bug-bounty

Autonomous bug bounty hunting framework for Claude Code. A 7-phase finite state machine orchestrates specialized AI agents that do recon, hunt in parallel waves, verify findings across three skeptical rounds, grade them on a 5-axis rubric, and produce submission-ready reports — end to end from a single slash command.

Table of Contents

1. What it is
2. Why this architecture
3. System architecture
4. The 7-phase FSM
5. Agent catalog
6. MCP control plane
7. Safety rails
8. Directory layout
9. Data model
10. Install & usage
11. Tech stack
12. Quality assessment

What it is

A multi-agent orchestration layer that turns Claude Code into a semi-autonomous bug bounty hunter. You give it one command:

/bountyagent target.com

…and it runs the full pipeline: recon → auth → parallel hunting waves → chain-building → three-round verification → grading → report writing. State is persisted to disk between phases, so long runs can be paused and resumed.

It is not:

• A scanner (nuclei/subfinder are just inputs).
• A single monolithic prompt.
• A black box — every phase writes structured JSON artifacts you can inspect.

It is:

• A finite state machine that knows which phase it's in and what's next.
• A set of ~10 specialized agents, each with a narrow role and tool whitelist.
• A local MCP server that acts as the control plane — findings, verifications, grades, and hand-offs all flow through typed tool calls instead of free-form prose.

Why this architecture

The core problem with LLM-based hunting is hallucination and drift. A single long-running agent will happily invent findings, inflate severity, and forget what it already tested. This framework solves that with three decisions:

System architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        Claude Code (host)                           │
│                                                                     │
│  /bountyagent target.com                                            │
│         │                                                           │
│         ▼                                                           │
│  ┌──────────────────┐    ┌──────────────────┐                       │
│  │   Orchestrator   │◄──►│  FSM state.json  │                       │
│  │  (slash command) │    │  phase / wave    │                       │
│  └────────┬─────────┘    └──────────────────┘                       │
│           │ spawns                                                  │
│           ▼                                                         │
│  ┌──────────────────────────────────────────────────┐               │
│  │         Specialized agents (parallel)            │               │
│  │                                                  │               │
│  │  recon │ hunter × N │ chain │ verifier × 3 │ ... │               │
│  └──────────────────┬───────────────────────────────┘               │
│                     │ calls tools                                   │
│                     ▼                                               │
│  ┌──────────────────────────────────────────────────┐               │
│  │    MCP server (stdio, Node.js, zero deps)        │               │
│  │                                                  │               │
│  │  bounty_http_scan   bounty_record_finding        │               │
│  │  bounty_*_handoff   bounty_write_verification    │               │
│  │  bounty_write_grade bounty_transition_phase ...  │               │
│  └──────────────────┬───────────────────────────────┘               │
│                     │                                               │
│                     ▼                                               │
│  ┌──────────────────────────────────────────────────┐               │
│  │      Session directory (on disk, per-target)     │               │
│  │  ~/bounty-agent-sessions/target.com/             │               │
│  │   state.json │ findings.jsonl │ handoff-wN-aN.*  │               │
│  │   brutalist.json │ balanced.json │ verified.json │               │
│  │   grade.json │ report.md                         │               │
│  └──────────────────────────────────────────────────┘               │
│                                                                     │
│  PreToolUse hooks ─── scope-guard.sh  (blocks out-of-scope Bash)    │
│  StatusLine       ─── bounty-statusline.js  (phase/wave/findings)   │
└─────────────────────────────────────────────────────────────────────┘

Control plane vs. data plane

• Control plane = structured JSON artifacts written by the MCP server. The orchestrator and every downstream agent read these. This is the only source of truth for what's been found, verified, and graded.
• Data plane = markdown mirrors (findings.md, brutalist.md, etc.) written best-effort for humans to eyeball. Prompts and code never parse them.

This split is deliberate — it's the main thing keeping the system deterministic enough to resume across sessions.

The 7-phase FSM

RECON ──► AUTH ──► HUNT ──► CHAIN ──► VERIFY ──► GRADE ──► REPORT
  │         │        │         │         │          │         │
  ▼         ▼        ▼         ▼         ▼          ▼         ▼
recon    optional  parallel   A→B      3 rounds   5-axis   write
tools    creds     waves     chains    (B/B/F)    score    submit-
                                                           ready

Verification is three rounds on purpose

• Round 1 — brutalist (max skepticism): re-runs every PoC; the default answer is "this isn't real, prove me wrong." Kills hallucinated findings.
• Round 2 — balanced: looks for false negatives the brutalist rejected too aggressively. Catches severity under-correction.
• Round 3 — final: fresh HTTP requests with fresh context on only the survivors. Last confirmation before grading.

Findings survive only if all three rounds agree. This is slow but it's the reason the submission validity ratio stays high.

Agent catalog

Each agent is a markdown file in .claude/agents/ declaring its role prompt, allowed tools, and model preference. They're spawned by the orchestrator with injected context — they don't see the full conversation, only what they need.

MCP control plane

A local stdio MCP server (mcp/server.js) — zero dependencies, pure Node — exposes typed tools for every state transition. Agents never write session files directly; everything goes through the server.

Tool families:

Why MCP instead of file writes directly? Three reasons: schema validation on every write, provenance (every artifact has a source tool), and dedupe (findings get canonical IDs F-1, F-2…).

Safety rails

Directory layout

bug-bounty/
├── install.sh                    # installer for target projects
├── dev-sync.sh                   # dev-only sync to test workspace
├── mcp/
│   ├── server.js                 # MCP server — all tools
│   └── auto-signup.js            # headless browser signup helper
├── .claude/
│   ├── agents/                   # 10 agent definitions (.md)
│   ├── commands/                 # /bountyagent, /bountyagent-fullsend
│   ├── hooks/                    # scope-guard, statusline, write-guard
│   ├── rules/                    # hunting.md, reporting.md
│   ├── bypass-tables/            # 8 vuln-class cheatsheets
│   └── settings.json             # hook wiring + status line config
├── test/                         # mcp-server test suite
├── package.json                  # node --test runner
└── CLAUDE.md                     # project instructions for Claude Code

Per-target runtime state lives outside the repo, at ~/bounty-agent-sessions/<domain>/.

Data model

Session directory (~/bounty-agent-sessions/<domain>/):

Install & usage

git clone https://github.com/deonmenezes/bug-bounty.git
cd bug-bounty
chmod +x install.sh
./install.sh /absolute/path/to/your/project

The installer drops agents/hooks/rules into <project>/.claude/, wires the MCP server into <project>/.mcp.json, and configures the status line. If the target already has .claude/settings.json or .mcp.json, it prints exactly the keys to merge instead of overwriting.

Then, from the target project:

claude

Inside the session:

/bountyagent target.com                      # full autonomous run
/bountyagent resume target.com               # pick up from last phase
/bountyagent resume target.com force-merge   # reconcile a stuck wave

Speed modes

The standard /bountyagent is balanced. When you need different tradeoffs, use one of the harness commands. They are dispatch policies built on top of the same 7-phase FSM — they do not re-implement it.

/bountyagent-fast https://target.com                          # cheap pre-screen
/bountyagent-ultra https://target.com                         # wide parallel
/bountyagent-loop https://target.com --findings 3 --budget-min 240
/bountyplan target.com                                        # plan before HUNT

A new Haiku-grade triage-agent runs after recon to score surfaces into promote / defer / kill — used implicitly by fast/ultra/plan modes to cut wasted hunter spawns.

For concurrent multi-target hunting, use the worktree helper:

./scripts/bounty-worktree.sh target1.com   # creates ~/bug-bounty-worktrees/target1.com on its own branch
./scripts/bounty-worktree.sh target2.com   # second worktree, independent MCP server, independent state

Full mode reference: docs/HARNESSES.md.

Requirements

• Claude Code with Opus access
• curl, python3, Node.js 18+
• Optional recon tools for better RECON:

  go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
  go install github.com/projectdiscovery/httpx/cmd/httpx@latest
  go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
  

  All optional — if missing, RECON steps skip cleanly.

Development

For working on the framework itself:

./dev-sync.sh /absolute/path/to/test-workspace

Backs up the test workspace's .mcp.json + .claude/settings.json, re-runs the installer, and runs claude mcp list as a smoke check.

Tech stack

Quality assessment

What's well-executed

• Separation of concerns. Each agent has one job, a narrow tool whitelist, and a short role prompt. This is the single most important anti-hallucination lever.
• Control plane / data plane split. JSON is authoritative, markdown is a debug mirror. Prompts and code never parse the markdown. This is the reason resume works reliably.
• Three-round verification. The brutalist → balanced → final chain catches both over- and under-correction without a single agent needing to be "right."
• Append-only findings with canonical IDs. findings.jsonl + F-N IDs mean you can reason about findings across waves without races.
• Hooks as real safety rails. scope-guard.sh runs before any Bash call; out-of-scope requests are blocked, not just logged. The rules in .claude/rules/*.md are loaded into every agent's context.
• Zero-dependency MCP server. Pure Node, stdio transport — trivial to install, no version drift.
• Graceful degradation. Missing subfinder/httpx/nuclei? RECON continues with what's there. Missing auth? Runs unauthenticated. No single-point-of-failure dependency.

Trade-offs / limits

• Opus-only economics. The multi-round verification is expensive. Cheaper models produce noticeably worse grading. This is a cost-versus-validity trade, and the framework chooses validity.
• No provenance enforcement on MCP writes. bounty_merge_wave_handoffs trusts the structured hand-offs it's given. A malicious or broken hunter could write plausibly-shaped garbage. Comments in server.js explicitly call this out as out of scope for the current patch.
• Synchronous waves. Parallelism is within a wave, not across waves. CHAIN and VERIFY wait for HUNT to finish. For a large target with 6 waves, wall-clock time is the bottleneck.
• Scope enforcement is denylist-based. deny-list.txt is a hard block; everything else is allowed. An allowlist-first model would be safer but more configuration-heavy.
• Recon leans on external tools. subfinder/nuclei are rate-limited and can get you blocked. No built-in throttling beyond what those tools provide.

Overall

For what it is — an open-source, Opus-backed, resumable bug-bounty agent — the architecture is legitimately good. The FSM + MCP control plane + three-round verification combo is the right shape for the hallucination problem, and the code matches the design. It's not a production security product, but it is a genuinely useful research-grade tool and a clean template for anyone building multi-agent systems on Claude Code.

Only run this against targets where you have explicit authorization (your own systems, or a published bug-bounty program scope). Unauthorized scanning is illegal in most jurisdictions. The scope-guard hook helps but cannot save you from bad inputs.