Pentest Swarm AI

What it is – An open‑source, self‑hosted pentesting framework that runs dozens of AI agents in parallel (a “swarm”) to discover, exploit, and report vulnerabilities. It works with any LLM you provide (Claude, OpenAI‑compatible, Together AI models, Ollama, etc.) and coordinates the agents via a shared “blackboard” that uses stigmergic pheromones to decide which findings get chased next.

---

Key features

Feature	What it does
Real swarm architecture	Independent agents (recon, classify, exploit, report) read/write a pgvector‑backed blackboard; findings emit pheromones that trigger other agents automatically.
Concurrent scanning	Hundreds of sub‑domains or ports are probed in parallel, far faster than a linear pipeline.
Automatic exploitation	When a finding is classified as high‑severity, an exploit agent attempts a real attack (BOLA/IDOR, JWT forgery, SSRF, injection, etc.) and captures proof‑of‑concept evidence.
Evidence‑backed reports	Successful exploits are turned into structured reports with CVSS v3.1 scores and screenshots/logs.
Provider‑agnostic LLM support	Claude (default), Together AI, OpenAI‑compatible, Gemini, local Ollama/LM Studio, or any custom endpoint.
Zero‑cost starter	Can run entirely locally with Ollama, no API key required.
Built‑in toolchain	Integrates ProjectDiscovery utilities (subfinder, httpx, nuclei, naabu, katana, dnsx, gau) plus an nmap adapter.
Live UI	Web dashboard (localhost:7777) and full‑screen terminal TUI showing charts, swarm topology, and a live findings stream.
Scope enforcement	Both at the orchestration layer and inside each executor to prevent out‑of‑scope activity.
Extensible agents	Add new agents simply by defining a trigger predicate; no central orchestrator changes needed.
Jev false‑positive filter & adaptive scoring	Optional second‑opinion filter that scores attack paths and prioritises the most promising ones.
Playbooks & exploit chains	YAML playbooks for common scenarios (bug bounty, CI/CD, internal network, CTF) and a library of pre‑built exploit chains.
CI/CD ready	Scriptable pentestswarm scan … command and a GitHub Action wrapper.

---

How the swarm works

1. Seed – The user launches a campaign (via the TUI or CLI) and selects a target or bundled vulnerable lab.
2. Blackboard – A pgvector database stores every finding as a vector with a pheromone weight.
3. Agents run independently – Each agent continuously polls the blackboard. When a finding’s pheromone crosses its threshold, the agent wakes and acts (e.g., recon writes PORT_OPEN, classifier tags it as SQL_INJECTION, exploit tries to inject, report logs the result).
4. Emergence – Because agents react to the shared state rather than a fixed pipeline, attack chains can form spontaneously (recon → classification → exploit → new recon, etc.).
5. Decay – Pheromones decay over time (different half‑lives per finding type), so stale paths die without manual cleanup.
6. Evidence & reporting – Successful exploits generate screenshots / request/response logs, which are automatically compiled into a CVSS‑scored report.

---

Quick start (one‑liner install & run)

# Install – pick any method you like
npm install -g @armurai/pentestswarm               # npm
curl -fsSL https://raw.githubusercontent.com/Armur-Ai/Pentest-Swarm-AI/main/scripts/install.sh | sh   # script
brew install Armur-Ai/tap/pentestswarm          # Homebrew
go install github.com/Armur-Ai/Pentest-Swarm-AI/cmd/pentestswarm@latest   # Go
docker run --rm ghcr.io/armur-ai/pentestswarm:latest --help   # Docker

# Run the interactive launcher
pentestswarm run

The launcher will ask you to:

• Choose an LLM provider (Claude, Together AI, Ollama, etc.) and paste the API key if needed.
• Enter a target URL or select a bundled vulnerable lab (e.g., OWASP Juice Shop, crAPI).
• Pick a live view (web dashboard + terminal UI).
• Hit Launch – the swarm starts scanning and exploiting automatically.

---

Typical use cases

• Bug bounty hunters – Sweep a fresh scope overnight and get verified findings with proof‑of‑concepts.
• Red‑team / penetration testers – Rapidly cover large attack surfaces (many sub‑domains, internal networks) with minimal manual orchestration.
• Security researchers / CTF players – Run the built‑in labs or custom playbooks to test new exploit ideas.
• CI/CD pipelines – Automate a security scan as part of a build, using the scriptable pentestswarm scan command.

---

Installation options

Method	Command	Notes
npm	npm install -g @armurai/pentestswarm	Requires Node ≥ 16.
Shell script	`curl …	sh`
Homebrew	brew install Armur-Ai/tap/pentestswarm	macOS/Linux via brew.
Go	go install github.com/Armur-Ai/Pentest-Swarm-AI/cmd/pentestswarm@latest	Needs Go 1.24+.
Docker	docker run --rm ghcr.io/armur-ai/pentestswarm:latest --help	No host install; run inside a container.

---

License & status

• License: AGPL‑3.0 (copyleft, requires source distribution of any modifications).
• Project status: Alpha – core swarm scheduler is functional (--swarm flag), many components (live dashboard, Jev scoring, exploit‑chain library) are in beta, and a roadmap outlines upcoming adapters (Burp, Metasploit) and a fine‑tuned Pentest‑R1 model.

---

Where to learn more

• Documentation site: https://armur-ai.github.io/Pentest-Swarm-AI/
• Architecture deep‑dive: https://armur-ai.github.io/Pentest-Swarm-AI/architecture
• Discord community: https://discord.gg/6qtkhpW8tk
• Roadmap: ROADMAP.md in the repo.

---

Legal disclaimer: The tool is intended only for authorized testing (bug‑bounty programs, CTFs, red‑team engagements with explicit permission). Misuse is illegal and the authors assume no liability.