Knowledge Base / User Guide

User Guide

This guide covers everything you need to operate the Donjon Platform as an end user, from launching the platform through generating compliance reports.

Getting Started

Installation

Donjon supports three deployment modes. The platform auto-detects its environment on launch.

Mode	Detection	Cloud	AI	TUI
Portable (USB)	USB mount detected	Disabled	Template only	Full
Installed	Default (fixed system)	All providers	All backends	Full
CI/CD	CI env vars detected	All providers	All backends	Headless

Linux / macOS

# Clone the repository
git clone https://github.com/DonjonSec/donjon-platform.git
cd donjon-platform

# Set up Python environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Populate vulnerability intelligence (optional, recommended)
python3 bin/update-intel.py --quick     # ~2 min: KEV + EPSS + 14-day NVD

# Launch
python3 bin/donjon-launcher

Windows

REM Clone the repository
git clone https://github.com/DonjonSec/donjon-platform.git
cd donjon-platform

REM Run setup (creates venv, installs deps)
bin\setup-windows.bat

REM Populate vulnerability intelligence (optional)
python3 bin\update-intel.py --quick

REM Launch
bin\donjon-launcher.bat

PowerShell Alternative

You can also use bin\donjon-launcher.ps1 on Windows. If you get an execution policy error, run: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

First Launch

On first launch, the PowerShell launcher will automatically:

Detect Python — Checks venv, system Python, and the py launcher in order.
Bootstrap environment — Creates a virtual environment and installs dependencies if missing.
Create data directories — Sets up data/results, data/evidence, data/reports, and data/logs.
Launch the TUI — Opens the terminal user interface with the main menu.

Running Your First Scan

Follow these steps to execute your first vulnerability scan.

Select "Scan Center" from the main menu
The TUI main menu presents all available operations. Navigate to the Scan Center tab to configure and launch scans.
Choose a scanner type
Community tier includes 7 core scanners: network, vulnerability, web, ssl, windows, linux, and compliance. Pro and above unlock all scanner types.
Enter target(s)
Specify one or more IP addresses, hostnames, or CIDR ranges. Community tier is limited to 16 targets per scan.
Select scan depth
Choose Quick (fast, fewer checks) or Standard (thorough). Deep scans require Pro tier or above.
Launch the scan
The platform starts scanning and displays real-time progress. Findings appear as they are discovered.
Review results
When the scan completes, a summary is displayed with finding counts by severity. Detailed results are stored in the evidence database.

Authorization Required

Only scan networks and systems you have explicit written authorization to test. Unauthorized scanning may violate laws and regulations.

Understanding Scan Results

Severity Levels

Severity	CVSS Range	Description
CRITICAL	9.0 - 10.0	Immediate exploitation risk. Requires urgent remediation.
HIGH	7.0 - 8.9	Significant risk. Should be addressed within days.
MEDIUM	4.0 - 6.9	Moderate risk. Plan remediation within weeks.
LOW	0.1 - 3.9	Minor risk. Address during regular maintenance.
INFO	0.0	Informational only. No direct security impact.

Intelligence Enrichment

Each finding is automatically enriched with data from 7 intelligence sources (803K+ entries):

CVSS Score — Common Vulnerability Scoring System severity rating
EPSS Score — Exploit Prediction Scoring System (probability of exploitation in 30 days)
CISA KEV — Whether the CVE is on the Known Exploited Vulnerabilities catalog
SSVC Decision — Stakeholder-Specific Vulnerability Categorization (Act/Attend/Track)
Exploit References — Links to Exploit-DB, Metasploit, and Nuclei templates

FAIR Risk Quantification

Donjon v7.0 includes FAIR risk quantification that translates findings into dollar-denominated risk estimates:

Monte Carlo simulation (10,000 iterations) for Annualized Loss Expectancy (ALE)
Maps EPSS, KEV, and CVSS scores to FAIR loss factors
Industry benchmarks from IBM/Ponemon 2025 for 8 verticals
Results shown as ranges (10th/50th/90th percentile), never point estimates
Data quality score (0-100%) accompanies every estimate

Working with Findings

Viewing Findings

All findings are stored in the SQLite evidence database. You can browse findings through:

TUI Dashboard — Interactive terminal-based findings browser
Web Dashboard — HTML dashboard at https://localhost:8443
API — GET /api/v1/findings for programmatic access

Triaging Findings

Findings can be triaged using the following workflow:

Review severity, CVSS, EPSS, and KEV status to prioritize
Check SSVC decision (Act / Attend / Track) for stakeholder guidance
Use AI analysis for remediation recommendations
Assign to remediation tracking
Create risk exceptions for accepted risks (with approval workflow)

Remediation Tracking

The platform includes a built-in remediation tracker accessible via the API:

# Create a remediation item
POST /api/v1/remediation
{
    "finding_id": "f-12345",
    "assignee": "security-team",
    "priority": "high",
    "due_date": "2026-03-01"
}

# Update status
PUT /api/v1/remediation/<id>
{
    "status": "in_progress",
    "notes": "Patch scheduled for next maintenance window"
}

Export and Reporting

Available Formats

Format	Community	Pro+	Use Case
`CSV`	✓	✓	Spreadsheet analysis, data import
`JSON`	✓	✓	Programmatic processing, API integration
`HTML`	—	✓	Client-ready reports with branding
`PDF`	—	✓	Executive reports, compliance evidence
`SARIF`	—	✓	GitHub/GitLab security dashboard integration
`XML`	—	✓	SIEM import, legacy system integration

Exporting via API

# Export a scan session
GET /api/v1/scans/<session_id>/export?format=csv

# Bulk export via POST
POST /api/v1/export
{
    "format": "sarif",
    "session_ids": ["sess-001", "sess-002"],
    "include_evidence": true
}

Report Types

Executive Report — High-level summary with risk posture and recommendations (GET /api/v1/reports/executive)
Compliance Report — Framework-specific compliance status (GET /api/v1/reports/compliance/<framework>)
Delta Report — Trend analysis comparing scans across sessions
Risk Matrix — Visual risk heatmap (GET /api/v1/risks/matrix)

AI-Powered Analysis

AI Backends

Backend	Requirements	Description
Template	None (default)	Pre-built analysis templates. Works offline, no LLM needed.
Ollama	Local Ollama instance	Local LLM inference. No data leaves your machine.
OpenAI	API key	OpenAI-compatible API. Data sanitization strips IPs/hostnames.

AI Capabilities

Finding Analysis — Explain what a finding means and its potential impact
Triage Assistance — Prioritize a list of findings by risk
Remediation Guidance — Generate step-by-step fix instructions
Scan Summary — Auto-generate executive summaries (Pro+ only)
Free-Form Query — Ask any question about your findings or security posture

AI Quota

AI analysis is a Pro feature. Community Edition uses built-in template-based analysis (no LLM). Pro and above connect your own model — any OpenAI-compatible endpoint, a local model (Ollama / llama.cpp / vLLM), or your approved AI vendor — bring your own key, with no usage metering.

Using AI via the API

# Analyze a specific finding
POST /api/v1/ai/analyze
{
    "finding": {
        "title": "SQL Injection in Login Form",
        "severity": "CRITICAL",
        "cvss_score": 9.8
    }
}

# Ask a free-form question
POST /api/v1/ai/query
{
    "question": "What is the most critical finding and how should I fix it?",
    "context": { "session_id": "sess-001" }
}

AI Disclaimer

All AI output is tagged "AI-Generated - Verify Before Acting". AI analysis is advisory and should be validated by qualified security professionals before implementation.

Compliance Mapping

Supported Frameworks

Donjon maps findings to 10+ compliance frameworks. Community tier supports 3 frameworks simultaneously; Pro and above support unlimited frameworks.

NIST 800-53
HIPAA
PCI-DSS v4
ISO 27001:2022
SOC 1/2 Type II
CMMC
FedRAMP
GDPR
SOX

Generating Compliance Reports

# Get compliance report for a specific framework
GET /api/v1/reports/compliance/NIST-800-53

# Response includes control mappings, status, and evidence
{
    "framework": "NIST-800-53",
    "controls_assessed": 142,
    "controls_passing": 118,
    "controls_failing": 24,
    "compliance_score": 83.1,
    "findings_by_control": [ ... ]
}

Dashboard Overview

Web Dashboard

The web dashboard runs on https://localhost:8443 and provides a comprehensive view of your security posture. It features five main tabs:

Scan Center — Configure and launch scans, view active scans and history
Schedules — Manage scheduled/recurring scans (Pro+)
Notifications — Configure alert channels (email, webhook, Slack, Teams)
AI Assistant — Interactive AI analysis interface
Settings — License, configuration, and platform management

Platform Stats

The GET /api/v1/stats endpoint returns a comprehensive overview:

Total scans run, findings count, findings by severity
Active scan sessions
AI query usage and quota
License tier and status
Platform health and uptime

Keyboard Shortcuts and TUI Navigation

TUI Navigation

Key	Action
`Tab`	Switch between sections
`↑` / `↓`	Navigate menu items
`Enter`	Select / Confirm
`Esc`	Back / Cancel
`q`	Quit application
`?`	Show help
`/`	Search / Filter
`r`	Refresh current view

Scan Controls

Key	Action
`s`	Start a new scan
`Ctrl`+`c`	Cancel running scan
`e`	Export results
`d`	View finding details
`a`	AI analysis of selected finding