$ show Armur-Ai/Pentest-Swarm-AI
Pentest-Swarm-AI is an open-source autonomous penetration testing tool built on a stigmergic swarm architecture. It coordinates multiple LLM-driven specialist agents (recon, classifier, exploit, report) via a shared blackboard with pheromone decay, enabling emergent attack paths without a central planner. The system integrates 30+ external security tools (nmap, nuclei, sqlmap, etc.), multiple LLM providers (Claude, OpenAI, Ollama, Gemini, LM Studio), and bug bounty platforms (HackerOne, Bugcrowd, Intigriti) for automated scope import and report submission. The architecture is a multi-agent system with a scheduler that dispatches agents based on blackboard predicates and pheromone levels. Key entry points include a CLI (Cobra commands: scan, init, playbook, submit, etc.), an API server (Fiber), a WebSocket hub for live streaming, a Next.js web dashboard, and an MCP server for IDE integration. Data flows: agents write findings to the blackboard with pheromone weights; the scheduler reads the blackboard and triggers agents whose predicates match; agents read findings, process them, and write new findings, creating a stigmergic feedback loop. External dependencies include PostgreSQL with pgvector for durable blackboard storage, LLM API endpoints, and the installed security tool binaries. The codebase demonstrates high craftsmanship with clean abstractions (tool adapter pattern, LLM provider interface, blackboard interface), extensive testing (unit, integration, e2e, benchmarks, LLM eval), and safety features (scope enforcement, provenance signing, rate limiting, false-positive caching). It is actively maintained with recent commits, CI/CD pipelines, and community engagement.
The LLM identified 5 files worth highlighting for reuse:
Core blackboard interface and Postgres implementation for stigmergic coordination. Agents write findings with pheromone weights, subscribe to predicates, and react to state changes. Includes pheromone decay, supersede semantics, cursor tracking, and budget enforcement. Reusable for any multi-agent system requiring decentralized coordination without a central planner.
Central registry and executor for all external security tool adapters. Provides parallel execution with streaming result channels, nil-safe lifecycle hooks (OnStart/OnDone/OnSkip), and scope validation via context. The pattern is reusable for orchestrating any collection of external binaries with consistent error handling and concurrency control.
Provider interface defining Complete, Stream, HealthCheck, and SupportsToolUse methods, with implementations for Claude, OpenAI, Ollama, Gemini, LM Studio, and OrcaRouter. Composable wrappers include retry/refusal handling, cost metering, and budget management. Reusable for any application needing pluggable LLM backends with consistent error handling and cost tracking.
Scope validation framework that checks targets (domains, CIDRs, URLs) against allowed/denied lists and validates commands for destructive tokens. Used by all tool adapters to enforce authorized targets. Includes ValidateAndLog, ValidateCommand, and custom error types. Reusable for any security tool orchestration requiring strict scope enforcement.
Command execution safety boundary for LLM-generated exploit commands. Implements scope validation, executable allowlist (derived from registered tools), safe-mode (rejects destructive tokens), assist mode (prompts user before execution), and dry-run. Reusable for any system that needs to safely execute commands generated by untrusted sources (e.g., LLM agents).