# elementalsouls/claude-bughunter architecture

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

- Interactive diagram: https://gitdiagram.com/elementalsouls/claude-bughunter
- Repository: https://github.com/elementalsouls/claude-bughunter

## Overview

#### Purpose and Delivery Model
Claude-BugHunter is a security-knowledge bundle for authorized external bug bounty and red-team engagements. Its primary product is portable Agent Skills: Markdown instruction packs automatically selected by Claude Code, OpenCode, Codex CLI, and Hermes Agent. Claude-Code-specific commands and a Python engagement engine provide guided orchestration.
Paths: `skills/`, `.claude-plugin/plugin.json`, `scripts/install.sh`.

#### Entry Points and Installation
Users install as a Claude Code marketplace plugin or copy skills/commands into harness-specific home directories. The Python `cbh` package exposes a terminal-native runner; clone installs also expose the `hunt` scaffolder. Slash-command workflows begin from command documents such as `/hunt`, `/recon`, and `/report`.
Paths: `cbh/cli.py`, `scripts/cbh.py`, `commands/hunt.md`.

#### Knowledge and Routing Layer
The central content layer is 83 skill directories, each centered on `SKILL.md`. Skills encode methodology, recon, vulnerability-class hunting, enterprise-platform chains, validation, evidence, and reporting. A generated index supports deterministic mapping from observed technologies/findings to suitable skills rather than relying solely on model topic matching.
Paths: `skills/hunt-dispatch/SKILL.md`, `skills/bb-methodology/SKILL.md`, `cbh/data/skill_index.json`.

#### Engagement Engine
`engine/` is the deterministic orchestration boundary for engagement-folder work. It loads engagement configuration, enforces target scope, manages persistent state and memory, performs recon and OSINT processing, maps observations to skills, and coordinates an agent-facing workflow. Example engagement and Burp-MCP configurations define its external integration contract.
Paths: `engine/engine.py`, `engine/scope.py`, `engine/engagement.example.json`.

#### Primary Workflow and State Flow
The operating flow is non-linear but follows: authorize/scope → recon → map and rank attack surface → route hypotheses to hunting skills → validate findings through gates → produce evidence-backed reports. Engagement inputs and observations are persisted as state/memory; scope is a hard boundary before active work, while validation gates separate candidate findings from reportable submissions.
Paths: `engine/recon.py`, `engine/state.py`, `engine/memory.py`.

#### External Tools, Services, and Runtimes
Code is primarily Python, with Bash and PowerShell installers. Recon guidance integrates locally installed ProjectDiscovery tools (for example subfinder, dnsx, httpx, katana, nuclei) and public intelligence sources such as certificate transparency. Burp Suite is integrated through an MCP server configuration, keeping interception/scanning tooling outside the core engine.
Paths: `pyproject.toml`, `engine/burp-mcp.json.example`, `scripts/setup_harness_mcp.py`.

#### Reporting, Safety, and Quality Boundaries
Reporting and evidence skills standardize triage, severity, redaction, and client/bug-bounty outputs. The repository intentionally limits operational scope to authorized external surfaces, excluding internal AD, persistence, C2, and evasion. CI chiefly preserves content quality and generated-document consistency.
Paths: `skills/triage-validation/SKILL.md`, `skills/evidence-hygiene/SKILL.md`, `.github/workflows/skill-lint.yml`.

Main entry points: [`engine/engine.py`](https://github.com/elementalsouls/claude-bughunter/blob/main/engine/engine.py) (Orchestrator), [`engine/recon.py`](https://github.com/elementalsouls/claude-bughunter/blob/main/engine/recon.py) (Recon & OSINT), [`cbh/data/skill_index.json`](https://github.com/elementalsouls/claude-bughunter/blob/main/cbh/data/skill_index.json) (Skill index), [`scripts/install.sh`](https://github.com/elementalsouls/claude-bughunter/blob/main/scripts/install.sh) (Installers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery & entry points"]
  node_plugin["Claude plugin<br/>plugin manifest<br/>[plugin.json]"]
  node_install["Installers<br/>[install.sh]"]
  node_cli["cbh runner<br/>Python CLI<br/>[cli.py]"]
  node_hunt_command["/hunt workflow<br/>slash command<br/>[hunt.md]"]
end

subgraph group_knowledge["Knowledge routing"]
  node_skills["Agent Skills<br/>Markdown skill packs"]
  node_dispatch["Hunt dispatch<br/>routing skill<br/>[SKILL.md]"]
  node_methodology["Bug bounty methodology<br/>methodology skill<br/>[SKILL.md]"]
  node_skill_index[("Skill index<br/>generated routing index<br/>[skill_index.json]")]
end

subgraph group_engine["Engagement engine"]
  node_engine_core["Orchestrator<br/>Python engine<br/>[engine.py]"]
  node_scope{{"Scope enforcement<br/>authorization boundary<br/>[scope.py]"}}
  node_recon["Recon &amp; OSINT<br/>recon pipeline<br/>[recon.py]"]
  node_state[("Engagement state<br/>persistent state<br/>[state.py]")]
  node_memory[("Engagement memory<br/>persistent memory<br/>[memory.py]")]
  node_engagement_config["Engagement contract<br/>engagement config"]
end

subgraph group_integrations["External integrations"]
  node_recon_tools["Recon tools &amp; public intel<br/>external tools<br/>[pyproject.toml]"]
  node_burp_mcp["Burp MCP server<br/>external security integration"]
end

subgraph group_assurance["Safety &amp; quality"]
  node_validation["Validation &amp; triage<br/>validation skill<br/>[SKILL.md]"]
  node_evidence["Evidence hygiene<br/>reporting skill<br/>[SKILL.md]"]
  node_quality_ci["Skill lint CI<br/>content quality CI<br/>[skill-lint.yml]"]
end

node_plugin -->|"delivers"| node_install
node_install -->|"installs"| node_skills
node_cli -->|"runs"| node_engine_core
node_hunt_command -->|"starts workflow"| node_engine_core
node_dispatch -->|"uses"| node_skill_index
node_skill_index -->|"routes to"| node_skills
node_methodology -.->|"informs"| node_dispatch
node_engagement_config -->|"configures"| node_engine_core
node_engine_core -->|"enforces"| node_scope
node_scope -->|"authorizes"| node_recon
node_recon -->|"uses"| node_recon_tools
node_recon -->|"persists observations"| node_state
node_engine_core -->|"maintains"| node_memory
node_state -->|"maps observations"| node_skill_index
node_engine_core -->|"coordinates agents with"| node_skills
node_engine_core -.->|"integrates via"| node_burp_mcp
node_skills -->|"candidate findings pass"| node_validation
node_validation -->|"approved findings become"| node_evidence
node_quality_ci -->|"validates"| node_skills

click node_plugin "https://github.com/elementalsouls/claude-bughunter/blob/main/.claude-plugin/plugin.json"
click node_install "https://github.com/elementalsouls/claude-bughunter/blob/main/scripts/install.sh"
click node_cli "https://github.com/elementalsouls/claude-bughunter/blob/main/cbh/cli.py"
click node_hunt_command "https://github.com/elementalsouls/claude-bughunter/blob/main/commands/hunt.md"
click node_dispatch "https://github.com/elementalsouls/claude-bughunter/blob/main/skills/hunt-dispatch/SKILL.md"
click node_methodology "https://github.com/elementalsouls/claude-bughunter/blob/main/skills/bb-methodology/SKILL.md"
click node_skill_index "https://github.com/elementalsouls/claude-bughunter/blob/main/cbh/data/skill_index.json"
click node_engine_core "https://github.com/elementalsouls/claude-bughunter/blob/main/engine/engine.py"
click node_scope "https://github.com/elementalsouls/claude-bughunter/blob/main/engine/scope.py"
click node_recon "https://github.com/elementalsouls/claude-bughunter/blob/main/engine/recon.py"
click node_state "https://github.com/elementalsouls/claude-bughunter/blob/main/engine/state.py"
click node_memory "https://github.com/elementalsouls/claude-bughunter/blob/main/engine/memory.py"
click node_engagement_config "https://github.com/elementalsouls/claude-bughunter/blob/main/engine/engagement.example.json"
click node_recon_tools "https://github.com/elementalsouls/claude-bughunter/blob/main/pyproject.toml"
click node_burp_mcp "https://github.com/elementalsouls/claude-bughunter/blob/main/engine/burp-mcp.json.example"
click node_validation "https://github.com/elementalsouls/claude-bughunter/blob/main/skills/triage-validation/SKILL.md"
click node_evidence "https://github.com/elementalsouls/claude-bughunter/blob/main/skills/evidence-hygiene/SKILL.md"
click node_quality_ci "https://github.com/elementalsouls/claude-bughunter/blob/main/.github/workflows/skill-lint.yml"

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_plugin,node_install,node_cli,node_hunt_command toneBlue
class node_skills,node_dispatch,node_methodology,node_skill_index toneAmber
class node_engine_core,node_scope,node_recon,node_state,node_memory,node_engagement_config toneMint
class node_recon_tools,node_burp_mcp toneRose
class node_validation,node_evidence,node_quality_ci toneIndigo
```

## Components

### Delivery & entry points

- [Claude plugin](https://github.com/elementalsouls/claude-bughunter/blob/main/.claude-plugin/plugin.json): plugin manifest · `.claude-plugin/plugin.json`
- [Installers](https://github.com/elementalsouls/claude-bughunter/blob/main/scripts/install.sh): shell installers · Installs skills and commands into supported harnesses. · `scripts/install.sh`
- [cbh runner](https://github.com/elementalsouls/claude-bughunter/blob/main/cbh/cli.py): Python CLI · Terminal-native engagement runner. · `cbh/cli.py`
- [/hunt workflow](https://github.com/elementalsouls/claude-bughunter/blob/main/commands/hunt.md): slash command · `commands/hunt.md`

### Knowledge routing

- **Agent Skills**: Markdown skill packs · Portable methodology and hunting instructions selected by agent harnesses.
- [Hunt dispatch](https://github.com/elementalsouls/claude-bughunter/blob/main/skills/hunt-dispatch/SKILL.md): routing skill · `skills/hunt-dispatch/SKILL.md`
- [Bug bounty methodology](https://github.com/elementalsouls/claude-bughunter/blob/main/skills/bb-methodology/SKILL.md): methodology skill · `skills/bb-methodology/SKILL.md`
- [Skill index](https://github.com/elementalsouls/claude-bughunter/blob/main/cbh/data/skill_index.json): generated routing index · Deterministically maps technologies and findings to skills. · `cbh/data/skill_index.json`

### Engagement engine

- [Orchestrator](https://github.com/elementalsouls/claude-bughunter/blob/main/engine/engine.py): Python engine · Coordinates engagement-folder workflow. · `engine/engine.py`
- [Scope enforcement](https://github.com/elementalsouls/claude-bughunter/blob/main/engine/scope.py): authorization boundary · Blocks active work outside authorized targets. · `engine/scope.py`
- [Recon & OSINT](https://github.com/elementalsouls/claude-bughunter/blob/main/engine/recon.py): recon pipeline · `engine/recon.py`
- [Engagement state](https://github.com/elementalsouls/claude-bughunter/blob/main/engine/state.py): persistent state · `engine/state.py`
- [Engagement memory](https://github.com/elementalsouls/claude-bughunter/blob/main/engine/memory.py): persistent memory · `engine/memory.py`
- [Engagement contract](https://github.com/elementalsouls/claude-bughunter/blob/main/engine/engagement.example.json): engagement config · Defines targets and external integration settings. · `engine/engagement.example.json`

### External integrations

- [Recon tools & public intel](https://github.com/elementalsouls/claude-bughunter/blob/main/pyproject.toml): external tools · ProjectDiscovery tools and public intelligence sources. · `pyproject.toml`
- [Burp MCP server](https://github.com/elementalsouls/claude-bughunter/blob/main/engine/burp-mcp.json.example): external security integration · Keeps interception and scanning outside the core engine. · `engine/burp-mcp.json.example`

### Safety & quality

- [Validation & triage](https://github.com/elementalsouls/claude-bughunter/blob/main/skills/triage-validation/SKILL.md): validation skill · Gates candidates before reportable submissions. · `skills/triage-validation/SKILL.md`
- [Evidence hygiene](https://github.com/elementalsouls/claude-bughunter/blob/main/skills/evidence-hygiene/SKILL.md): reporting skill · Standardizes redaction and evidence-backed reporting. · `skills/evidence-hygiene/SKILL.md`
- [Skill lint CI](https://github.com/elementalsouls/claude-bughunter/blob/main/.github/workflows/skill-lint.yml): content quality CI · Checks skill content and generated-document consistency. · `.github/workflows/skill-lint.yml`

## Connections

- Claude plugin → Installers: delivers
- Installers → Agent Skills: installs
- cbh runner → Orchestrator: runs
- /hunt workflow → Orchestrator: starts workflow
- Hunt dispatch → Skill index: uses
- Skill index → Agent Skills: routes to
- Bug bounty methodology → Hunt dispatch: informs
- Engagement contract → Orchestrator: configures
- Orchestrator → Scope enforcement: enforces
- Scope enforcement → Recon & OSINT: authorizes
- Recon & OSINT → Recon tools & public intel: uses
- Recon & OSINT → Engagement state: persists observations
- Orchestrator → Engagement memory: maintains
- Engagement state → Skill index: maps observations
- Orchestrator → Agent Skills: coordinates agents with
- Orchestrator → Burp MCP server: integrates via
- Agent Skills → Validation & triage: candidate findings pass
- Validation & triage → Evidence hygiene: approved findings become
- Skill lint CI → Agent Skills: validates