How shuvonsec/claude-bug-bounty works
1. Repository shape
- This is an AI-assisted bug bounty hunting harness, not a single app.
- The repo is organized around a command-driven orchestration layer on top of standalone security tools, with persistent memory and external MCP integrations.
2. Primary entry points
- The main user-facing interface is Claude Code slash commands in commands/.
- Those commands route work to specialized agents in agents/ and executable tooling in tools/, scripts/, and install*.sh.
- The same capabilities are also exposed as direct CLI utilities, so the system can run with or without Claude in the loop.
3. Orchestration layer
- agent.py and brain.py appear to hold the core coordination logic for selecting actions and sequencing stages.
- The workflow is staged around recon → hunt → validate → report, with additional commands for scope, intel, chain, surface, resume, and autopilot.
- This layer is the main architectural boundary between the human/operator and the automated offensive pipeline.
4. Specialized agent layer
- agents/ contains role-specific prompts/behavior for:
- reconnaissance
- recon ranking
- chain building
- validation
- report writing
- autonomous autopilot
- web3 audit
- These agents do not seem to own execution themselves; they decide or draft, while the tools perform the actual scanning, probing, and report generation.
5. Core execution pipeline
- tools/ is the operational engine room.
- The main flow is:
- discover attack surface
- fingerprint tech / find live targets
- run vulnerability-specific tests
- validate findings
- generate reports
- Key orchestration tools include hunt.py, recon_engine.sh, intel_engine.py, validate.py, report_generator.py, scope_checker.py, and mindmap.py.
6. Security testing modules
- The repo includes targeted scanners/testers for specific bug classes: IDOR, OAuth, race conditions, AI/chatbot abuse, CVE matching, fuzzing, and web vulnerability sweeps.
- These are not generic scanners; they encode opinionated bug-bounty heuristics and are meant to be selected based on target technology and attack surface.
- wordlists/ supports these modules with reusable payload lists.
7. Persistent memory subsystem
- memory/ is a key architectural feature and acts like a local learning store across hunts.
- It includes:
- hunt_journal.py for append-only action logs
- pattern_db.py for cross-target technique/payout learning
- audit_log.py for request logging, rate limiting, and circuit breaking
- schemas.py for structured validation
- This layer is what enables resume, pattern reuse, and history-aware targeting.
8. Safety and scope boundaries
- scope_checker.py is a deterministic guardrail that runs before testing assets.
- The README emphasizes that scope enforcement is non-negotiable and that all outbound activity should be filtered through it.
- rules/ and hooks/ provide always-on behavioral constraints and session hooks, making safety part of the runtime rather than just documentation.
9. Autonomous mode
- /autopilot is the high-level autonomous loop.
- It chains the major phases with checkpoints and uses memory plus audit controls to avoid uncontrolled hammering.
- The important architectural boundary here is that autonomy is bounded by validation, circuit breaking, and per-host rate limits, rather than being fully unconstrained automation.
10. External integrations
- mcp/ contains two important MCP-backed integration points:
- Burp Suite MCP client for proxy history and replayed traffic
- HackerOne MCP server for public program intel and disclosed reports
- These integrations connect the harness to external context sources: live proxy data and bounty-program intelligence.
11. Web3 branch
- web3/ is a separate knowledge and methodology track focused on smart contract auditing.
- It has its own staged reading path and is paired with the web3-auditor agent and /web3-audit command.
- Architecturally, this is a parallel capability domain rather than a subfeature of the web2 hunting pipeline.
12. Docs/skills as behavior content
- skills/, docs/, rules/, and agents/*.md are not runtime engines; they are behavioral and knowledge inputs for the harness.
- They define methodology, payload arsenals, reporting style, and domain-specific playbooks that shape agent decisions.
13. Operational packaging
- install.sh, install_tools.sh, scripts/, and config.example.json support environment setup and tool chaining.
- The repo assumes a mixed runtime: Python 3.8+, shell, and some JS tooling for recon/browser support.
- tests/ provides coverage around memory, scope, MCP, schema, and intel behavior, which suggests the repo treats these coordination layers as first-class components.
14. How the data flows end to end
- A typical run starts with a command or CLI entry point, checks scope, performs recon, ranks likely targets, runs targeted tests, logs all actions into memory/audit storage, validates any findings, and finally emits a report.
- Burp/HackerOne MCP add external context, while the memory subsystem feeds back prior outcomes to improve future targeting.
Main entry points: hunt.py Hunt engine · agents Agent prompts · commands Slash commands · agent.py Agent router
Components 22
Interface
User-facing slash commands and direct CLI entrypoints.
- Slash commands · Claude Code command surface for hunt, recon, intel, validate, report, resume, and autopilot flows.
commands - CLI scripts · Direct shell and Python entrypoints that can run the harness without Claude in the loop.
scripts
Orchestration
Command routing, decision logic, and agent behaviors.
- Agent router · Top-level coordination logic for selecting actions and sequencing work.
agent.py - Brain state · Decision and planning core that likely tracks intent, context, and next actions.
brain.py - Agent prompts · Role-specific prompts for recon, ranking, chaining, validation, reporting, autopilot, and web3 auditing.
agents
Execution
Recon, hunting, validation, reporting, and helper tooling.
- Hunt engine · Main end-to-end offensive workflow coordinator for recon-to-report execution.
tools/hunt.py - Recon engine · Discovery and surface mapping stage for live targets and tech fingerprinting.
tools/recon_engine.sh - Intel engine · Program intelligence and target enrichment stage.
tools/intel_engine.py - Target selector · Ranks likely targets and chooses what to test next.
tools/target_selector.py - Validation · Confirms candidate findings and separates signal from noise.
tools/validate.py - Report generator · Formats validated findings into report output.
tools/report_generator.py
Memory & Safety
Persistent learning, audit controls, and scope enforcement.
- Scope guard · Deterministic boundary check that filters assets before testing.
tools/scope_checker.py - Hunt journal · Append-only log of actions and hunt progress.
memory/hunt_journal.py - Pattern DB · Cross-target technique and payout memory used to reuse prior wins.
memory/pattern_db.py - Audit log · Request logging, rate limiting, and circuit breaking for bounded automation.
memory/audit_log.py - Schemas · Structured data contracts for memory and runtime records.
memory/schemas.py
Integrations
External MCP-backed context sources.
- Burp MCP · Proxy history and replayed traffic from Burp Suite via MCP.
mcp/burp-mcp-client - HackerOne MCP · Public program intel and disclosed reports via MCP server.
mcp/hackerone-mcp/server.py
Knowledge
Methodology, playbooks, payloads, and runtime guidance.
- Skills · Methodology and domain guidance in skills content.
skills - Rules & hooks · Always-on behavioral constraints and session hooks.
rules - Wordlists · Reusable payload and wordlist corpus for scanners and fuzzers.
wordlists - Web3 track · Parallel smart-contract audit methodology and live-hunt workflow.
web3
Connections 28
- Slash commands → Agent router: routes · Slash commands hand off orchestration to the core router.
- Slash commands → Agent prompts: loads · Commands bind to role-specific agent behavior.
- Slash commands → Hunt engine: triggers · High-level hunt flows can invoke the pipeline directly.
- CLI scripts → Hunt engine: runs · CLI and shell wrappers execute the same operational pipeline.
- Agent router → Brain state: consults · Router uses planning state to sequence work.
- Agent router → Agent prompts: delegates · Orchestrator delegates task-specific reasoning to agents.
- Brain state → Target selector: chooses · Planning informs target ranking and next action selection.
- Agent prompts → Recon engine: guides · Agent prompts shape recon and ranking behavior.
- Agent prompts → Validation: guides · Validation and reporting agents steer triage output.
- Agent prompts → Report generator: guides · Report-writing behavior is driven by dedicated prompts.
- Hunt engine → Scope guard: checks · All offensive work is gated by scope enforcement first.
- Hunt engine → Recon engine: starts · Hunt begins with discovery and surface mapping.
- Hunt engine → Intel engine: enriches · Target intelligence is gathered before deeper testing.
- Hunt engine → Target selector: prioritizes · The pipeline ranks promising targets and techniques.
- Hunt engine → Validation: verifies · Findings are validated before being accepted.
- Hunt engine → Report generator: publishes · Validated results are turned into a report.
- Hunt engine → Hunt journal: logs · Run progress is recorded for resume and replay.
- Hunt engine → Audit log: controls · Automation is bounded by audit and circuit-breaker controls.
- Hunt journal → Pattern DB: feeds · History is distilled into reusable cross-target patterns.
- Audit log → Schemas: validates · Operational records are validated against structured schemas.
- Scope guard → Schemas: validates · Scope decisions and records follow shared data contracts.
- Intel engine → Burp MCP: reads · Proxy context informs target intelligence.
- Intel engine → HackerOne MCP: reads · Program disclosures and public intel enrich recon.
- Skills → Agent prompts: informs · Methodology content shapes agent decisions and wording.
- Rules & hooks → Scope guard: reinforces · Behavioral rules and hooks backstop deterministic scope checks.
- Wordlists → Recon engine: supports · Payload corpora feed scanning and fuzzing stages.
- Web3 track → Slash commands: specializes · Web3 audit flows expose a parallel command path.
- Web3 track → Agent prompts: specializes · Web3 auditor behavior is defined as a distinct agent track.