Skip to main content

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.

pentestswarm scan is the core command of Pentest Swarm AI. It deploys a coordinated swarm of AI agents against the specified target, running reconnaissance, vulnerability scanning, exploitation attempts, and report generation in a fully autonomous pipeline. The swarm works through a sequential five-phase runner by default, or the experimental stigmergic blackboard scheduler when --swarm is passed.
You must have explicit written authorization to pentest any target. Unauthorized scanning is illegal in most jurisdictions. Run pentestswarm scan only against systems you own or have a signed engagement letter for.

​
Synopsis

pentestswarm scan <target> [flags]
<target> is a domain name, IP address, or CIDR range (e.g. example.com, 10.0.0.1, 10.0.0.0/24). When --scope is omitted, the target itself becomes the scope — a conservative default that prevents accidentally reaching sibling domains.

​
Scan Modes

ModeDescription
manualDefault. General-purpose pentest, all techniques enabled.
bugbountyBug-bounty optimized. Scope-enforced, dedup-ready output, publish threshold 0.5 (only confirmed findings).
asmAttack surface management. Continuous asset discovery, less aggressive exploitation.
ctfCTF-tuned heuristics. Prioritizes flag-capture patterns and common CTF vulnerability classes.

​
Flags

​
target
string
required
The domain, IP, or CIDR to pentest. Positional first argument.
​
--scope
string
Comma-separated list of in-scope domains and CIDRs (e.g. example.com,10.0.0.0/24). Defaults to the target when omitted.
​
--objective
string
default:"find all vulnerabilities"
Natural-language description of what the swarm should find. Passed verbatim to the orchestrator’s system prompt.
​
--mode
string
default:"manual"
Scan mode: manual | bugbounty | asm | ctf.
​
--provider
string
Override the LLM provider: claude | ollama | lmstudio. Defaults to the value in config.yaml.
​
--dry-run
boolean
default:"false"
Print the planned commands without executing any of them. No packets are sent, no exploitation occurs.
​
--output
string
default:"./reports"
Directory where the finished report files are written.
​
--format
string
default:"md"
Report output format: md | html | json | sarif | all.
​
--follow
boolean
default:"false"
Stream live event output to the terminal. Enabled automatically when running in an interactive terminal.
​
--strict
boolean
default:"false"
Abort on any LLM error instead of degrading to heuristic fallbacks. Useful for debugging.
​
--swarm
boolean
default:"false"
Use the stigmergic blackboard scheduler (experimental). Agents deposit pheromones on the blackboard to guide each other. The default is the sequential five-phase runner.
​
--exploration-bias
string
default:"med"
Swarm pheromone scaling: low (depth-first) | med | high (breadth-first). Only meaningful when --swarm is set.
​
--publish-unverified
boolean
default:"false"
Include suspected-but-not-reproduced findings in the report (aggressive mode). Lowers the publish threshold from 0.5 to 0.1.
​
--estimate
boolean
default:"false"
Print expected LLM spend in USD and exit without scanning. No network packets are sent. Works even without an API key configured.
​
--target-class
string
default:"medium"
Sizing hint for the --estimate calculation: small (single subdomain, ≤20 endpoints) | medium (typical corporate site) | large (thousands of endpoints).
​
--safe-mode
boolean
default:"false"
Cap request-per-second rate and forbid destructive techniques. Intended for programs that explicitly disallow automated scanning.
​
--assist
boolean
default:"false"
Human-in-the-loop mode. The swarm pauses before every executed step and prompts [y/N/a=approve-all] on stderr.
​
--auth-token
string
Authorization token forwarded to HTTP requests as a Bearer header (for authenticated scanning).

​
Global flags (from pentestswarm --help)

​
--config
string
Path to config file. Defaults to ./config.yaml.
​
--api
string
default:"http://localhost:8080"
API server URL (used when pentestswarm serve is running separately).
​
--json
boolean
default:"false"
Emit structured JSON output instead of human-readable text.
​
--quiet
boolean
default:"false"
Suppress decorative output including the banner and event stream.
​
--verbose
boolean
default:"false"
Enable debug-level logging.

​
Event output format

When --follow is active (or the terminal is interactive), each agent event is printed to stdout: 
  15:04:05 [think]  Planning reconnaissance strategy...
  15:04:06 [>>]     Running subfinder on example.com
  15:04:08 [<<]     subfinder: 14 subdomains discovered
  15:04:09 [!]      SQL injection in /search?q= (CVSS 9.8)
  15:04:10 [*]      Phase transition: recon → exploit
  15:04:11 [>]      Running sqlmap --batch -u https://example.com/search
  15:04:45 [ERR]    nuclei: template parse error for cve-2024-xxxx

  [DONE]  Campaign complete.
TagColorMeaning
[think]CyanOrchestrator reasoning step
[>>]YellowTool invocation
[<<]GreenTool result
[!]RedFinding discovered
[*]MagentaState change / phase transition
[>]YellowStep executed
[ERR]RedError event
[DONE]GreenCampaign milestone complete

​
Cost estimation

Pass --estimate before any real scan to preview expected LLM spend. No packets are sent. 
pentestswarm scan example.com --estimate --target-class medium
Output: 
  [estimate] target class: medium
  [estimate] model:        claude-sonnet-4-6
  [estimate] expected LLM spend: $0.24 – $1.20
  (No packets sent. Remove --estimate to run the scan.)
Token ranges by class (calibrated against internal campaign logs):
ClassInput token rangeTypical use case
small20k – 80kSingle subdomain, ≤20 endpoints
medium80k – 400kCorporate site, 100–500 endpoints
large400k – 1.5MBug-bounty-scale, thousands of endpoints

​
API key resolution

The scan command resolves the API key in this order:
  1. config.yaml → orchestrator.api_key
  2. Environment variable PENTESTSWARM_ORCHESTRATOR_API_KEY
  3. Environment variable ANTHROPIC_API_KEY
  4. OS keychain entry (set by pentestswarm init)
  5. Interactive prompt (first-run escape hatch, interactive terminals only)

​
Examples

# Minimal — scan a domain, scope defaults to the target
pentestswarm scan example.com

# Explicit scope, follow live events
pentestswarm scan example.com --scope example.com --follow

# Bug-bounty mode with live streaming
pentestswarm scan example.com --scope example.com --mode bugbounty --follow

# CIDR range with a specific objective
pentestswarm scan 10.0.0.0/24 --scope 10.0.0.0/24 --objective "find RCE"

# Preview cost before scanning, no network traffic
pentestswarm scan example.com --estimate --target-class large

# Dry run — see the plan without executing
pentestswarm scan example.com --scope example.com --dry-run

# Stigmergic swarm scheduler, high exploration bias
pentestswarm scan example.com --scope example.com --swarm --exploration-bias high

# Human-in-the-loop: approve every step before execution
pentestswarm scan example.com --scope example.com --assist

# Quiet JSON output for CI pipelines
pentestswarm scan example.com --scope example.com --format json --quiet --json

campaign

Monitor and manage running campaigns launched by scan

report

Polish and quality-gate generated report drafts before submission

playbook

Run structured community attack playbooks instead of freestyle scanning

doctor

Verify all dependencies and security tools are installed correctly

Build docs developers (and LLMs) love

Get started for freeTalk to us