elementalsouls/claude-bughunter

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.