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.

Pentest Swarm AI’s bug bounty mode connects directly to HackerOne, Bugcrowd, and Intigriti to import program scope, enforce it at the tool layer, and deliver deduped, submission-ready reports at the end of every campaign. Instead of manually copying scope lists and reformatting findings, you run one command and the swarm handles the rest — from subdomain enumeration through active escalation.

​
End-to-end workflow

1
Set up platform credentials
2
Credentials are read from the OS keychain (populated by pentestswarm init) or from environment variables for CI pipelines. Set the relevant variables for each platform you use:
3
HackerOne
export HACKERONE_API_USER="your-h1-username"
export HACKERONE_API_TOKEN="your-api-token"
Generate your token at hackerone.com → Settings → API Token. Both HACKERONE_API_USER and HACKERONE_API_TOKEN are required for authenticated requests (private programs and dedup checks). Public program scope imports work without credentials, but dedup against your own submissions requires them.
Bugcrowd
export BUGCROWD_API_TOKEN="your-bugcrowd-token"
Generate your token in the Bugcrowd researcher portal. The Bugcrowd importer uses the v4 API (api.bugcrowd.com/v4) and requires a token — public scraping is not supported.
Intigriti
export INTIGRITI_API_TOKEN="your-oauth2-bearer-token"
Retrieve your OAuth2 bearer token from the Intigriti researcher settings. The importer calls api.intigriti.com/external/researcher/v1 using Authorization: Bearer.
4
For persistent storage in your OS keychain (recommended on dev machines):
5
pentestswarm init
6
Import program scope
7
Pull the in-scope asset list directly from the platform and write it to scope.yaml:
8
pentestswarm scope import h1 shopify
9
  [scope] importing h1/shopify ...
  [ok] wrote 42 domains + 3 CIDRs to scope.yaml

  Next:
    pentestswarm scan shopify.com --scope scope.yaml --swarm
10
The importer maps each asset type into your scope definition:
11
H1 asset typeBugcrowd categoryIntigriti typeMaps toURL, WILDCARD, DOMAINwebsite, api, otherurl, wildcard, domain, apiallowed_domainsCIDRip (CIDR format)ip_range, cidrallowed_cidrsIP_ADDRESSip (bare IP)ipallowed_cidrs (as /32)
12
Only assets marked eligible_for_submission: true (H1) or in_scope: true (Bugcrowd/Intigriti) are included.
13
To write to a custom path:
14
pentestswarm scope import bugcrowd tesla --out /tmp/tesla.yaml
pentestswarm scope import intigriti acme-corp --out acme.yaml
15
Run the swarm in bugbounty mode
16
pentestswarm scan example.com --scope scope.yaml --mode bugbounty --swarm --follow
17
The --mode bugbounty flag activates deduplication checks against your existing program submissions and formats all output for platform-ready submission. --swarm enables the stigmergic scheduler; --follow streams live agent events to your terminal.
18
Run the bug-bounty playbook
19
For a fully structured multi-phase attack scenario with defined tool sequences and post-analysis prompts, run the built-in playbook:
20
pentestswarm playbook run bug-bounty --target example.com
21
The playbook resolves variable defaults automatically. For dedup against a specific program’s known issues, set HACKERONE_API_USER and HACKERONE_API_TOKEN before running — the playbook’s dedup phase uses those credentials when program_slug is provided as a variable.
22
pentestswarm playbook run bug-bounty --target example.com
23
Polish and review reports
24
After the campaign completes, generated reports sit in ./reports/. Polish raw findings into submission-ready markdown:
25
pentestswarm report polish ./reports/report.md

​
Scope import platforms

The HackerOne importer calls GET /v1/hackers/programs/<slug>/structured_scopes. Authenticated requests (with HACKERONE_API_USER + HACKERONE_API_TOKEN) give access to private programs and enable dedup checks against your own submitted reports via GET /v1/hackers/me/reports.
# Import from a public program (no credentials needed)
pentestswarm scope import h1 shopify

# Import from a private program (credentials required)
export HACKERONE_API_USER="myusername"
export HACKERONE_API_TOKEN="sk-..."
pentestswarm scope import h1 private-program-slug

​
Bug bounty mode behaviours

Deduplication — Before the report agent files findings, it compares titles against your own prior submissions to the same program (/v1/hackers/me/reports) and the program’s public disclosed reports (hacktivity feed). Findings that match existing titles are suppressed from submission output. Scope enforcement — Scope is enforced at two layers: at the tool executor (tools only run against in-scope hosts) and at the output layer (findings for out-of-scope assets are dropped). The --scope flag is not bypassable. Submission templates — The report agent uses platform-specific templates to format findings. Each template captures the fields each platform expects:
The HackerOne template includes a summary, reproduction steps (command, HTTP request, or manual instructions), evidence items with timestamps, impact statement, remediation recommendation, CVSS score and vector, related CVEs, and corroborating tools.
## Summary
{{.Summary}}

## Steps to Reproduce
...reproduction steps with commands or HTTP requests...

## Impact
{{.Impact}}

## Recommendation
{{.Remediation}}

## Severity
**{{.Severity}}** — CVSS {{.CVSSScore}} (`{{.CVSSVector}}`)
The Bugcrowd template uses Bugcrowd’s VRT (Vulnerability Rating Taxonomy) format with title, severity, target, category, description, proof of concept, impact, and remediation.
### Vulnerability Details
- **Title:** {{.Title}}
- **Severity (VRT):** {{.Severity}} · CVSS {{.CVSSScore}}
- **Target:** {{.Target}}
...
The Intigriti template covers title, domain, type of weakness, severity, description, proof of concept, impact, and remediation.
**Title:** {{.Title}}
**Domain:** {{.Target}}
**Type of weakness:** {{.AttackCategory}}
**Severity:** {{.Severity}} (CVSS {{.CVSSScore}})
...

​
Bug bounty playbook

The built-in bug-bounty.yaml playbook defines four phases — from passive subdomain enumeration through active SQLi/SSRF/IDOR escalation: 
name: Bug Bounty Swarm
description: >
  End-to-end swarm for bug-bounty programs. Starts from a root domain,
  enumerates subdomains and endpoints, hunts for low-hanging vulns, then
  escalates on candidate SQLi/SSRF/IDOR with targeted active tests.
  Scope-enforced at every step; dedup-ready output for HackerOne / Bugcrowd.
author:
  name: Armur AI
  github: Armur-Ai
version: 1.0.0
tags: [bug-bounty, external, web, recon, active]

variables:
  target_domain:
    type: string
    required: true
  program_slug:
    type: string
    required: false
    description: HackerOne/Bugcrowd program slug, used for dedup and scope hints

phases:
  - name: subdomain_enumeration
    tools:
      - name: subfinder
        options: { recursive: true, timeout: 300 }
      - name: dnsx
    post_analysis: |
      Catalogue every subdomain, flag wildcards and takeover candidates
      (dangling CNAMEs pointing to third-party services).

  - name: web_surface
    tools:
      - name: httpx
        options: { follow_redirects: true, threads: 50 }
      - name: katana
        options: { depth: 3, js_crawl: true }
      - name: gau
    post_analysis: |
      Map alive hosts, status codes, tech stacks, and deep-link endpoints.
      Prioritise endpoints with query parameters, admin-ish paths, and
      old/deprecated versions.

  - name: vulnerability_scan
    tools:
      - name: nuclei
        options:
          severity: [critical, high, medium]
          templates: ["http/", "cves/", "exposures/"]
    post_analysis: |
      Report-ready findings only — filter duplicates against known
      program issues when program_slug is provided.

  - name: active_escalation
    # Opt-in by the swarm: only triggers if nuclei / classifier produce a
    # POTENTIAL_SQLI, SSRF, or IDOR finding with pheromone >= 0.5.
    tools:
      - name: sqlmap
        options: { risk: 1, level: 2, batch: true }
    post_analysis: |
      Confirm exploitability for high-pheromone findings. Cleanup
      commands must be registered for anything that mutates state.

​
Continuous monitoring with ASM

For ongoing visibility into your bug bounty programs, combine scope imports with ASM mode to automatically re-scan when the attack surface changes — new subdomains, newly-opened ports, and tech stack changes all trigger fresh campaigns. See the ASM guide for schedule configuration, diff commands, and notification setup.
Only test assets listed in your imported scope.yaml. The scope is enforced at the tool executor and at the output layer, but you remain responsible for ensuring every target is in-scope for the program. Never run against assets you do not have explicit written authorization to test.

Attack Surface Monitoring

Schedule continuous re-scans and get alerts when the attack surface changes.

Playbooks

Build custom multi-phase attack scenarios on top of the bug-bounty playbook.

GitHub Actions

Run bug bounty scans automatically in CI on a weekly schedule.

MCP Integration

Drive bug bounty scans interactively from Claude Desktop or Cursor.

Build docs developers (and LLMs) love

Get started for freeTalk to us