Pentest Swarm AI is an open-source, autonomous penetration testing CLI built in Go that replaces the fixed recon → classify → exploit → report pipeline with a stigmergic swarm: specialist agents coordinate by reading and writing findings on a shared Postgres-backed blackboard rather than being dispatched by a central planner. Each finding carries a pheromone weight that decays over time, biasing agents toward high-signal paths and letting stale ones die naturally. The result is emergent attack chains that no single agent planned — and a workflow that scales to a thousand-subdomain target with a single command and a single Claude API key. Built on Go 1.24, the Anthropic Claude API, and the ProjectDiscovery toolchain, Pentest Swarm AI ships as a self-contained binary with a multi-panel TUI, a live Next.js dashboard, an MCP server for Claude Desktop and Cursor integration, and five community playbooks covering bug bounty, external ASM, CI/CD, internal network, and CTF scenarios.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Armur-Ai/Pentest-Swarm-AI/llms.txt
Use this file to discover all available pages before exploring further.
Key capabilities
Swarm Intelligence, Not a Pipeline
Agents coordinate through a stigmergic blackboard — each agent’s writes influence other agents’ behavior. There is no central planner. A recon finding wakes the classifier; a high-severity classification wakes the exploit agent; exploit results feed back into the board and wake the report agent. Order emerges from blackboard state, not a prescribed sequence.
15 Native Security Tools
The tool coordinator runs subfinder, httpx, nuclei, naabu, katana, dnsx, gau, nmap, sqlmap, ffuf, gobuster, trufflehog, gitleaks, semgrep, and amass concurrently against a target. Every tool adapter is scope-guarded, missing binaries are gracefully skipped, and results stream back to the blackboard as each tool finishes. No external orchestration layer required.
Multi-LLM Support
All agents inherit from a single provider config. Set one key and the entire swarm works. Supported providers are Claude (default — best quality, prompt caching enabled), Ollama (100% local, air-gapped), LM Studio (local with GUI model management), and any OpenAI-compatible endpoint — Together AI, DeepSeek, Groq, and more — via the
openai provider type.Multiple Engagement Modes
Five community swarm playbooks ship out of the box:
bug-bounty, external-asm, ci-cd, internal-network, and ctf-solver. Run any playbook with pentestswarm playbook run <name> --target <target>, or launch a freeform swarm scan with pentestswarm scan <target> --swarm.How it works
A campaign begins whenpentestswarm scan seeds the shared blackboard with a TARGET_REGISTERED finding. From that point on, no central planner issues instructions. The Recon agent triggers on TARGET_REGISTERED and fans out across all eight security tools, writing per-finding entries (SUBDOMAIN, PORT_OPEN, HTTP_ENDPOINT, TECHNOLOGY) back to the board. The Classifier agent wakes when raw recon findings accumulate above a pheromone threshold of 0.2 — it maps them to CVEs, scores CVSS, and emits CVE_MATCH and MISCONFIGURATION findings. The Exploit agent triggers on CVE_MATCH findings whose pheromone weight exceeds 0.5, builds attack chains, and writes EXPLOIT_CHAIN and EXPLOIT_RESULT entries. Finally, the Report agent triggers on CAMPAIGN_COMPLETE and queries the full board to generate Markdown, HTML, JSON, or SARIF output.
Every finding’s pheromone weight decays according to a configurable half-life that is specific to its type — a PORT_OPEN stays hot for hours; a SESSION for minutes. This decay ensures stale paths die naturally and agents stay focused on the most actionable signal. Each agent runs its own trigger predicate: add a new agent with its own predicate and it joins the swarm without anyone rewriting the orchestrator.
For a deep dive into the blackboard schema, pheromone decay math, and agent trigger semantics, see Swarm Architecture.
Tech stack
| Component | Technology | Why |
|---|---|---|
| Platform | Go 1.24 | Single binary, goroutine concurrency, native security tools |
| CLI | Cobra + bubbletea | Beautiful TUI with multi-panel agent view |
| LLM | Claude API / Ollama / LM Studio | Best quality cloud + full privacy local |
| Security Tools | subfinder · httpx · nuclei · naabu · katana · dnsx · gau · nmap | ProjectDiscovery Go libs + nmap subprocess |
| Blackboard | Postgres 16 + pgvector | Transactional writes, vector similarity, pheromone decay in SQL |
| Cache | Redis 7 | Rate limiting, session state |
| Dashboard | Next.js 15 + shadcn/ui + tremor | Dark-first, chart-heavy live campaign view |
| MCP | JSON-RPC stdio | Claude Desktop + Cursor integration |
Security tools wired in
The tool coordinator (internal/tools/coordinator.go) registers all built-in tools at startup. Tools backed by external binaries are checked via IsAvailable() at dispatch time — missing binaries are skipped and surfaced by pentestswarm doctor rather than causing a scan failure.
| Tool | Purpose |
|---|---|
| subfinder | Passive subdomain enumeration using multiple public sources |
| httpx | Web probe — discovers live HTTP/HTTPS endpoints, banners, and status codes |
| nuclei | Template-based vulnerability scanning across thousands of CVE and misconfiguration templates |
| naabu | Fast port scanner for discovering open ports across a target’s IP space |
| katana | Active web crawler for enumerating URLs, forms, and JavaScript endpoints |
| dnsx | DNS resolution and record enumeration for discovered subdomains |
| gau | Passive URL discovery from AlienVault OTX, Wayback Machine, and Common Crawl |
| nmap | Network and service fingerprinting via XML-parsed subprocess; scope-validated before every invocation |
| sqlmap | SQL injection testing and exploitation |
| ffuf | Fast HTTP fuzzer for content discovery and parameter brute-forcing |
| gobuster | Directory, DNS, and virtual-host brute-forcing |
| trufflehog | Secret scanning across code, commits, and filesystems |
| gitleaks | Git repository leak detection for secrets and credentials |
| semgrep | Static analysis for code-level vulnerability patterns |
| amass | In-depth DNS enumeration and attack surface mapping |
Project status
Honesty labels: stable means shipped and tested, beta means works but has rough edges, alpha means experimental, planned means on the roadmap.| Feature | Status | Notes |
|---|---|---|
| Sequential 5-phase runner | stable | Default mode; battle-tested core |
| Stigmergic swarm scheduler | alpha | --swarm flag; memory-backed blackboard wired |
| ProjectDiscovery toolchain | stable | subfinder, httpx, nuclei, naabu, katana, dnsx, gau |
nmap adapter | stable | XML parsed; scope-validated |
| Cleanup registry | stable | Always runs on SIGINT / exit / budget-cancel |
| Claude prompt caching | stable | Enabled for recon + classifier by default |
--strict LLM mode | stable | Promotes LLM errors to fatal |
| CVSS v3.1 scoring | stable | FIRST spec |
| Postgres blackboard backend | beta | Migration shipped; runner uses memory-board for now |
| MCP server | beta | pentestswarm mcp serve |
| VS Code extension | beta | deploy/vscode/ |
| GitHub Action | beta | deploy/github-action/action.yml with SARIF |
| Swarm playbooks (5) | beta | bug-bounty, external-asm, ci-cd, internal-network, ctf-solver |
| Live dashboard | alpha | web/; UI built, wiring to live campaigns in progress |
| Burp MCP bridge | planned | Wave 2 |
| Metasploit / ZAP / sqlmap adapters | planned | Wave 2 |
| Fine-tuned Pentest-Swarm model | planned | Wave 3 (Pentest-R1 recipe) |
| Cybench / AutoPenBench benchmarks | planned | Wave 3 |
The project is in active alpha. The sequential 5-phase runner is the battle-tested default. The stigmergic swarm scheduler (
--swarm) is experimental — expect rough edges and consult the roadmap for what is shipping next.Next steps
Quickstart
Install the binary and run your first swarm scan in under 60 seconds with a single Claude API key.
Installation
All install paths covered: Homebrew tap, Docker one-liner,
go install, and the pre-built binary releases.Swarm Architecture
Deep dive into the stigmergic blackboard, pheromone decay math, agent trigger predicates, and why this is not a pipeline.
Bug Bounty Guide
Run the
bug-bounty playbook against a HackerOne or Bugcrowd program, import scope automatically, and generate submission-ready reports.