Skip to content

Complete Documentation (Comprehensive)

This document is the single, high-detail reference for architecture, usage, operations, testing, packaging, and known failure handling.

For role-oriented quick access:

1) Project goals

CIS Hardening Tool is an orchestration layer over security scanners. It does not replace scanner engines; it installs, invokes, normalizes, and reports their results across Linux and Windows.

Primary goals:

  1. Unified execution model across heterogeneous operating systems.
  2. Best-effort installation and scanning with graceful degradation.
  3. Unified report output from mixed tool formats.
  4. Practical artifact-level validation via VMs before release acceptance.

2) Runtime modes

  1. Interactive CLI (cis-tool with no subcommand)
  2. Direct CLI commands (scan, tools, history, server, doctor, findings)
  3. FastAPI server + WebSocket UI (main.py, cis-tool server run)
  4. Packaged binaries (.deb, AppImage, Windows standalone/installer)

The CLI is structured as a cli/ package (8 modules) rather than a single cli.py file. Global flags include --json, --exit-code, --quiet, --verbose, and --only-failures.

3) Tool support overview

See full matrix at TOOL_MATRIX.md.

  • Linux: OpenSCAP, Lynis, CIS-CAT Lite, USG (Ubuntu only)
  • Windows: HardeningKitty, CIS-CAT Lite, SCT (manual asset)

4) Key data paths

  • SQLite DB: cis_history.db (lazy-initialized on first access)
  • Per-scan artifacts: <runtime_home>/reports/<YYYYmmdd_HHMMSS>__<scan_id>/...
  • Session logs: <runtime_home>/logs/scans/<scan_id>/<YYYYmmdd_HHMMSS>.ndjson
  • Per-tool logs: <runtime_home>/logs/scans/<scan_id>/<tool_name>.log
  • Background server logs: <runtime_home>/logs/web_server_<YYYYmmdd_HHMMSS>.log
  • VM validation artifacts: vms/artifacts/

5) Security and privilege model

  • Linux scan/install flows generally require root; CLI re-execs with sudo for non-whitelisted commands.
  • Windows uses elevation request (runas) path.
  • Network operations include release/tool download and scanner content retrieval.
  • Local DB and logs are file-based; protect host filesystem permissions accordingly.

6) Install and run quick recipes

Dev mode

uv pip install -e .
cis-tool --version
cis-tool tools status
cis-tool scan --tools lynis,openscap --non-interactive --export pdf --output report.pdf

Server mode

cis-tool server start --detach
cis-tool server status
cis-tool server logs
cis-tool server stop

Release artifact validation

./scripts/run_automated_vm_tests.sh v1.1.2

7) Design principles used across the codebase

  1. Best-effort installation
  2. Tool installs try per-package and continue on partial failure.
  3. Cross-distro adaptability
  4. Package mappings are distro/version aware with fallbacks.
  5. Safe subprocess environment
  6. Sanitized env avoids AppImage/PyInstaller linker pollution.
  7. Operational observability
  8. Rich console logs, API/log streaming, VM per-target logs.
  9. Packaging reproducibility
  10. CI artifacts built in pinned base environments.

8) Documentation map by audience

Platform/infra engineers

Security engineers/compliance operators

Maintainers/contributors

9) What changed recently (important)

  1. Debian 11 VM path removed from active matrix.
  2. Installer robustness improved for distro/version-specific package drift.
  3. Windows CIS-CAT Java prerequisite moved into install logic.
  4. VM runners updated to collect/export PDFs and improve diagnostics.
  5. Packaging includes frontend/template data for standalone runtime correctness.
  6. CLI refactored from single cli.py into cli/ package (8 modules).
  7. Reporter refactored: report_gen.py deleted and merged into reporter.py; parsing logic extracted to core/parsers/ package.
  8. New core modules: core/deps.py, core/constants.py, core/os_detect.py, core/ws_patch.py.
  9. New CLI commands: doctor (diagnostics), findings (query scan findings).
  10. New API endpoints: GET /api/health, GET /scan/{id}/findings, GET /scan/{id}/timeline, DELETE /scan/{id}, paginated GET /scan/status.
  11. Frontend redesigned as multi-page SPA with hash-based routing and modal log viewer.
  12. Docker build uses uv multi-stage; Dockerfile.rocky removed; single Dockerfile.
  13. setup.py removed; pyproject.toml is the sole build configuration.
  14. Database: lazy initialization, completed_at column, delete_scan helper, pagination support.
  15. scan_logger.py: per-tool log files.
  16. logger.py: LOG_FORMAT=json support.
  17. CIS-CAT Linux logic extracted to wrappers/ciscat_linux.py.

10) Source of truth

If docs and behavior diverge, code is authoritative. Start from:

  • cli/ (package with 8 modules)
  • main.py
  • core/tool_manager.py
  • core/tools_config.py
  • core/constants.py
  • core/deps.py
  • core/os_detect.py
  • core/parsers/ (report parsing package)
  • core/wrappers/linux.py
  • core/wrappers/windows.py
  • core/wrappers/ciscat_linux.py
  • scripts/*
  • .github/workflows/release.yml