README.md

---

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
• ♾️ 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:

Detected Technology	Agent Triggered
WordPress, Drupal, Joomla, Magento, PrestaShop, Moodle	CMS-specific agent
PHP, Node.js, Flask, ASP.NET, Spring Boot, Ruby on Rails	Stack-specific agent
GraphQL	GraphQL agent
Active Directory	AD agent
Kubernetes	Kubernetes agent
Headless browser required	Headless browser agent

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.

---

Integrated Toolbox

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

Category	Tools (examples)
Port scanning	Naabu, Masscan
Web scanning	Nuclei, ffuf, dirb, sqlmap, Arjun, wafw00f
Recon & crawling	Subfinder, Katana, Waybackurls, httpx
CMS	WPScan, CMSeeK, WhatWeb
Active Directory	NetExec, BloodHound, Impacket (30+ scripts)
Kubernetes	kubectl, Kubescape, Kubeletctl
Network	Hydra, curl, dig, SNMP tools
Browser	Lightpanda (headless)

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:

Topic	What You'll Find	Link
GPU & Driver Setup	NVIDIA troubleshooting for Docker, WSL, and native Linux	GPU Guide
Environment Variables	LLM provider configuration, API keys, model selection	Environment Config
Startup & Build	install.sh behavior, docker compose build, stack management	Build & Launch
Scope & Flags	TARGET syntax, bug bounty mode, FOCUS/EXCLUDE, credentials	Scope Definition
Assessment Workflow	Step-by-step: discovery, fingerprinting, agents, reporting	Assessment Engine
Real-Time Session Logs	Monitor commands executed by the MCP server live	Session Logs
AI Agents	Agent structure, lifecycle, how to create or modify agents	AI Agents
Architecture	Deployment diagrams, security boundaries, execution flow	Architecture
Toolbox	Complete tool list, adding tools, Docker image internals	Toolbox
MCP Workflows	Workflow structure, creating custom workflows, best practices	MCP Workflows
Available Tools List	Full table of 50+ tools with paths and sources	Tools List
Training Labs	Recommended vulnerable labs to train DarkMoon	Pentester Labs

---

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.

---