Administrator Guide

This guide covers installation, deployment, configuration, license management, and platform administration for Donjon Platform v7.0.

Installation and Deployment

Windows Deployment

The recommended way to launch on Windows is with the PowerShell launcher or the batch file.

Option A: Batch File (simplest)

REM Navigate to the platform directory
cd C:\path\to\donjon-platform

REM Run setup (first time only)
bin\setup-windows.bat

REM Launch
bin\donjon-launcher.bat

Option B: PowerShell Launcher

# Set execution policy (first time only)
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

# Launch
.\bin\donjon-launcher.ps1

The PowerShell launcher (donjon-launcher.ps1) performs automatic bootstrapping:

1. Detects Python (venv first, then system python/python3, then py -3 launcher)
2. Creates a virtual environment if one does not exist
3. Installs dependencies from requirements.txt
4. Creates data directories (data/results, data/evidence, data/reports, data/logs)
5. Sets PYTHONPATH to include lib/
6. Launches the platform

Linux / macOS Deployment

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

# Setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Populate vulnerability intelligence
python3 bin/update-intel.py --quick     # Fast: KEV + EPSS + 14-day NVD (~2 min)
# OR full database with NVD API key (~2 hrs, 800K+ entries):
NVD_API_KEY=your-key python3 bin/update-intel.py

# Launch
python3 bin/donjon-launcher

Docker Deployment

# Build the image
docker build -t donjon:7.0 .

# Run with persistent data volume
docker run -d \
    --name donjon \
    -p 8443:8443 \
    -v donjon-data:/app/data \
    donjon:7.0

# View logs
docker logs -f donjon

Air-Gapped / USB Deployment

Donjon is designed for air-gapped environments. The platform auto-detects USB deployment mode.

1. Prepare on a connected machine

   Clone the repository, install dependencies, and populate the vulnerability intelligence database.

2. Copy to USB drive

   Copy the entire donjon-platform directory (including venv/ and data/vuln_db/) to a USB drive.

3. Run on the air-gapped machine

   Plug in the USB drive and launch directly. Cloud scanning is automatically disabled. AI defaults to the template backend (no network required).

   # Linux/macOS
   python3 /media/USB_DRIVE/donjon-platform/bin/donjon-launcher
   
   # Windows
   E:\donjon-platform\bin\donjon-launcher.bat

Configuration

Configuration File

The main configuration file is config/active/config.yaml.

# AI backend configuration
ai:
  provider: 'template'        # template | ollama | openai
  sanitize_external: true     # Strip IPs/hostnames for external LLMs
  ollama_url: 'http://localhost:11434'
  openai_model: 'gpt-4'

# Risk quantification
risk:
  industry: 'technology'      # Maps to IBM/Ponemon benchmarks
  monte_carlo_iterations: 10000

# Compliance frameworks to assess
compliance:
  frameworks:
    - 'NIST-800-53'
    - 'HIPAA'
    - 'PCI-DSS-v4'
    - 'ISO27001-2022'

# CI/CD security gate thresholds
cicd:
  security_gate:
    max_critical: 0
    max_high: 5

Environment Variables

Database Setup

SQLite (Default)

Donjon uses SQLite by default, with databases stored in the data/ directory. No configuration required.

• data/evidence/evidence.db — Scan sessions, findings, evidence
• data/vuln_db/vuln_intel.db — Vulnerability intelligence (803K+ entries)

PostgreSQL (Enterprise)

Enterprise tier supports PostgreSQL for multi-user environments:

# Set the database URL
export DONJON_DB_URL="postgresql://donjon:password@db-server:5432/donjon"

# Or in config.yaml
database:
  url: 'postgresql://donjon:password@db-server:5432/donjon'

AI Provider Configuration

ai:
  provider: 'template'

# Install Ollama and pull a model
ollama pull llama3

# Configure Donjon
ai:
  provider: 'ollama'
  ollama_url: 'http://localhost:11434'
  ollama_model: 'llama3'

ai:
  provider: 'openai'
  sanitize_external: true  # Always enable for external APIs
  openai_model: 'gpt-4'

# Set API key via environment variable
export OPENAI_API_KEY="sk-..."

Notification Channels

Configure alert delivery channels via the API or dashboard:

License Management

Tier Overview

Activating a License

1. Obtain a license file

   Purchase a license at donjonsec.com. You will receive a license.json file.

2. Place the license file

   Copy license.json to data/license.json in your platform directory.

3. Verify activation

   Restart the platform or call the license API:

   GET /api/v1/license
   # Response shows tier, organization, expiry, and validation status

You can also activate via the API:

POST /api/v1/license/activate
Content-Type: application/json

{
    "license_data": { /* full license.json contents */ }
}

Machine Fingerprinting

Licenses can be bound to a specific machine via fingerprinting. The fingerprint is a SHA-256 hash combining:

• MAC address (first available NIC)
• Hostname
• Platform identifier (OS + architecture)
• Processor string
• OS machine ID (Linux: /etc/machine-id; Windows: MachineGuid from registry)

Format: sha256:<64-char-hex-digest>

License Renewal and Transfer

• Renewal: Replace data/license.json with the new file and restart the platform or call POST /api/v1/license/activate.
• Transfer: Contact donjonsec.com support with your current license ID and the new machine fingerprint.

Air-Gap License Activation

1. Generate fingerprint on target machine

   Launch Donjon and note the machine fingerprint from the license page or run the fingerprint tool.

2. Request license on connected machine

   Submit the fingerprint to donjonsec.com for a machine-bound license.

3. Transfer license file

   Copy the received license.json to the air-gapped machine's data/ directory via USB or approved media.

4. Restart Donjon

   The platform verifies the license using dual ML-DSA-65 + Ed25519 signatures locally. No network call is required.

License Verification Process

When the platform loads a license file, it performs these checks in order:

1. Signature verification — Dual ML-DSA-65 (post-quantum) + Ed25519 (classical) signatures must both pass (v2 format). Legacy v1 uses HMAC-SHA256.
2. Expiry check — License must not be expired (or have no expiry for perpetual licenses).
3. Machine fingerprint — If the license carries a fingerprint, it must match the current machine.
4. Revocation check — License ID must not appear in the local data/revoked.json list.
5. Tier validation — The tier field must be a recognized value (community, pro, enterprise, managed).

If any check fails, the platform falls back to Community tier with a warning in the log.

User Management

API Key Authentication

The REST API uses API key authentication. Generate and manage keys through the dashboard or configuration.

# Include the API key in requests
curl -H "X-API-Key: your-api-key" https://localhost:8443/api/v1/stats

Backup and Recovery

What to Back Up

Backup Procedure

# Stop the platform before backing up the database

# Linux/macOS
tar -czf donjon-backup-$(date +%Y%m%d).tar.gz \
    data/evidence/ \
    data/license.json \
    config/active/config.yaml \
    data/reports/

# Windows (PowerShell)
Compress-Archive -Path data\evidence, data\license.json, `
    config\active\config.yaml, data\reports `
    -DestinationPath "donjon-backup-$(Get-Date -Format yyyyMMdd).zip"

Recovery

1. Install Donjon on the target machine
2. Extract the backup archive into the platform directory
3. Restart the platform
4. If the license is machine-bound, request a transfer from support

Updating the Platform

# Pull the latest version
git pull origin main

# Update dependencies
source venv/bin/activate   # or venv\Scripts\activate on Windows
pip install -r requirements.txt

# Update vulnerability intelligence
python3 bin/update-intel.py --quick

# Restart the platform
python3 bin/donjon-launcher