Getting Started¶

1) What this project is¶

CIS Hardening Tool orchestrates multiple security scanners and presents their output in a unified way.

• Linux: openscap, lynis, usg, ciscat
• Windows: hardeningkitty, sct, ciscat

It supports: - Interactive CLI (cis-tool) with subcommands including doctor and findings - Direct CLI subcommands (scan, tools, server, history, doctor, findings) - FastAPI web server + multi-page SPA dashboard (main.py) - PDF/HTML report generation - JSON output mode (--json), exit-code control, quiet/verbose flags

2) Installation options¶

A. Development install (recommended while contributing)¶

Requires uv. There is no setup.py; the project is configured entirely via pyproject.toml (includes distro dependency for Linux detection).

uv pip install -e .

Note: Building the tiktoken dependency from source (if pre-built wheels aren't available for your architecture) requires the Rust compiler. Install it via curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh.

Optional dev dependencies:

uv pip install -e ".[dev]"

B. Docker¶

A unified multi-stage Dockerfile uses uv for fast, reproducible builds:

docker build -t cis-tool .
docker run --rm -p 8000:8000 cis-tool server run

C. Release artifact install (for validation)¶

Download release artifacts and run via package/AppImage/EXE as appropriate.

Helper scripts: - scripts/install.sh (Linux) - scripts/install.ps1 (Windows)

3) Common commands¶

Interactive menu¶

cis-tool

Version¶

cis-tool --version          # version read from importlib.metadata

Environment health check¶

cis-tool doctor             # verify tools, paths, DB connectivity

Install tools¶

cis-tool tools status
cis-tool tools install lynis openscap ciscat -y

Run scans¶

cis-tool scan --tools lynis,openscap --non-interactive
cis-tool scan --json                   # JSON output
cis-tool scan --exit-code              # non-zero exit on failures
cis-tool scan --quiet                  # suppress progress output
cis-tool scan --verbose                # extra detail
cis-tool scan --only-failures          # show only failed checks

View findings for a scan¶

cis-tool findings <scan_id>

Export report for an existing scan¶

cis-tool history --id <scan_id> --export pdf --output report.pdf

Server control¶

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

4) Running the web app¶

python main.py

Or via CLI wrapper:

cis-tool server run

Default URL: http://localhost:8000

The frontend is a multi-page SPA with hash routing. Pages include:

• Dashboard -- KPI cards, compliance overview
• Scans -- scan list with pagination, per-scan inline logs, modal log viewer
• Tools -- tool status and install controls
• Logs -- aggregated log browser

Additional frontend features: dark/light theme toggle, toast notifications, CSV/JSON export.

5) Key file locations¶

6) Database and reports¶

• Runtime home (Linux/macOS): ~/.cis-sentinel
• Runtime home (Windows): %LOCALAPPDATA%\\cis-sentinel
• Override runtime home: CIS_SENTINEL_HOME
• SQLite DB: <runtime_home>/cis_history.db (or CIS_DB_PATH override)
• Lazy initialization (no module-level init_db())
• Supports completed_at column, delete_scan(), count_scans(), pagination
• Scan reports: <runtime_home>/reports/<YYYYmmdd_HHMMSS>__<scan_id>/...
• Session logs: <runtime_home>/logs/scans/<scan_id>/<tool_name>.ndjson (per-tool log files, lazy dir init)
• Server logs: <runtime_home>/logs/web_server_<YYYYmmdd_HHMMSS>.log
• JSON logging: set LOG_FORMAT=json environment variable

7) Build/test shortcuts¶

Use make targets:

• make test
• make test-unit
• make lint
• make security
• make run-cli
• make run-server

8) VM validation flow¶

./scripts/run_automated_vm_tests.sh vX.Y.Z

This downloads release artifacts to vms/artifacts/, provisions VMs, executes in-VM test runners, and stores logs and reports.