Armur-Ai/Pentest-Swarm-AI

Pentest Swarm AI – an open‑source, swarm‑based pentesting framework

What it is

• A Go‑based command‑line tool that lets you run dozens of autonomous AI agents against a target at the same time. The agents share a stigmergic blackboard (a Postgres + pgvector store) where each finding is written with a “pheromone” weight. Other agents read that board and react when the weight is high enough, so the workflow emerges organically rather than following a fixed pipeline.

Why a “swarm” matters

• Traditional AI pentesters (e.g., PentestGPT) use a single planner LLM that calls specialist tools in a linear order: recon → classify → exploit → report. Pentest Swarm replaces that planner with a decentralized set of agents that coordinate via the blackboard. This enables true parallelism – a 1 000‑subdomain target can be probed by many agents simultaneously – and allows attack chains to form spontaneously (e.g., a recon finding can instantly trigger an exploit without a hard‑coded hand‑off).

Key components

Component	Technology / Role
Agents	Four built‑in agents (recon, classifier, exploit, reporter). Each runs independently and can be added/removed without touching the others.
Blackboard	Postgres 16 with pgvector; stores findings, pheromone levels, and vector embeddings for similarity search.
Pheromones	Numeric weights that decay over time (different half‑lives per finding type). When a weight crosses a threshold, the relevant agent wakes up.
LLM provider	One provider config (Claude, Together AI, OpenAI‑compatible, Gemini, Ollama, LM Studio, OrcaRouter). The same model is used by all agents; the framework only supplies the “hands” (tool execution, coordination).
Toolchain	ProjectDiscovery Go libraries (subfinder, httpx, nuclei, naabu, katana, dnsx, gau) plus an nmap adapter. Future adapters for Metasploit, sqlmap, ZAP, Burp are planned.
Dashboard / UI	Interactive TUI (Cobra + Bubbletea) for quick launches; optional web dashboard (Next.js 15) on localhost:7777 showing live charts and swarm topology.
Cache / Rate‑limit	Redis 7 for session state and request throttling.

How you use it

1. Install – one‑liner via npm, Homebrew, a Go install, a Docker pull, or a curl script.
2. Run – pentestswarm run opens a TUI where you select a provider, paste an API key (or use a local Ollama model), and point the swarm at a target URL or a bundled vulnerable lab (e.g., OWASP Juice Shop, crAPI, VAmPI, DVGA).
3. Watch – The UI shows live charts, a topology diagram of agents, and a streaming list of graded findings. A separate web dashboard can be opened for richer visualisation.
4. Script – For CI/CD or automation, use the flag‑based form: pentestswarm scan <target> --scope <scope> --swarm ….

Safety & legality

• The tool enforces scope both at the orchestration layer and again inside each executor. A --strict mode treats any LLM error as fatal. A disclaimer in the README stresses that the software is for authorized testing only (bug‑bounty programs, CTFs, red‑team exercises, research).

Current status

• The core sequential 5‑phase runner is stable.
• The stigmergic swarm scheduler is alpha (enabled with --swarm).
• Postgres blackboard is beta (memory board used by default until migration completes).
• Live dashboard is alpha; a VS Code extension and GitHub Action are beta.
• Planned wave 2 features include adapters for Metasploit, sqlmap, ZAP, Burp, and a richer set of community playbooks.

Who it’s for

• Pentesters who want to cover large scopes overnight.
• Bug‑bounty hunters chasing first‑blood on fresh assets.
• Red‑team operators needing breadth and speed.
• Security researchers exploring autonomous offensive AI.

Bottom line Pentest Swarm AI is a genuine open‑source project that turns any LLM (Claude, Together AI models, local Ollama, etc.) into a coordinated swarm of autonomous pentesting agents. By leveraging stigmergy and pheromone‑based emergence, it aims to achieve parallel, evidence‑backed vulnerability discovery at “machine speed” while keeping all data under the user’s control.