# shuvonsec/claude-bug-bounty architecture

> Architecture diagram of the GitHub repository shuvonsec/claude-bug-bounty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shuvonsec/claude-bug-bounty
- Repository: https://github.com/shuvonsec/claude-bug-bounty

## Overview

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: [`tools/hunt.py`](https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/hunt.py) (Hunt engine), [`agents`](https://github.com/shuvonsec/claude-bug-bounty/tree/main/agents) (Agent prompts), [`commands`](https://github.com/shuvonsec/claude-bug-bounty/tree/main/commands) (Slash commands), [`agent.py`](https://github.com/shuvonsec/claude-bug-bounty/blob/main/agent.py) (Agent router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interface"]
  node_commands["Slash commands<br/>entrypoints"]
  node_scripts["CLI scripts"]
end

subgraph group_orchestration["Orchestration"]
  node_agent_py["Agent router<br/>orchestrator<br/>[agent.py]"]
  node_brain_py["Brain state<br/>planner<br/>[brain.py]"]
  node_agents["Agent prompts<br/>behavior"]
end

subgraph group_execution["Execution"]
  node_hunt_tool["Hunt engine<br/>pipeline<br/>[hunt.py]"]
  node_recon_engine["Recon engine<br/>[recon_engine.sh]"]
  node_intel_engine["Intel engine<br/>[intel_engine.py]"]
  node_target_selector["Target selector<br/>ranking<br/>[target_selector.py]"]
  node_validate_tool["Validation<br/>triage<br/>[validate.py]"]
  node_report_gen["Report generator<br/>reporting"]
end

subgraph group_memory_safety["Memory & Safety"]
  node_scope_checker["Scope guard<br/>policy<br/>[scope_checker.py]"]
  node_hunt_journal["Hunt journal<br/>[hunt_journal.py]"]
  node_pattern_db[("Pattern DB<br/>learning<br/>[pattern_db.py]")]
  node_audit_log["Audit log<br/>control<br/>[audit_log.py]"]
  node_schemas["Schemas<br/>validation<br/>[schemas.py]"]
end

subgraph group_integrations["Integrations"]
  node_burp_mcp["Burp MCP<br/>integration"]
  node_hackerone_mcp["HackerOne MCP<br/>integration<br/>[server.py]"]
end

subgraph group_knowledge["Knowledge"]
  node_skills["Skills<br/>knowledge"]
  node_rules_hooks["Rules & hooks<br/>constraints"]
  node_wordlists["Wordlists<br/>payloads"]
  node_web3_track["Web3 track<br/>domain"]
end

node_commands -->|"routes"| node_agent_py
node_commands -->|"loads"| node_agents
node_commands -->|"triggers"| node_hunt_tool
node_scripts -->|"runs"| node_hunt_tool
node_agent_py -->|"consults"| node_brain_py
node_agent_py -->|"delegates"| node_agents
node_brain_py -->|"chooses"| node_target_selector
node_agents -->|"guides"| node_recon_engine
node_agents -->|"guides"| node_validate_tool
node_agents -->|"guides"| node_report_gen
node_hunt_tool -->|"checks"| node_scope_checker
node_hunt_tool -->|"starts"| node_recon_engine
node_hunt_tool -->|"enriches"| node_intel_engine
node_hunt_tool -->|"prioritizes"| node_target_selector
node_hunt_tool -->|"verifies"| node_validate_tool
node_hunt_tool -->|"publishes"| node_report_gen
node_hunt_tool -->|"logs"| node_hunt_journal
node_hunt_tool -->|"controls"| node_audit_log
node_hunt_journal -->|"feeds"| node_pattern_db
node_audit_log -->|"validates"| node_schemas
node_scope_checker -->|"validates"| node_schemas
node_intel_engine -->|"reads"| node_burp_mcp
node_intel_engine -->|"reads"| node_hackerone_mcp
node_skills -->|"informs"| node_agents
node_rules_hooks -->|"reinforces"| node_scope_checker
node_wordlists -->|"supports"| node_recon_engine
node_web3_track -->|"specializes"| node_commands
node_web3_track -->|"specializes"| node_agents

click node_commands "https://github.com/shuvonsec/claude-bug-bounty/tree/main/commands"
click node_scripts "https://github.com/shuvonsec/claude-bug-bounty/tree/main/scripts"
click node_agent_py "https://github.com/shuvonsec/claude-bug-bounty/blob/main/agent.py"
click node_brain_py "https://github.com/shuvonsec/claude-bug-bounty/blob/main/brain.py"
click node_agents "https://github.com/shuvonsec/claude-bug-bounty/tree/main/agents"
click node_hunt_tool "https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/hunt.py"
click node_recon_engine "https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/recon_engine.sh"
click node_intel_engine "https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/intel_engine.py"
click node_target_selector "https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/target_selector.py"
click node_validate_tool "https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/validate.py"
click node_report_gen "https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/report_generator.py"
click node_scope_checker "https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/scope_checker.py"
click node_hunt_journal "https://github.com/shuvonsec/claude-bug-bounty/blob/main/memory/hunt_journal.py"
click node_pattern_db "https://github.com/shuvonsec/claude-bug-bounty/blob/main/memory/pattern_db.py"
click node_audit_log "https://github.com/shuvonsec/claude-bug-bounty/blob/main/memory/audit_log.py"
click node_schemas "https://github.com/shuvonsec/claude-bug-bounty/blob/main/memory/schemas.py"
click node_burp_mcp "https://github.com/shuvonsec/claude-bug-bounty/tree/main/mcp/burp-mcp-client"
click node_hackerone_mcp "https://github.com/shuvonsec/claude-bug-bounty/blob/main/mcp/hackerone-mcp/server.py"
click node_skills "https://github.com/shuvonsec/claude-bug-bounty/tree/main/skills"
click node_rules_hooks "https://github.com/shuvonsec/claude-bug-bounty/tree/main/rules"
click node_wordlists "https://github.com/shuvonsec/claude-bug-bounty/tree/main/wordlists"
click node_web3_track "https://github.com/shuvonsec/claude-bug-bounty/tree/main/web3"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_commands,node_scripts toneBlue
class node_agent_py,node_brain_py,node_agents toneAmber
class node_hunt_tool,node_recon_engine,node_intel_engine,node_target_selector,node_validate_tool,node_report_gen toneMint
class node_scope_checker,node_hunt_journal,node_pattern_db,node_audit_log,node_schemas toneRose
class node_burp_mcp,node_hackerone_mcp toneIndigo
class node_skills,node_rules_hooks,node_wordlists,node_web3_track toneTeal
```

## Components

### Interface

User-facing slash commands and direct CLI entrypoints.

- [Slash commands](https://github.com/shuvonsec/claude-bug-bounty/tree/main/commands): entrypoints · Claude Code command surface for hunt, recon, intel, validate, report, resume, and autopilot flows. · `commands`
- [CLI scripts](https://github.com/shuvonsec/claude-bug-bounty/tree/main/scripts): cli · 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](https://github.com/shuvonsec/claude-bug-bounty/blob/main/agent.py): orchestrator · Top-level coordination logic for selecting actions and sequencing work. · `agent.py`
- [Brain state](https://github.com/shuvonsec/claude-bug-bounty/blob/main/brain.py): planner · Decision and planning core that likely tracks intent, context, and next actions. · `brain.py`
- [Agent prompts](https://github.com/shuvonsec/claude-bug-bounty/tree/main/agents): behavior · Role-specific prompts for recon, ranking, chaining, validation, reporting, autopilot, and web3 auditing. · `agents`

### Execution

Recon, hunting, validation, reporting, and helper tooling.

- [Hunt engine](https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/hunt.py): pipeline · Main end-to-end offensive workflow coordinator for recon-to-report execution. · `tools/hunt.py`
- [Recon engine](https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/recon_engine.sh): recon · Discovery and surface mapping stage for live targets and tech fingerprinting. · `tools/recon_engine.sh`
- [Intel engine](https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/intel_engine.py): intel · Program intelligence and target enrichment stage. · `tools/intel_engine.py`
- [Target selector](https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/target_selector.py): ranking · Ranks likely targets and chooses what to test next. · `tools/target_selector.py`
- [Validation](https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/validate.py): triage · Confirms candidate findings and separates signal from noise. · `tools/validate.py`
- [Report generator](https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/report_generator.py): reporting · Formats validated findings into report output. · `tools/report_generator.py`

### Memory & Safety

Persistent learning, audit controls, and scope enforcement.

- [Scope guard](https://github.com/shuvonsec/claude-bug-bounty/blob/main/tools/scope_checker.py): policy · Deterministic boundary check that filters assets before testing. · `tools/scope_checker.py`
- [Hunt journal](https://github.com/shuvonsec/claude-bug-bounty/blob/main/memory/hunt_journal.py): journal · Append-only log of actions and hunt progress. · `memory/hunt_journal.py`
- [Pattern DB](https://github.com/shuvonsec/claude-bug-bounty/blob/main/memory/pattern_db.py): learning · Cross-target technique and payout memory used to reuse prior wins. · `memory/pattern_db.py`
- [Audit log](https://github.com/shuvonsec/claude-bug-bounty/blob/main/memory/audit_log.py): control · Request logging, rate limiting, and circuit breaking for bounded automation. · `memory/audit_log.py`
- [Schemas](https://github.com/shuvonsec/claude-bug-bounty/blob/main/memory/schemas.py): validation · Structured data contracts for memory and runtime records. · `memory/schemas.py`

### Integrations

External MCP-backed context sources.

- [Burp MCP](https://github.com/shuvonsec/claude-bug-bounty/tree/main/mcp/burp-mcp-client): integration · Proxy history and replayed traffic from Burp Suite via MCP. · `mcp/burp-mcp-client`
- [HackerOne MCP](https://github.com/shuvonsec/claude-bug-bounty/blob/main/mcp/hackerone-mcp/server.py): integration · Public program intel and disclosed reports via MCP server. · `mcp/hackerone-mcp/server.py`

### Knowledge

Methodology, playbooks, payloads, and runtime guidance.

- [Skills](https://github.com/shuvonsec/claude-bug-bounty/tree/main/skills): knowledge · Methodology and domain guidance in skills content. · `skills`
- [Rules & hooks](https://github.com/shuvonsec/claude-bug-bounty/tree/main/rules): constraints · Always-on behavioral constraints and session hooks. · `rules`
- [Wordlists](https://github.com/shuvonsec/claude-bug-bounty/tree/main/wordlists): payloads · Reusable payload and wordlist corpus for scanners and fuzzers. · `wordlists`
- [Web3 track](https://github.com/shuvonsec/claude-bug-bounty/tree/main/web3): domain · Parallel smart-contract audit methodology and live-hunt workflow. · `web3`

## Connections

- 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.
