# Infrastructure Maintenance Scripts

Ansible-based maintenance scripts for infrastructure operations across multiple Linux distributions.

## Supported Operating Systems

- Ubuntu 20.04, 22.04, 24.04
- Debian 11, 12, 13
- Alpine Linux

## Prerequisites

- Ansible 2.15 or higher
- Python 3.8+ on target hosts
- SSH access to target hosts
- Sudo privileges on target hosts

## Installation

1. Clone the repository:
```bash
git clone git@git.puddi.ng:public-infra/maintenance-scripts.git
cd maintenance-scripts
```

2. Install required Ansible collections:
```bash
ansible-galaxy collection install -r requirements.yml
```

3. Configure inventory:
```bash
vim inventory/hosts.ini
```

## Available Playbooks

### 1. CVE Scanner - `playbooks/scan_cves.yml`

Identifies packages with CVE vulnerabilities using the NIST NVD database.

**Features:**
- Parses installed packages across supported OS distributions
- Queries NIST NVD CVE database via API
- Correlates vulnerabilities with installed packages
- Outputs JSON report with findings

**Usage:**
```bash
ansible-playbook playbooks/scan_cves.yml -i inventory/hosts.ini
```

**Output:**
- JSON report saved to `/tmp/cve_report_*.json`
- Contains package name, version, CVE IDs, severity, and host information

### 2. Package Update Checker - `playbooks/check_updates.yml`

Checks for available package updates and assesses potential risks using OpenAI.

**Features:**
- Lists upgradable packages across supported distributions
- Uses OpenAI API to identify potential breaking changes
- Separates safe updates from risky ones
- Provides recommendation on whether to proceed

**Prerequisites:**
- Set `OPENAI_API_KEY` environment variable

**Usage:**
```bash
export OPENAI_API_KEY="your-openai-api-key"
ansible-playbook playbooks/check_updates.yml -i inventory/hosts.ini
```

**Output:**
- JSON report saved to `/tmp/update_report_*.json`
- Lists safe and risky updates with risk assessment
- Provides boolean flag for automatic update safety

### 3. Docker Cleanup - `playbooks/cleanup_docker.yml`

Cleans up Docker resources including images, containers, and build cache.

**Features:**
- Removes dangling images
- Removes stopped containers
- Cleans build cache
- Provides before/after disk usage comparison
- Optional volume cleanup (disabled by default)

**Usage:**
```bash
ansible-playbook playbooks/cleanup_docker.yml -i inventory/hosts.ini
```

**Output:**
- JSON report saved to `/tmp/docker_cleanup_report_*.json`
- Shows disk space reclaimed for each resource type

### 4. Log Archiver - `playbooks/archive_logs.yml`

Archives rotated log files and transfers them to remote storage.

**Features:**
- Archives gzipped rotated logs from `/var/log`
- Organizes logs by hostname, IP, and date
- Transfers archives to remote storage location
- Cleans up original logs after successful transfer
- Generates metadata for each archive

**Prerequisites:**
- Set `REMOTE_STORAGE_PATH` environment variable (defaults to `/mnt/log-archive`)

**Usage:**
```bash
export REMOTE_STORAGE_PATH="/path/to/log-storage"
ansible-playbook playbooks/archive_logs.yml -i inventory/hosts.ini
```

**Output:**
- JSON report saved to `/tmp/log_archive_report_*.json`
- Archives stored with structure: `YEAR/MONTH/DAY/logs_HOSTNAME_IP_DATE.tar.gz`

### 5. Disk Space Analyzer - `playbooks/analyze_disk_space.yml`

Analyzes disk usage and identifies directories consuming excessive space.

**Features:**
- Scans multiple paths with configurable depth (default 5)
- Identifies directories larger than threshold (default 1GB)
- Lists large files exceeding threshold
- Provides disk and inode usage statistics
- Alerts on high disk or inode usage

**Usage:**
```bash
ansible-playbook playbooks/analyze_disk_space.yml -i inventory/hosts.ini
```

**Output:**
- JSON report saved to `/tmp/disk_space_report_*.json`
- Lists large directories and files sorted by size
- Includes disk and inode usage alerts

## Configuration

### Environment Variables

- `OPENAI_API_KEY`: Required for package update risk assessment
- `REMOTE_STORAGE_PATH`: Path for log archive storage (default: `/mnt/log-archive`)

### Inventory Structure

The inventory file uses INI format with groups:

```ini
[webservers]
web1.example.com ansible_host=192.168.1.10

[dbservers]
db1.example.com ansible_host=192.168.1.20
```

### SSH Configuration

Configure SSH access in `ansible.cfg` or use SSH config file:
```ini
[defaults]
host_key_checking = False
```

## Running Playbooks

### Target specific hosts:
```bash
ansible-playbook playbooks/scan_cves.yml -i inventory/hosts.ini -l web1.example.com
```

### Target groups:
```bash
ansible-playbook playbooks/scan_cves.yml -i inventory/hosts.ini -l webservers
```

### Run with extra variables:
```bash
ansible-playbook playbooks/analyze_disk_space.yml -i inventory/hosts.ini -e "size_threshold_gb=5"
```

### Limit concurrency:
```bash
ansible-playbook playbooks/scan_cves.yml -i inventory/hosts.ini -f 10
```

## Output Locations

All playbooks generate JSON reports in `/tmp/` with timestamps:
- CVE reports: `/tmp/cve_report_TIMESTAMP.json`
- Update reports: `/tmp/update_report_TIMESTAMP.json`
- Docker cleanup reports: `/tmp/docker_cleanup_report_TIMESTAMP.json`
- Log archive reports: `/tmp/log_archive_report_TIMESTAMP.json`
- Disk space reports: `/tmp/disk_space_report_TIMESTAMP.json`

## Best Practices

1. **Test on non-production hosts first**: Always test playbooks on a subset of hosts
2. **Monitor output**: Review reports before taking automated actions
3. **Schedule regular runs**: Use cron or Jenkins for periodic scans
4. **Backup before updates**: Ensure backups exist before running update playbooks
5. **Review risky updates**: Manually review packages marked as risky before updating

## Troubleshooting

### Connection issues
```bash
ansible all -i inventory/hosts.ini -m ping
```

### Privilege issues
Ensure the user has sudo privileges:
```bash
ansible-playbook playbooks/scan_cves.yml -i inventory/hosts.ini -u ansible_user --become
```

### Collection not found
Install required collections:
```bash
ansible-galaxy collection install -r requirements.yml
```

### Python module issues
Ensure Python 3 is available:
```bash
ansible all -i inventory/hosts.ini -m shell -a "python3 --version"
```

## Contributing

1. Follow Ansible best practices
2. Use Ansible modules instead of shell commands when possible
3. Ensure cross-platform compatibility
4. Write clear and descriptive task names
5. Add error handling where appropriate
6. Test on all supported OS distributions

## License

Copyright (c) 2026. All rights reserved.