Use this file to discover all available pages before exploring further.
pentestswarm playbook lets you run structured, repeatable attack sequences defined in YAML instead of relying on the freestyle AI swarm. Playbooks encode expert knowledge about a specific testing objective — OWASP Top 10, bug-bounty recon, CI/CD pipeline auditing, CTF solving — into an ordered series of phases, each specifying which tools to run and how the AI should interpret the results. This makes campaigns auditable, shareable, and reproducible across teams.
Execute a playbook against a target. The argument is either a direct file path to a YAML file or the name of a playbook in the ./playbooks/ directory (without the .yaml extension).
pentestswarm playbook run playbooks/owasp-top10.yaml --target example.compentestswarm playbook run bug-bounty --target app.example.com
When a playbook runs, the CLI prints each phase in order, dispatches the configured tools, and passes results to the AI post-analysis prompt defined in the YAML. Live events are streamed exactly as with pentestswarm scan --follow.Example output:
Parse and validate a playbook YAML file without running it. Checks that required fields are present, tool names are recognized, and variable references are consistent.
pentestswarm playbook validate my-playbook.yaml
Output on success:
[VALID] My Custom Playbook (3 phases, 2 variables)
Output on failure:
[INVALID] My Custom Playbook ERROR: phase "exploitation" references unknown tool "mybiztool" WARN: variable "api_key" declared but never referenced
The command exits with a non-zero code when there are errors, making it suitable for pre-commit hooks and CI pipelines.
Scaffold a new playbook YAML file at ./playbooks/my-playbook.yaml with sensible defaults and inline comments. Edit the generated file, then run playbook validate before using it.
pentestswarm playbook create
Generated template:
name: my-playbookdescription: Description of what this playbook testsauthor: name: Your Name github: yourgithubversion: 1.0.0tags: [web, custom]variables: target_domain: type: string required: truephases: - name: reconnaissance tools: - name: subfinder options: { recursive: false } - name: httpx options: { follow_redirects: true } post_analysis: | Analyze discovered assets and identify interesting targets. - name: vulnerability_scan tools: - name: nuclei options: severity: [critical, high, medium] post_analysis: | Classify findings and prioritize for exploitation.
The bug-bounty.yaml playbook is the most comprehensive example. Its four phases are:
subdomain_enumeration — runs subfinder (recursive) and dnsx, then asks the AI to flag wildcards and dangling CNAME takeover candidates.
web_surface — runs httpx, katana (depth-3 with JS crawling), and gau, then maps alive hosts, tech stacks, and deep-link endpoints.
vulnerability_scan — runs nuclei against critical/high/medium severity templates, filtering duplicates against known program issues when program_slug is set.
active_escalation — opt-in phase triggered when the classifier finds a POTENTIAL_SQLI, SSRF, or IDOR finding with pheromone score ≥ 0.5. Runs sqlmap with --batch for automated confirmation.
# Run the built-in bug-bounty playbook by namepentestswarm playbook run bug-bounty --target example.com# Run a custom playbook by pathpentestswarm playbook run playbooks/owasp-top10.yaml --target app.example.com# List all installed playbookspentestswarm playbook list# Validate a playbook before committing itpentestswarm playbook validate my-playbook.yaml# Scaffold a new playbook skeletonpentestswarm playbook create
scan
Run a freestyle AI pentest without a playbook
scope
Import and diff program scope files to feed into playbook runs
report
Polish the findings report generated after a playbook run
doctor
Verify the tools referenced in your playbooks are installed
