124 lines
3.8 KiB
Markdown
124 lines
3.8 KiB
Markdown
# 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.
|