Skip to content

CLI and API Reference

CLI entrypoints

  • Python package script: cis-tool
  • Built binary name in release artifacts: typically cis-hardening-tool (Linux/AppImage/DEB) and cis-hardening-tool-standalone.exe (Windows)

Privilege model

The CLI elevates privileges for most operations:

  • Linux: re-execs with sudo unless command is explicitly non-root (--help, history, status, logs, stop, --version)
  • Windows: attempts elevation with ShellExecuteW(..., "runas", ...)

Global flags

  • --json — output results in JSON format (available on scan, history, tools, findings commands)
  • --exit-code — exit with non-zero status when findings are present
  • --quiet — suppress informational output; only emit results
  • --verbose — increase output verbosity (debug-level logging)
  • --only-failures — filter output to show only failed/non-compliant findings

Core CLI commands

cis-tool (no subcommand)

Starts interactive menu with options for server, tools, quick scan, and history.

cis-tool scan

Options: - --tools, -t list/comma-separated tool names - --non-interactive - --export, -e (pdf/html) - --output, -o output path

Behavior: - Creates scan_id - Saves running/completed/failed state in SQLite (includes completed_at timestamp) - Dispatches to Linux/Windows wrappers per selected tool - Per-tool log files are written during execution (see scan_logger.py)

cis-tool history

  • No args: show previous scans
  • --id <scan_id>: export report for that scan
  • --export, --output control format/path

cis-tool report-formats

Non-interactive command that prints:

  1. Per-tool raw output artifacts/formats for the current host OS
  2. Consolidated export formats supported by CLI report generation

Options:

  • --all-platforms: include Linux + Windows matrix rows regardless of current host

cis-tool doctor

Diagnostic command that checks system readiness: - Verifies required dependencies and tool availability - Reports OS detection results (via core/os_detect.py) - Validates database connectivity and schema - Checks runtime home directory permissions

cis-tool ai

AI-powered scan analysis and summarization: - summarize: Generate an AI summary for a scan (defaults to latest). Options: --id, --force (regenerate even if cached). Summary is saved to db and printed inline as Markdown. - status: Show current AI provider configuration (Provider, Model, API Key presence). - config: Configure AI provider settings. Options: --provider, --model, --api-key (prompts interactively if not provided).

cis-tool findings

Query and display scan findings: - --id <scan_id>: show findings for a specific scan - Supports --json, --only-failures, --exit-code global flags - Retrieves parsed findings from the scan results

cis-tool tools status

Returns current install state of all known tools (Installed, Missing, Incompatible).

cis-tool tools install

  • Accepts explicit tool list or installs all compatible missing tools
  • Uses ToolManager package-manager aware logic

cis-tool server ...

  • run: foreground FastAPI/uvicorn
  • start: background process, logs to <runtime_home>/logs/web_server_<YYYYmmdd_HHMMSS>.log
  • status
  • logs: live tail
  • stop

CLI package structure

The CLI has been refactored from a single cli.py into a cli/ package with 8 modules for maintainability: - cli/__init__.py — package entry and main dispatcher - Individual modules for scan, history, server, tools, doctor, findings, report-formats, and interactive menu

API endpoints

Server/base routes

  • GET / → dashboard HTML (frontend/index.html)
  • GET /api/system/info → detected OS string
  • WS /ws, WS /ws/ → live updates/logs
  • legacy: WS /scan/ws and WS /scan/ws/ sends refresh message and closes

Health endpoint

  • GET /api/health — returns server health status and version info

Scan router (api/scan.py)

  • POST /scan/start
  • Body: { "tools": ["lynis", "openscap"] } (optional)
  • Defaults by OS if omitted
  • GET /scan/status
  • Supports pagination: ?limit=N&offset=M
  • Returns paginated list of scans with total count
  • GET /scan/{scan_id}/report (consolidated report download)
  • GET /scan/{scan_id}/findings — returns parsed findings for a scan
  • GET /scan/{scan_id}/timeline — returns chronological scan events/progress
  • DELETE /scan/{scan_id} — delete a scan record and its associated data

Tools router (api/tools.py)

  • GET /tools/status
  • POST /tools/install with { "tools": ["..."] }

AI router (api/ai.py)

  • GET /ai/settings — Returns currently configured AI settings (safely omitting API key value).
  • POST /ai/settings — Updates AI settings.
  • GET /ai/summary/{scan_id} — Retrieves inline summary for a scan (generates if missing).
  • POST /ai/summary/{scan_id} — Forces regeneration of AI summary.

Report router (api/report.py)

  • GET /report/{scan_id}
  • GET /report/download/{scan_id}/{tool}/{file_type}
  • GET /report/session-log/{scan_id}

Data model highlights

DB table: scans

  • id, timestamp, os_type, tools, status, results, error, completed_at

DB table: scan_logs

  • id, scan_id, tool, timestamp, message

Log files

  • NDJSON lines in <runtime_home>/logs/scans/<scan_id>/<YYYYmmdd_HHMMSS>.ndjson
  • Per-tool log files in <runtime_home>/logs/scans/<scan_id>/<tool_name>.log

Report folders

  • Per-run scan folder: <runtime_home>/reports/<YYYYmmdd_HHMMSS>__<scan_id>/...

Runtime home

  • Linux/macOS: ~/.cis-sentinel
  • Windows: %LOCALAPPDATA%\\cis-sentinel
  • Override: CIS_SENTINEL_HOME

Exit behavior and operational notes

  • Some tools use non-zero codes for findings (e.g., OpenSCAP/Lynis); command streaming treats those as non-fatal where expected.
  • Tool install operations are best-effort and may partially succeed.