Architecture and Code Map¶

High-level flow¶

Diagram source: architecture-overview.mmd

1. User triggers scan (CLI or API)
2. ToolManager (singleton via core/deps.py) verifies/installs required tools
3. OS detection via core/os_detect.py
4. OS-specific wrapper executes scanner (LinuxWrapper / WindowsWrapper)
5. CIS-CAT logic on Linux extracted to core/wrappers/ciscat_linux.py
6. Logs are streamed per-tool and persisted (core/scan_logger.py, DB)
7. Results are stored in SQLite (core/database.py) with lazy init, pagination, completed_at, and delete_scan()
8. Tool output is parsed by core/parsers/ (oscap, lynis, hardeningkitty, ciscat)
9. Reports are generated by slim orchestrator core/reporter.py (formerly split across reporter.py + report_gen.py, now merged)
10. Websocket broadcasts status/log updates to frontend (core/comms.py, patched via core/ws_patch.py)

Main modules¶

cli/ (package -- replaces former monolithic cli.py)¶

The CLI has been split into a package with focused submodules:

New top-level commands: cis-tool doctor, cis-tool findings <id>.

main.py¶

• FastAPI app setup
• Routers mounted from api/
• Static asset mounting (frontend/css, frontend/js)
• WebSocket endpoints and middleware

New shared modules in core/¶

core/tool_manager.py¶

• Package manager abstraction (apt, dnf/yum, apk, pacman, zypper)
• Version-aware package mapping via core/tools_config.py
• Windows Java prerequisite bootstrap for CIS-CAT
• Sanitized subprocess env for packaged runtime compatibility

core/wrappers/linux.py¶

• OpenSCAP content discovery and profile selection
• Runs openscap, lynis, usg
• CIS-CAT logic extracted to core/wrappers/ciscat_linux.py

core/wrappers/ciscat_linux.py (new)¶

• CIS-CAT benchmark selection and execution on Linux
• Extracted from linux.py for clarity

core/wrappers/windows.py¶

• Runs HardeningKitty (PowerShell)
• Runs SCT (LGPO.exe) and CIS-CAT batch launcher

core/parsers/ (new package -- replaces parsing logic formerly in reporter.py)¶

core/reporter.py (slim orchestrator)¶

• Aggregates parsed findings from core/parsers/*
• Generates consolidated PDF/HTML reports
• report_gen.py has been merged into this module and deleted
• Handles missing-tool report artifacts gracefully by inserting explicit error findings

core/database.py¶

• SQLite with WAL
• Lazy initialization (no module-level init_db() call)
• completed_at column for scan completion tracking
• delete_scan(), count_scans(), pagination support

core/scan_logger.py¶

• Per-tool log files (not a single file per scan)
• Lazy directory initialization

core/logger.py¶

• Standard logging setup
• JSON logging mode via LOG_FORMAT=json environment variable

api/*¶

• scan.py: start/status/report, paginated status, DELETE /scan/{id}, GET /scan/{id}/findings, GET /scan/{id}/timeline, GET /scan/{id}/logs
• tools.py: install/status
• report.py: report/file download endpoints
• GET /api/health endpoint

Version¶

The package version is read from importlib.metadata at runtime (not hardcoded). It is defined in pyproject.toml.

Frontend¶

Multi-page SPA with hash-based routing:

Additional features: - Dark/light theme toggle - Toast notifications - CSV/JSON export - Consumes REST + WebSocket for real-time updates - Static assets under frontend/css and frontend/js

Packaging and release¶

• Project metadata in pyproject.toml (no setup.py; distro added as dependency)
• Docker: unified multi-stage Dockerfile using uv for fast, reproducible builds
• .github/workflows/release.yml builds:
• Linux DEB (Ubuntu 18.04 container for glibc compatibility)
• Linux AppImage
• Windows standalone EXE + installer
• PyInstaller includes both templates and frontend resources

Deleted files¶

Test/validation layers¶

• Unit/API tests in tests/
• VM artifact validation pipeline in scripts/ + Vagrantfile
• Multi-OS provisioning with per-VM test runners