What is DarkMoon?

DarkMoon is an automated penetration testing tool that orchestrates complete security assessments using artificial intelligence security agents. Built as an open-source cybersecurity tool, it enables organizations to run professional-grade vulnerability assessments without manual intervention.

Instead of replacing the pentester, DarkMoon acts as an autonomous security testing system — it reasons, plans, and coordinates specialized agents that execute real offensive security operations through a controlled execution layer.

Why DarkMoon?

Traditional penetration testing is:

• ⏱️ Time-consuming — manual testing takes weeks
• 💰 Expensive — expert consultants cost thousands per day
• 🔄 Inconsistent — results vary by tester expertise
• 📊 Hard to scale — limited by human resources

DarkMoon solves this with AI penetration testing:

• 🤖 AI-powered pentesting — autonomous agents conduct full security assessments end-to-end
• 🛡️ Security by design — the AI never directly executes tools; all actions flow through a controlled MCP interface
• 🕶️ Privacy gateway (reversible local tokenization) — the AI never sees your real sensitive values. IPs, hostnames, domains, URLs, emails, credentials and internal paths are replaced by deterministic placeholders (IP_PRIVATE_001, …); real values are injected locally, right before a tool runs, and masked back out of every result. No sensitive data ever leaves your perimeter to the LLM provider — use Claude's power under strict data-sovereignty constraints. Exfiltration attempts are blocked.
• ♾️ Pentesting automation for CI/CD — run automated security testing post-build to catch critical vulnerabilities before production
• 🔧 50+ integrated tools — a comprehensive penetration testing tools suite (Nuclei, NetExec, BloodHound, sqlmap, Naabu, httpx, ffuf, and more)
• 📈 Adaptive multi-agent methodology — specialized agents for Web, Active Directory, Kubernetes, Network, CMS, and more
• 📝 Vulnerability reporting automation — structured, evidence-based reports generated automatically

Perfect for security teams, DevSecOps engineers, ethical hacking professionals, and organizations of all sizes.

Quick Start

Prerequisites

• Docker & Docker Compose
• An LLM API key (OpenRouter, Anthropic, OpenAI, or local models)

Note: GPU configuration, NVIDIA driver troubleshooting, and advanced environment setup are covered in the Full Documentation — GPU Troubleshooting.

Installation

1. Clone the repository

git clone https://github.com/ASCIT31/Dark-Moon.git
cd Dark-Moon

2. Configure your LLM provider

install.sh handles provider configuration interactively — no need to edit docker-compose.yml:

./install.sh           # skip form if .opencode.env already configured
./install.sh --init    # force reconfiguration (cloud or local model)
./install.sh --help    # show usage

Supports cloud providers (Anthropic, OpenAI, OpenRouter…) and local models (Ollama, llama.cpp).

Note: For full details on environment variables and local model setup, see the Full Documentation — Environment Variables.

3. Build and launch

./install.sh  # Clean install with full stack reset

4. Run your first assessment

./darkmoon.sh "TARGET: example.com"

5. Monitor in real-time

./darkmoon.sh --log <session_id>

Note: Real-time session logs display every command executed by the MCP server. See Full Documentation — Session Logs for details.

How It Works

DarkMoon operates as a strategic AI security agent orchestrator aligned with ISO 27001, NIST SP 800-115, and MITRE ATT&CK methodologies.

When you provide a target, the platform automatically:

1. 🔍 Discovers the target environment (ports, services, protocols)
2. 🧠 Fingerprints the technology stack (frameworks, CMS, APIs)
3. 🎯 Models the attack surface
4. 🚀 Deploys specialized sub-agents based on detected technologies
5. 🔬 Executes an intelligent vulnerability scanning loop with reactive adaptation
6. ✅ Validates findings with evidence (requests, payloads, responses)
7. 📝 Generates a structured audit report

Sub-Agent Orchestration

DarkMoon dynamically selects and dispatches specialized agents depending on the technologies discovered:

Multiple agents can execute in parallel across hybrid architectures.

Note: For the complete list of agents, their structure, lifecycle, and how to create custom agents, see Full Documentation — AI Agents.

Architecture Overview

User ──> DarkmoonCLI ──> OpenCode (AI Brain) ──> MCP (Security Gatekeeper) ──> Docker Toolbox (Real Tools)

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

The AI reasons and plans. The MCP controls what can be executed. The Toolbox runs isolated tools inside Docker. The AI never directly touches the system — this is security by design.

Note: For the full architecture breakdown (deployment diagrams, network flows, security boundaries), see Full Documentation — Architecture.

Scope Definition

DarkMoon supports flexible scope definition directly from the command line.

Quick pentest (zero config):

./darkmoon.sh "TARGET: http://172.19.0.3:3000"

Bug bounty mode (flags activate automatically):

./darkmoon.sh "TARGET: http://172.19.0.3:3000 PROGRAM=\"Juice Shop\" FOCUS=sqli,xss,idor NOISE=moderate FORMAT=h1"

Key flags include FOCUS, EXCLUDE, CREDS, TOKEN, NOISE, SEVERITY, FORMAT, and more — all interpreted naturally by the AI.

Note: For the complete flags reference, asset types, EXCLUDE/FOCUS free-form syntax, and advanced multi-target scoping, see Full Documentation — Scope Definition.

DarkMoon ships with a purpose-built Docker image containing 50+ security tools compiled and optimized in a multi-stage build:

All tools are directly accessible — no path configuration needed.

Note: For the complete tools list with installation details and how to add new tools, see Full Documentation — Toolbox.

📖 Documentation Guide

DarkMoon's Full Documentation covers everything you need to operate the platform. Here is a quick reference to the most important sections:

Use Cases

DarkMoon is designed as a versatile security testing platform for:

• 🔒 Security teams — run continuous automated penetration testing across your infrastructure
• ⚙️ DevSecOps pipelines — integrate AI-driven security research into CI/CD workflows
• 🎯 Bug bounty hunters — accelerate ethical hacking with autonomous target analysis
• 🔬 Security researchers — explore attack surfaces with an AI cybersecurity platform that adapts in real time
• 🎓 Training & education — learn offensive security with guided, reproducible assessments

Example Prompts

# Web application pentest
./darkmoon.sh "TARGET: http://172.19.0.3:3000"

# Active Directory assessment
./darkmoon.sh "TARGET: 192.168.1.10"

# Bug bounty with specific focus
./darkmoon.sh "TARGET: https://app.example.com PROGRAM=\"Example BB\" FOCUS=sqli,rce,ssrf EXCLUDE=H1 FORMAT=h1"

Note: For more prompt examples including DVGA, Juice Shop, and headless browser scenarios, see Full Documentation — Prompt Examples.

Contributing

DarkMoon is open source and welcomes contributions. Whether you want to add new agents, integrate tools, create workflows, or improve documentation — see CONTRIBUTING.md for guidelines.

License

This project is licensed under the GNU General Public License v3.0. See LICENSE for details.