I. Preview

Watch DarkMoon in action — Full autonomous penetration test demo

II. Installation

II.1. Prerequisites

Before starting, you must have:

• Docker
• Docker Compose
• Access to an LLM provider (OpenRouter, Anthropic, OpenAI...)

II.2. GPU Troubleshooting Guide (Official)

Overview

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

There are two major supported setups:

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

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

uname -a

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

Case 1 — Windows + Docker Desktop + WSL2

Check GPU availability

On Windows (PowerShell):

nvidia-smi

Inside WSL:

/usr/lib/wsl/lib/nvidia-smi

Test Docker GPU

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:

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

nvidia-smi

Test Docker GPU

docker run --rm --gpus all nvidia/cuda:12.3.2-base-ubuntu22.04 nvidia-smi

If it fails — install NVIDIA Container Toolkit

Fix corrupted NVIDIA repo

sudo rm -f /etc/apt/sources.list.d/nvidia-container-toolkit.list

Correct installation (official method)

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
| sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

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

sudo apt update
sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Validate installation

docker run --rm --gpus all nvidia/cuda:12.3.2-base-ubuntu22.04 nvidia-smi

Final Notes

• Darkmoon runs perfectly without GPU (CPU fallback)
• GPU is optional acceleration, not required
• WSL GPU issues are often OS-level, not Docker-level
• Native Linux GPU issues are usually driver or toolkit misconfiguration

Quick Debug Checklist

II.2. General 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.3. Configuration of environment variables in docker compose

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

II.3.a Example environment variable

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

II.3.b Role of the variables

II.4. Automatic generation of OpenCode files

On first launch, Darkmoon:

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

All of this is done by the script:

conf/apply-settings.sh

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

II.5. Volumes and persistence

Configuration files are persisted via Docker volumes.

II.5.a Important volumes

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

II.5.b What this allows

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

II.6. Build and launch Darkmoon

II.6.a Building the images

Using install.sh

Darkmoon provides a dedicated installation and recovery script:

./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

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

docker builder prune -f

5. Rebuilds all images from scratch

docker compose build --no-cache

6. Recreates the Darkmoon stack

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

docker compose build

II.6.b Launching the stack

docker compose up -d

II.7. Launch Darkmoon (User CLI)

A wrapper is provided: darkmoon.sh.

II.7.a Make the wrapper executable

chmod +x darkmoon.sh

II.7.b Install globally (optional)

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

II.7.c Launch Darkmoon with TUI Console

darkmoon

Or with a direct command:

darkmoon "TARGET: mydomain.com"

Pentest Agent — Scope definition

Quick Pentest (zero config)

TARGET: http://172.19.0.3:3000

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

Bug Bounty (flags activate it)

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

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

Flags Reference

EXCLUDE / FOCUS — Free-Form

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

EXCLUDE=dom-xss,self-xss,clickjacking
EXCLUDE=H1
EXCLUDE=brute-force,rate-limiting,CWE-352

FOCUS=sqli,rce,ssrf,idor
FOCUS=auth-bypass,jwt,deserialization

Only shortcut: H1 = HackerOne Core Ineligible Findings.

Asset Types (optional prefix in TARGETS)

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

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

Examples

Minimal bounty:

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

Exclude specific attacks:

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

Multi-target with out-of-scope:

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

Full scope:

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

II.7.d How to Use the Darkmoon Assessment Engine

Overview

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

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

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

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

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

Step 1 — Start an Assessment

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

TARGET: 172.20.0.4

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

darkmoon_get_session
--> session_id returned

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

./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.

workflow: port_scan
target: 172.20.0.4
ports discovered: 80

This phase builds the initial attack surface model.

Step 3 — Technology Fingerprinting

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

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

The orchestrator builds a technology profile:

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

Step 4 — Attack Surface Modeling

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

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

Step 5 — Sub-Agent Selection

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

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

Step 6 — Reactive Multi-Agent Execution

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

1. The results are analyzed.
2. Newly discovered technologies are evaluated.
3. Additional agents may be dispatched.

Initial scan
   |
WordPress detected
   |
WordPress agent executed
   |
Plugin exposes GraphQL API
   |
GraphQL agent triggered

Step 7 — Evidence-Based Findings

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

UNCONFIRMED SIGNAL

This ensures the report remains audit-grade and defensible.

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

./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.8. Direct access to the container (debug)

It is possible to enter the OpenCode container directly:

docker exec -ti opencode bash

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

II.9. Where to modify what (summary)

II.10. Quick summary

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

III. Uses

III.1. Prompt Examples

Here's a list of prompts you can use with Darkmoon GPT:

• DVGA
• Juice Shop Headless
• Juice Shop

IV. Architecture

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

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

IV.1. Core Idea

Darkmoon is built around a strict and deliberate principle:

The AI never interacts directly with pentesting tools.

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

IV.2. Main Components (Who Does What)

IV.2.a. OpenCode — 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.b. AI 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.c. MCP 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.d. Darkmoon 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.e. Docker & 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.3. Execution 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.a Deployment diagram

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

IV.3.b Network 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.4. Security by Design

Darkmoon enforces clear boundaries:

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

IV.5. Why 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.

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.

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

V.1. What is a Darkmoon Agent?

A Darkmoon agent is:

• a Markdown file,
• loaded by OpenCode,
• that defines autonomous behavior,
• and controls the MCP to perform real actions.

V.2. Agent 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.3. Structure of a Darkmoon Agent

V.3.a Simplified Example

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

You are an autonomous AI cybersecurity agent.

V.3.b List of Agents

Currently, there are 4 agents:

• pentest-web — web application pentesting (XSS, SQLi, SSRF, XXE, etc.)
• pentest-ad — Windows infrastructure and Active Directory pentesting
• pentest-kubernetes — Kubernetes cluster surface attack pentesting
• pentest-network — network infrastructure attacks (FTP, SSH, SMTP, SNMP, etc.)

V.3.c Common Sections

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

V.4. Real 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.

V.5. Critical Rules for Agents

V.5.a Autonomy

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

V.5.b MCP-only

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

V.5.c Communication

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

V.6. Where Agents Live

V.6.a Before Build

conf/agents/

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

V.6.b After Build (Recommended)

darkmoon-settings/agents/

Advantages: modify without rebuild, persistence, external versioning.

V.7. Agent Lifecycle

1. OpenCode starts
2. Checks if agents already exist
3. Initial seed if needed
4. Dynamic loading
5. On-demand execution

V.8. Adding a New Agent

V.8.a. Method 1 — After Build (Recommended)

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

V.8.b. Method 2 — Before Build

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

V.9. Best Practices

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

V.10. Summary

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.

VI. Toolbox

VI.1. What 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.2. General principle (simple idea)

This project uses Docker with two stages:

VI.2.a Step 1: Builder

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

VI.2.b Step 2: Runtime

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

VI.3. Why this architecture is smart

VI.3.a Clear separation of roles

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

VI.3.b Standardized output

All compiled tools are placed in: /out/bin

Then exposed in: /usr/local/bin

VI.3.c Important optimizations

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

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

VI.4. What does the image contain?

VI.4.a Base system

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

VI.4.b Included languages

• Go: used to compile many network and security tools
• Python: (compiled version) installed in /opt/darkmoon/python
• Ruby: (compiled version) installed in /opt/darkmoon/ruby

VI.4.c Wordlists

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

VI.4.d Installed tools (examples)

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

VI.5. How to use the image

VI.5.a Build the image

docker build -t darkmoon .

VI.5.b Start a shell

docker run -it darkmoon bash

VI.5.c Use a tool

nuclei -h
naabu -h
netexec -h

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

VI.6.a Choose the right place

VI.6.b Rules to follow

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

VI.6.c Simple example (Go tool)

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

VI.7. How to maintain the project

VI.7.a In case of an error:

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

VI.7.b Best practices:

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

VI.8. For 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.9. Very 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.10. Toolbox list

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

VI.10.a Tools installed in the darkmoon runtime image

VI.10.b Tools installed by pip install impacket==0.12.0

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

VI.11. BONUS: Pentester lab to train DarkMoon

VI.11.a WEB / API / GRAPHQL / FRONTEND

VI.11.b ACTIVE DIRECTORY / WINDOWS

VI.11.c NETWORK / INFRASTRUCTURE

VI.11.d CLOUD (AWS / AZURE / GCP / OVH)

VI.11.e IOT / EMBEDDED / SCADA / ICS

VI.11.f MULTI-INFRA ORCHESTRATION (RARE & CRITICAL)

VII. MCP Workflows

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

Target audience: developers, advanced pentesters, contributors.

VII.1. What is an MCP Workflow?

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

A workflow = a complete operational task.

VII.2. Where Workflows Live

Workflows are located in:

mcp/src/tools/workflows/

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

VII.3. Dynamic Discovery

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

VII.4. Workflow Structure

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

VII.5. Example: Vulnerability Scan

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

VII.6. Called by an Agent

An agent can call:

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

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

VII.7. Advantages of Workflows

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

VII.8. Creating a New Workflow

1. Copy TEMPLATE.py
2. Implement the logic
3. Respect the structure
4. Test locally
5. Restart the MCP

VII.9. Best Practices

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

VII.10. Summary

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

VIII. Contributing

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

IX. License

Code licensed under GNU GPL v3.