# 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:

1. Detect Python — Checks venv, system Python, and the `py` launcher in order.
2. Bootstrap environment — Creates a virtual environment and installs dependencies if missing.
3. Create data directories — Sets up `data/results`, `data/evidence`, `data/reports`, and `data/logs`.
4. 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.

1. 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.

2. 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.

3. Enter target(s)

   Specify one or more IP addresses, hostnames, or CIDR ranges. Community tier is limited to 16 targets per scan.

4. Select scan depth

   Choose Quick (fast, fewer checks) or Standard (thorough). Deep scans require Pro tier or above.

5. Launch the scan

   The platform starts scanning and displays real-time progress. Findings appear as they are discovered.

6. 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:

1. Review severity, CVSS, EPSS, and KEV status to prioritize
2. Check SSVC decision (Act / Attend / Track) for stakeholder guidance
3. Use AI analysis for remediation recommendations
4. Assign to remediation tracking
5. 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