# CIS Benchmark Auditor

Automated security auditing tool for CIS Benchmarks. Runs checks against a
local machine or a remote host via SSH and produces a colour-coded XLSX report
showing passed, failed, and manual-review items with remediation guidance.

## Supported benchmarks

| Benchmark | Version | Checks | Implementation |
|-----------|---------|--------|----------------|
| CIS NGINX | v3.0.0 | 44 | Hand-coded Python functions |
| CIS Debian Linux 13 | v1.0.0 | 343 | Data-driven XLSX parser |

## Requirements

```
pip install -r requirements.txt
```

`paramiko` is only needed for SSH mode. The rest of the standard library covers
local execution.

## Usage

### List available profiles

```bash
python main.py nginx --list-profiles
python main.py debian --list-profiles --benchmark-file CIS_Debian_Linux_13_Benchmark_v1.0.0.xlsx
```

### Audit local machine

```bash
python main.py nginx  --profile "Level 1 - Webserver"

python main.py debian --profile "Level 1 - Server" \
    --benchmark-file CIS_Debian_Linux_13_Benchmark_v1.0.0.xlsx
```

### Audit remote host via SSH

```bash
python main.py debian \
    --mode ssh --host 10.0.0.5 --user admin --key ~/.ssh/id_rsa \
    --profile "Level 1 - Server" \
    --benchmark-file CIS_Debian_Linux_13_Benchmark_v1.0.0.xlsx
```

### Run specific checks only

```bash
python main.py debian \
    --profile "Level 1 - Server" \
    --benchmark-file CIS_Debian_Linux_13_Benchmark_v1.0.0.xlsx \
    --checks 1.1.2.1.1,2.1.1,5.1.1
```

### All options

```
positional:
  benchmark             nginx | debian

options:
  --benchmark-file XLSX Path to benchmark XLSX (required for: debian)
  --mode {local,ssh}    Execution mode (default: local)
  --host HOST           SSH host
  --port PORT           SSH port (default: 22)
  --user USER           SSH username (default: root)
  --key KEY             Path to SSH private key
  --password PASSWORD   SSH password
  --profile PROFILE     Profile to audit
  --checks CHECKS       Comma-separated check IDs
  --list-profiles       Print profiles and exit
  --output XLSX         Output report path (default: auto-named)
  --verbose, -v         Print check progress
```

## Report format

The XLSX output contains four sheets:

- **Summary** — total counts, timestamp, target host
- **Passed** — checks that passed with actual vs expected values
- **Failed** — checks that failed with actual vs expected values and remediation steps
- **Manual Review** — checks that require human judgment, with collected command output
- **Errors** (if any) — checks that could not be executed

## Project structure

```
main.py                         # CLI entry point (all benchmarks)
requirements.txt
cis_auditor/
  core/
    models.py                   # CheckResult, AuditReport dataclasses
    executor.py                 # LocalExecutor, SSHExecutor
    report.py                   # XLSX report generator
  benchmarks/
    base.py                     # CheckDefinition, BenchmarkInfo
    nginx/
      __init__.py               # Wraps hand-coded nginx_audit checks
    debian/
      __init__.py               # Lazy-load wrapper
      loader.py                 # XLSX parser → CheckDefinition objects
nginx_audit/                    # Hand-coded NGINX check functions (44 checks)
  checks.py
  executor.py
  models.py
  report.py
  runner.py
```

## Adding a new benchmark

1. Create `cis_auditor/benchmarks/<name>/`
2. Implement `loader.py` (data-driven from XLSX) or `checks.py` (hand-coded)
3. Expose `load(xlsx_path) -> BenchmarkInfo` in `__init__.py`
4. Add the name to `BENCHMARK_NAMES` in `main.py`

The `CheckDefinition.run()` method handles all four pass-condition types
(`empty_output`, `non_empty_output`, `contains_pass`, `manual`) automatically,
so new benchmarks only need to supply the audit script and the right condition.