Creating and Running Automated Pentest Playbook Files

Playbooks are YAML files that define structured, multi-phase attack campaigns. Each playbook names a sequence of phases, the security tools that run in each phase, the options passed to those tools, and a post_analysis prompt that instructs the LLM how to interpret the tool output. The PlaybookRunner translates the playbook into a campaign objective and hands it to the swarm engine for execution.

Built-in playbooks

Seven playbooks ship with Pentest Swarm AI, covering the most common engagement types:

Playbook	Tags	Description
`bug-bounty`	`bug-bounty`, `external`, `web`, `recon`, `active`	End-to-end bug bounty swarm: subdomain enumeration → web surface mapping → nuclei scan → SQLi/SSRF/IDOR escalation. Dedup-ready output for HackerOne and Bugcrowd.
`owasp-top10`	`web`, `owasp`, `comprehensive`	Comprehensive web assessment covering all OWASP Top 10 categories: injection, auth, access control, misconfig, and vulnerable components.
`external-asm`	`asm`, `external`, `monitoring`, `passive-first`	Scheduled ASM playbook for cron use. Passive OSINT first, then DNS resolution, port and service fingerprinting, web fingerprinting, and a critical/high-only vuln sweep.
`ci-cd-security`	`ci`, `cd`, `sast`, `secrets`, `sbom`, `sarif`	Source-side security for CI: gitleaks + trufflehog secret scanning, semgrep SAST, dependency audit. Emits SARIF; zero network traffic to production.
`internal-network`	`internal`, `network`, `authorized-only`, `high-risk`	Authorized internal network pentest: CIDR sweep → service enumeration → optional Metasploit post-exploitation. Requires a signed scope file; cleanup always registered.
`ctf-solver`	`ctf`, `htb`, `thm`, `benchmark`, `autonomous`	Autonomous CTF machine solver: enumerate → initial foothold → privilege escalation → flag collection → writeup. Retired machines only by default.
`api-security`	`api`, `rest`, `graphql`	Focused REST and GraphQL API assessment: endpoint discovery via katana and gau, then nuclei checks for broken auth, BOLA/IDOR, mass assignment, and excessive data exposure.

Running a playbook

pentestswarm playbook run bug-bounty --target example.com

Provide the playbook name (resolved from the ./playbooks/ directory) or a direct file path, and supply --target. The runner resolves variable defaults, builds a campaign objective from the phase names and post_analysis prompts, and starts the campaign engine:

pentestswarm playbook run internal-network --target 10.0.0.1

pentestswarm playbook run ctf-solver --target 10.10.10.1

pentestswarm playbook run owasp-top10 --target example.com

Local paths are also accepted:

pentestswarm playbook run ./playbooks/bug-bounty.yaml --target example.com

Playbook YAML structure

The complete schema, derived from internal/plugins/types.go:

# --- Identity ---
name: string           # required; unique identifier used in CLI commands
description: string    # recommended; shown in 'pentestswarm playbook list'
version: string        # semver-like (e.g. 1.0.0); advisory
author:
  name: string         # your name or team
  github: string       # GitHub handle

# --- Discoverability ---
tags:                  # list of strings; used for filtering and search
  - web
  - recon

# --- Variables ---
# Variables are interpolated into tool options using {{ variable_name }} syntax.
variables:
  my_variable:
    type: string       # string | int | bool | list | secret
    required: true     # if true, runner errors without a value (no default)
    default: ""        # mutually exclusive with required: true

# --- Phases ---
phases:
  - name: phase_name   # required; must be unique within the playbook
    strategy: ""       # sequential (default) | parallel | best-effort
    conditions:        # optional trigger predicates (future: pheromone guards)
      - "pheromone > 0.5"
    tools:
      - name: subfinder          # built-in tool name (see tool list below)
        options:                 # tool-specific options map
          recursive: true
          timeout: 300
      - name: custom_tool        # references a custom tool definition
        command: "./my-script.sh {{ my_variable }}"  # inline command
    post_analysis: |
      Multi-line LLM prompt. This text is appended to the phase result
      and instructs the classifier / report agent how to interpret output.
      Use it to set analysis focus, specify what to flag, and what to skip.

  - name: next_phase
    tools: []          # phases may have no tools (LLM-only analysis)
    post_analysis: |
      Read flags from flag_path_hints. Submit via box's grader
      if credentials available; otherwise surface to report.

Variable type rules

Type	Accepted values
`string`	Any text
`int`	Whole numbers
`bool`	`true` or `false`
`list`	Comma-separated string or YAML list
`secret`	String; value is redacted from logs

Variable names must match /^[a-z][a-z0-9_]*$/. A variable declared required: true with a non-empty default produces a validation warning — pick one.

OWASP Top 10 playbook — full example

name: OWASP Top 10 Assessment
description: Comprehensive assessment targeting the OWASP Top 10 vulnerability categories
author:
  name: Armur AI
  github: Armur-Ai
version: 1.0.0
tags: [web, owasp, comprehensive]

variables:
  target_domain:
    type: string
    required: true

phases:
  - name: reconnaissance
    tools:
      - name: subfinder
        options: { recursive: true }
      - name: httpx
        options: { follow_redirects: true }
      - name: katana
        options: { depth: 3 }
      - name: gau
    post_analysis: |
      Map the full attack surface. Identify all web endpoints, parameters,
      forms, API routes, and authentication mechanisms. Note technology
      stack for targeted vulnerability checks.

  - name: injection_testing
    tools:
      - name: nuclei
        options:
          templates: ["cves/", "vulnerabilities/sqli/", "vulnerabilities/xss/"]
          severity: [critical, high]
    post_analysis: |
      Focus on A03:2021 Injection. Test all input points for SQL injection,
      XSS, command injection, LDAP injection, and template injection.
      Verify findings and assess exploitability.

  - name: auth_and_access
    tools:
      - name: nuclei
        options:
          templates: ["vulnerabilities/auth-bypass/", "misconfiguration/"]
    post_analysis: |
      Cover A01:2021 Broken Access Control, A02:2021 Cryptographic Failures,
      and A07:2021 Identification and Authentication Failures.
      Check for IDOR, privilege escalation, weak passwords, exposed tokens.

  - name: misconfig_and_components
    tools:
      - name: nuclei
        options:
          templates: ["exposures/", "technologies/", "misconfiguration/"]
    post_analysis: |
      Cover A05:2021 Security Misconfiguration and A06:2021 Vulnerable
      and Outdated Components. Check for default credentials, unnecessary
      features, outdated libraries, exposed admin panels.

Run it:

pentestswarm playbook run owasp-top10 --target example.com

Authoring your own playbook

Scaffold a new playbook

pentestswarm playbook create

This launches an interactive prompt and writes a starter YAML to the current directory.

Edit the YAML

Open the generated file in your editor. Define your phases, tools, and post_analysis prompts. Reference declared variables with {{ variable_name }} syntax in tool options:

name: My GraphQL Playbook
description: Targets GraphQL APIs for common misconfigurations.
author:
  name: Your Name
  github: your-handle
version: 0.1.0
tags: [graphql, api, web]

variables:
  target_domain:
    type: string
    required: true
  endpoint_path:
    type: string
    default: /graphql

phases:
  - name: discovery
    tools:
      - name: httpx
        options: { follow_redirects: true }
      - name: katana
        options: { depth: 2 }
    post_analysis: |
      Identify GraphQL endpoints. Look for /graphql, /api/graphql,
      /v1/graphql, and GraphQL playground paths.

  - name: graphql_audit
    tools:
      - name: nuclei
        options:
          templates: "graphql/"
    post_analysis: |
      Check for introspection enabled, mutations exposed without auth,
      and batch query abuse potential.

Validate the playbook

pentestswarm playbook validate my-playbook.yaml

The validator checks:

name is present

version is semver-like (warning only)

author.name is set (warning if missing)

Variable names match /^[a-z][a-z0-9_]*$/

Variable types are one of string | int | bool | list | secret

Each phase has a unique, non-empty name

Tool references that are not in the known tool list produce a warning (not an error — custom tools may be loaded at runtime)

Template variable references ({{ foo }}) in tool options are declared in the variables block

  ✗ variable "MyVar": name must match /^[a-z][a-z0-9_]*$/
  ⚠ author.name is empty — unowned playbooks are hard to maintain
  ⚠ phase[1] ("graphql_audit").tools[0]: tool "graphql-scanner" is not known to this binary

Exit code 0 = valid, 1 = errors found.

Run it

pentestswarm playbook run ./my-playbook.yaml --target example.com

Local paths and playbook names are both accepted. The runner searches ./playbooks/ and the system playbook directory for named playbooks.

Available tool names for playbook phases

These are the tool names the current binary recognises in phase tools[].name:

Tool	What it does
`subfinder`	Passive subdomain discovery via DNS sources and APIs
`amass`	Deeper OSINT and ASM subdomain discovery; passive mode by default
`httpx`	HTTP probing: status codes, tech detection, TLS info, response bodies
`nuclei`	Template-based vulnerability scanning (ProjectDiscovery templates)
`naabu`	Fast port scanning with rate control
`katana`	JavaScript-aware web crawler and endpoint discovery
`dnsx`	DNS resolution, reverse lookups, A/AAAA/CNAME enumeration
`gau`	Fetch known URLs from Wayback Machine and Common Crawl
`nmap`	Network port scanning and service/version fingerprinting
`ffuf`	Content discovery and parameter fuzzing with FUZZ keyword
`gobuster`	Directory and DNS enumeration
`sqlmap`	Automated SQL injection detection and exploitation
`semgrep`	Static analysis — SAST and supply-chain audit
`gitleaks`	Secret scanning in git history
`trufflehog`	Verified secret detection in commits and file systems

Tools outside this list (e.g. metasploit, dalfox) generate a validation warning but are not rejected — they may be custom tool definitions loaded from your plugins/ directory at runtime.

Add meaningful tags to every playbook you author. Tags are used by pentestswarm playbook list --tag web to filter the playbook catalog and make playbooks discoverable to teammates and the community. Use existing tag vocabulary (web, network, internal, asm, ctf, ci, api, graphql, cloud) where possible, and introduce new tags sparingly.

Bug Bounty

See the bug-bounty playbook in action with scope imports and dedup.

ASM

Run the external-asm playbook on a schedule for continuous monitoring.

GitHub Actions

Execute playbooks inside CI with SARIF output and severity thresholds.

CTF Mode

Use the ctf-solver playbook to autonomously solve HackTheBox machines.

Get Started

Core Concepts

CLI Reference

Guides

Security & Operations

Creating and Running Automated Pentest Playbook Files

Built-in playbooks

Running a playbook

Playbook YAML structure

Variable type rules

OWASP Top 10 playbook — full example

Authoring your own playbook

Available tool names for playbook phases

Bug Bounty

ASM

GitHub Actions

CTF Mode

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Reference

Guides

Security & Operations

Documentation Index

​Built-in playbooks

​Running a playbook

​Playbook YAML structure

​Variable type rules

​OWASP Top 10 playbook — full example

​Authoring your own playbook

​Available tool names for playbook phases

Bug Bounty

ASM

GitHub Actions

CTF Mode

Build docs developers (and LLMs) love

Built-in playbooks

Running a playbook

Playbook YAML structure

Variable type rules

OWASP Top 10 playbook — full example

Authoring your own playbook

Available tool names for playbook phases