DarkMoon

DarkMoon is an open-source autonomous penetration testing platform. An LLM "brain" plans the assessment, a privacy gateway tokenizes sensitive values the agents discover mid-campaign before they reach the model (the launch prompt itself is passed verbatim — see the Privacy Gateway section), and an MCP gatekeeper runs curated workflows inside an isolated Docker toolbox — so the AI reasons and coordinates but never touches the target directly.

Architecture Overview

DarkMoon enforces a strict separation of concerns: OpenCode plans, the Privacy Gateway tokenizes, the MCP gatekeeper decides what runs, and the Docker Toolbox executes isolated tools. The model never issues raw commands or sees raw target data.

DarkMoon Autonomous Assessment Flow

Scroll sideways to see the whole diagram

View full size View full size

Where It Fits in an Engagement

DarkMoon is a breadth-first accelerator, not a replacement for manual depth. Point it at a scoped surface to enumerate technologies, run the relevant agents, and surface candidate findings quickly — then have an analyst reproduce anything it flags. Treat every autonomous result as a lead, not a deliverable.

Privacy Gateway

The defining feature of the v1.4.0 line. Important limitation: the operator's launch prompt is passed to the model verbatim — it defines scope, so it cannot be redacted up front. Values the agents discover mid-campaign (private IPs, hostnames, URLs, secrets) are replaced with deterministic placeholders (IP_PRIVATE_001, CRED_SECRET_001) before subsequent LLM calls, then rehydrated locally inside the toolbox at execution time and re-masked on the way back. Anything placed in the launch prompt itself reaches the provider unredacted.

# Privacy gateway — what the model actually sees.
# The LAUNCH prompt is passed to the model verbatim: it defines scope, so it
# cannot be redacted up front. Values the agents discover MID-CAMPAIGN are
# deterministically tokenized locally before subsequent LLM calls and
# rehydrated only inside the Docker toolbox at execution time.

# Launch prompt (sent verbatim):
TARGET=vpn.acme-corp.com

# Mid-campaign discovery — what later turns send to the LLM provider:
#   discovered 10.20.4.8            -> IP_PRIVATE_001
#   discovered intranet.acme-corp.local -> HOST_PRIVATE_001
#   discovered svc_scan / Winter2026!   -> CRED_USER_001 / CRED_SECRET_001

# Tool results are re-masked on the way back, so the model never reasons
# over raw IPs, hostnames, URLs, or secrets it did not receive at launch.

Specialized Agents

DarkMoon dispatches autonomous domain agents reactively: it discovers technologies, selects the relevant agent, validates findings with evidence, and iterates until attack-surface coverage is exhausted. The four agents below are the core domain agents; vendor docs now describe roughly 50 agents in total, though the published count varies across the repo, website, and docs (vendor-reported).

Beneath the four domain agents, the assessment engine dispatches technology-reactive sub-agents as it fingerprints the target: stack-specific agents (PHP, Node.js, Flask, ASP.NET, Spring Boot, Ruby on Rails), a GraphQL agent, a headless-browser agent, and CMS engines (WordPress, Drupal, Joomla, Magento, PrestaShop, Moodle). Coverage therefore adapts to what the target actually runs rather than following a fixed checklist.

MCP Workflows & Toolbox

The AI never runs raw shell. MCP exposes workflows — Python modules that encapsulate a complete task (port scanning, vulnerability scanning, crawling) with structured inputs/outputs and timeout management. Those workflows drive a compiled Docker toolbox of 80+ utilities (vendor-reported).

Installation

1. Clone & Install

# Clone the repository
git clone https://github.com/ASCIT31/Dark-Moon.git
cd Dark-Moon

# Interactive installer: pick LLM provider, pull the toolbox image,
# and build the OpenCode + MCP + Docker stack
./install.sh

2. Configure the LLM Provider

The interactive installer writes a .env. The docs' reference configuration is a current Opus-class frontier model; any current top-tier model works, and cloud and local providers are interchangeable.

# .env — provider selection for the OpenCode "AI brain"
# Reference configuration in the docs is a current Opus-class frontier model.
OPENCODE_MODEL="anthropic/claude-opus-5"       # or the current Opus-class frontier model
OPENROUTER_PROVIDER="anthropic"                # anthropic | openai | groq | mistral | openrouter | local
OPENROUTER_API_KEY="sk-or-..."                 # cloud/OpenRouter path uses OPENROUTER_API_KEY

# Local / self-hosted alternative (Ollama or llama.cpp).
# NOTE: sub-32B models cannot sustain autonomous campaigns.
# OPENROUTER_PROVIDER="local"
# OPENCODE_MODEL="ollama/qwen3-coder:30b"

3. Run an Authorized Campaign

# Bring the stack up
docker compose up -d

# Launch an authorized assessment against a scoped target
./darkmoon.sh "TARGET=example.com"

# Scope- and safety-bounded run. Directives use KEY=value. Note: OUT excludes
# HOSTS, EXCLUDE/FOCUS tune attack CLASSES, and NOISE bounds intensity.
./darkmoon.sh "TARGET=example.com \
  TARGETS=*.example.com \
  OUT=admin.example.com, payments.example.com \
  FOCUS=sqli, ssrf, idor \
  SEVERITY=high \
  NOISE=low \
  SAFE_HARBOR=yes \
  FORMAT=h1"

4. Validate Against a Lab Target First

Before pointing DarkMoon at a client, run it against a deliberately vulnerable target you control. This confirms the Docker stack, GPU/CPU inference, and mid-campaign tokenization all work, and shows you exactly what EXPLOITED vs Confirmed output looks like on a known-vulnerable app. The smoke path below is Docker-only and was not executed on the authoring host — treat its pins and timings as unverified until you run them.

#!/usr/bin/env bash
# Deterministic DarkMoon smoke path: pinned target, isolated network,
# wait-for-readiness, known-marker assertion, full teardown.
# Docker-only and NOT executed on the authoring host (no Docker there).
set -euo pipefail

# 1. Pin the target image by digest (never :latest). Resolve once:
#    docker pull bkimminich/juice-shop:<tag>
#    docker inspect --format '{{index .RepoDigests 0}}' bkimminich/juice-shop:<tag>
TARGET_IMAGE="bkimminich/juice-shop@sha256:PASTE_DIGEST_FROM_INSPECT"
echo "$TARGET_IMAGE" | grep -q "@sha256:" || { echo "FAIL: TARGET_IMAGE is not digest-pinned"; exit 1; }

# 2. Isolated bridge network — no host networking for the target or the stack.
docker network inspect darkmoon-smoke-net >/dev/null 2>&1 || docker network create --driver bridge darkmoon-smoke-net

# 3. Target plus stack up. DarkMoon's own compose file must likewise pin
#    digests and attach to an isolated network.
docker run -d --name juiceshop-smoke --network darkmoon-smoke-net -p 127.0.0.1:3000:3000 "$TARGET_IMAGE"
docker compose up -d

# 4. Wait-for-readiness: fail closed after ~120 s.
READY=0
for i in $(seq 1 60); do
  if curl -fsS http://127.0.0.1:3000/rest/admin/application-version >/dev/null 2>&1; then READY=1; break; fi
  sleep 2
done
if [ "$READY" -ne 1 ]; then echo "FAIL: target not ready"; docker compose down -v; docker rm -f juiceshop-smoke >/dev/null 2>&1; exit 1; fi

# 5. Tight, low-noise campaign at the lab target only.
./darkmoon.sh "TARGET=http://127.0.0.1:3000 TARGETS=http://127.0.0.1:3000 NOISE=low SAFE_HARBOR=yes"
./darkmoon.sh --log SESSION_ID

# 6. Known-marker assertion: the version endpoint must still answer with a version field.
curl -fsS http://127.0.0.1:3000/rest/admin/application-version | grep -q '"version"' || { echo "FAIL: marker assertion"; exit 1; }
ls ./reports/

# 7. Full teardown: stack, target, network, and smoke reports.
docker compose down -v
docker rm -f juiceshop-smoke
docker network rm darkmoon-smoke-net
rm -rf ./reports/smoke-*
echo "PASS: smoke path complete, stack and reports removed"

While it runs, capture the outbound LLM traffic and confirm that canary values the agents discover mid-campaign are tokenized on subsequent calls. Remember the launch prompt itself is sent verbatim, so only mid-campaign discoveries are covered — that is the one real proof the privacy gateway holds.

Community vs Pro

Pro activation

# Pro Edition: activate with a licence key
sudo ./install.sh LICENSE-KEY

# Add or rotate LLM providers on a live stack
./darkmoon.sh --connect

# Web UI (change the default admin/admin credentials immediately)
# http://localhost:80

Pro runtime hardening

Scope & Safety Flags

Campaign behavior is controlled through directives passed in the run prompt. Scope is defined with TARGETS (in-scope) and OUT (out-of-scope); EXCLUDE and FOCUS tune attack classes, not hosts. Set these deliberately — defaults are permissive enough to wander outside a tight engagement.

Usage example

TARGET=example.com
PROGRAM=acme-public-bbp
TARGETS=*.example.com
OUT=status.example.com, blog.example.com
FOCUS=idor, ssrf, sqli
SAFE_HARBOR=yes
SEVERITY=high

# I have written authorization to test *.example.com under the Acme
# public bug bounty program. Run an authorized assessment, validate
# findings with evidence, and produce a HackerOne-format report.

Monitoring, Output & Control

Campaigns run unattended, so know how to watch and bound them before you launch.

Evidence & Reporting

Findings are reported only with supporting HTTP requests, payloads, and responses, and are triaged into two states so a human knows what still needs review:

Reports export to standard, HackerOne, and Bugcrowd formats (signed PDF on Pro), alongside an interactive attack-surface graph and, on Pro, vulnerability-evolution tracking across campaigns.

Pre-Flight Checklist

Clear every item before pointing DarkMoon at anything you do not own.

Troubleshooting