cis-benchmarks/README.md

# cis-benchmarks

Local repository for CIS benchmark source PDFs and plain-text extracts.

## Layout
- `pdf/`: original benchmark PDFs
- `text/`: `pdftotext -layout` extracts for search and parsing
- `docs/`: assessment notes and remediation checklists
- `bin/`: helper scripts

## Current Benchmarks
- AlmaLinux OS 8, 9, 10
- Debian Linux 12, 13
- Docker
- Docker Community Edition
- NGINX
- Red Hat Enterprise Linux 9, 10
- Ubuntu Linux 22.04 LTS, 24.04 LTS
- Visual Studio Code GPO

## Refresh Text Extracts
```bash
./bin/refresh_text_extracts.sh
```

This keeps the source PDFs in `pdf/` and rewrites matching `.txt` files in `text/`.

## Benchmark Checker
The repo now includes a generic checker that parses a CIS text export and runs the
documented `Audit:` procedures for automated controls.

List parsed controls from a benchmark:
```bash
./bin/cis-check text/CIS_AlmaLinux_OS_9_Benchmark_v2.0.0.txt --list-controls
```

Run a single control:
```bash
./bin/cis-check text/CIS_AlmaLinux_OS_9_Benchmark_v2.0.0.txt --control 1.3.1.5
```

Run all automated Level 1 server checks and emit JSON:
```bash
./bin/cis-check text/CIS_AlmaLinux_OS_9_Benchmark_v2.0.0.txt \
  --profile "Level 1 - Server" \
  --format json
```

Generate both machine-readable and human-readable reports in one pass:
```bash
./bin/cis-check text/CIS_AlmaLinux_OS_9_Benchmark_v2.0.0.txt \
  --profile "Level 1 - Server" \
  --manual \
  --report-dir reports/almalinux9
```

Generate only the remediation guide from an existing audit JSON:
```bash
./bin/cis-check \
  --report-json reports/almalinux9/audit-report.json \
  --guide-output reports/almalinux9/remediation-guide.md
```

Record an approved exception live while reviewing:
```bash
./bin/cis-check \
  --exceptions-file reports/almalinux9/exceptions.json \
  --host lynx \
  --approve-exception 3.3.1 \
  --exception-reason "Docker networking requires IP forwarding" \
  --exception-notes "Reviewed during CIS audit"
```

Then rerun the report with the same exceptions file:
```bash
./bin/cis-check text/CIS_AlmaLinux_OS_9_Benchmark_v2.0.0.txt \
  --host lynx \
  --exceptions-file reports/almalinux9/exceptions.json \
  --report-dir reports/almalinux9
```

Notes:
- Automated controls with embedded shell audit scripts are executed directly with `bash`.
- Automated controls with simple command examples are executed command-by-command and
  evaluated against expected output in the benchmark text.
- Manual controls are excluded by default and reported as `MANUAL` when `--manual` is used.
- `--report-dir` writes `audit-report.json`, `audit-report.md`, and `remediation-guide.md`.
- `--format remediation` prints the remediation guide directly.
- The markdown report includes benchmark-provided remediation text for failed, error, review,
  and manual controls.
- The remediation guide groups items by subsystem and separates execution blockers from
  direct compliance gaps.
- The remediation guide also flags likely accepted exceptions such as structural partition
  requirements or container-driven forwarding settings for human approval.
- Approved host-specific exceptions can be stored in a local JSON file and are then shown in
  the audit and remediation outputs on future runs.
- Run the checker on the target host, ideally as `root`, because many CIS audits depend on
  host-specific binaries, privileged files, and live system state.

## Host Assessments
- `docs/lynx-almalinux9-remediation-checklist.md`