Skip to content

INSTALL.md

Latest commit

 

History

History
263 lines (187 loc) · 10.4 KB

INSTALL.md

File metadata and controls

263 lines (187 loc) · 10.4 KB
Raw

Installation Guide

Step-by-step setup for the Claude-BugHunter skill bundle.

Prerequisites

  • Claude Code — install from https://claude.ai/download
  • macOS, Linux, or Windows — macOS/Linux use the bash installers; Windows uses the native PowerShell installers
  • Python 3.9+ — for the cbh CLI runner

Optional (recommended but not required)

  • Burp Suite Professional or Community — https://portswigger.net/burp. cbh --burp routes traffic through Burp's proxy. Without Burp, the CLI runs in curl-only mode and everything still works.
  • Burp MCP Server (BApp Store extension) — adds conversational hunting via Claude Code. Optional layer on top of Burp Pro. Skip if you don't have Burp.
  • subfinder (ProjectDiscovery) — improves passive subdomain enum. Without it, cbh recon falls back to crt.sh alone.
  • Java — required for Burp MCP if you install it.

Choose your operating mode

Mode What you need Best for
Curl-only Just Python 3.9+ Quick hunts, scripted automation, no GUI
Burp proxy (cbh --burp) Add Burp Suite Pro/Community All cbh traffic logged in Burp; one click to Repeater
Burp MCP (conversational) Burp Pro + MCP extension + Claude Code MCP setup Maximum LLM-driven workflow inside Claude Code

All three modes are first-class supported. The skills + CLI work identically across them — you pick based on what you have installed and how you like to work.

Step 1 — Clone this repo

# macOS / Linux
mkdir -p ~/security-research && cd ~/security-research

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$HOME\security-research"
cd "$HOME\security-research"

# both
git clone https://github.com/elementalsouls/Claude-BugHunter.git
cd Claude-BugHunter

Step 2 — Run the installer

# macOS / Linux
bash scripts/install.sh

# Windows (PowerShell)
pwsh ./scripts/install.ps1

The repo ships a .gitattributes that forces LF line endings on shell and PowerShell scripts, so a fresh clone installs cleanly on every platform. If you have an existing checkout that already picked up CRLF (cloned before this .gitattributes), normalize it once with git add --renormalize . && git checkout . (or just re-clone) — a CRLF-corrupted script aborts with a syntax error and cannot fix itself.

This copies:

  • All 83 skills → ~/.claude/skills/ (macOS/Linux) or %USERPROFILE%\.claude\skills\ (Windows)
  • All 15 slash commands → ~/.claude/commands/
  • The hunt scaffolder → ~/.claude/scripts/hunt.sh (sourced from your .zshrc/.bashrc) on macOS/Linux, or ~\.claude\scripts\hunt.ps1 (dot-sourced from your PowerShell $PROFILE) on Windows

Existing skills with the same name are backed up to ~/.claude/install-backups/<timestamp>/ — outside the skills/commands directories, so backups never load as duplicate skills. Re-runs are non-destructive.

Run on other harnesses (OpenCode · Codex · Hermes · Google AntiGravity)

The skills are plain Agent Skills, so they also run outside Claude Code:

# macOS / Linux
./scripts/install.sh --all          # also installs to ~/.agents/skills (Codex/OpenCode), ~/.hermes/skills (Hermes), and ~/.gemini/config/skills (AntiGravity)
./scripts/install.sh --agents       # just Codex + OpenCode
./scripts/install.sh --hermes       # just Hermes
./scripts/install.sh --antigravity  # just Google AntiGravity
./scripts/install.sh --agents --burp-mcp   # also wire your Burp MCP into those harnesses
# Windows (PowerShell)
pwsh ./scripts/install.ps1 -All          # Codex + OpenCode + Hermes + Google AntiGravity
pwsh ./scripts/install.ps1 -Agents       # just Codex + OpenCode
pwsh ./scripts/install.ps1 -Hermes       # just Hermes
pwsh ./scripts/install.ps1 -AntiGravity  # just Google AntiGravity
pwsh ./scripts/install.ps1 -Agents -BurpMcp   # also wire your Burp MCP into those harnesses

Slash commands, the plugin marketplace, and the /hunt engine are Claude-Code-only; other harnesses get the skill knowledge + Burp MCP. Full details and per-harness MCP snippets: docs/multi-harness.md.

Step 3 — (Optional) Set up Burp MCP

Skip this step if you don't have Burp Suite Pro. The bundle works fine in curl-only mode (cbh recon target.com etc.). Set this up later when/if you adopt Burp.

In Burp Suite:

  1. Go to Extensions → BApp Store → search for "MCP Server" → Install
  2. Confirm the Output tab shows: Started MCP server on 127.0.0.1:9876
  3. Note the path it extracted the proxy JAR to (typically ~/.BurpSuite/mcp-proxy/mcp-proxy-all.jar)

In your terminal:

# macOS / Linux
claude mcp add burp -s user -- java -jar ~/.BurpSuite/mcp-proxy/mcp-proxy-all.jar
# Windows (PowerShell)
claude mcp add burp -s user -- java -jar "$HOME\.BurpSuite\mcp-proxy\mcp-proxy-all.jar"

Verify in a fresh claude session:

/mcp

You should see burp · ✓ connected.

Step 4 — (Optional) Refresh vendored skills from upstream

The bundle ships a frozen snapshot of shuvonsec's skills. To pull the latest from upstream and re-bundle:

# macOS / Linux
chmod +x scripts/install-community-skills.sh
./scripts/install-community-skills.sh

# Windows (PowerShell)
pwsh ./scripts/install-community-skills.ps1

This clones shuvonsec/claude-bug-bounty into ~/security-research/community-skills/ and runs its installer. Useful when you want fresher hunt patterns; not needed for first-time setup.

Windows note: the upstream shuvonsec/claude-bug-bounty ships its own bash installer. install-community-skills.ps1 runs it through Git-for-Windows bash if available, and skips it (with a notice) otherwise. Install Git for Windows (https://git-scm.com).

Step 5 — (Optional) Set up the skill regenerator

If you want to regenerate hunt-* per-class skills from fresh disclosed HackerOne reports periodically:

cd ~/security-research
git clone https://github.com/shuvonsec/public-skills-builder.git
cd public-skills-builder

# Need Python 3.10+ — use Homebrew on macOS
brew install python@3.12
/opt/homebrew/bin/python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt 2>/dev/null || pip install anthropic httpx pydantic requests

# Configure API keys
cp .env.example .env
# Edit .env:
#   ANTHROPIC_API_KEY=sk-ant-...
#   H1_API_KEY=your_h1_username:your_h1_token

Important: Anthropic API and Claude Max are separate billing systems. Max gives you Claude Code access; the API is pay-per-token. You need both keys (console.anthropic.com/billing for the API key) to run the generator.

Run the generator:

python3 public_skills_builder.py --source h1-public --program shopify --limit 200

Other H1 programs with high disclosed-report counts: gitlab, hackerone, mail-ru, valve, uber, twitter. The generator outputs flat .md files in skills/ — you'll need to wrap each in its own folder structure (hunt-name/SKILL.md) before installing to ~/.claude/skills/.

Known issues with public-skills-builder

Issue Fix
unsupported operand type: str | None Python <3.10 — install 3.12 via Homebrew
Filter parameters must contain at least one program handle Add --program <handle>
Could not fetch ngalongc/bug-bounty-reference Hardcoded master branch URLs — patch script to try main first

Step 6 — Smoke-test

Open a fresh claude session in any folder:

claude

Try a hunt-class trigger test:

I have a reflected user input that's rendered into the page HTML — testing for XSS. What payloads should I try?

Expected: Claude triggers hunt-xss and walks you through detection patterns + payloads.

Try the validation flow:

/triage

Then describe a hypothetical finding. Expected: Claude runs the 7-Question Gate.

Try the engagement scaffold:

hunt acme-test
ls ~/Targets/acme-test/

Expected: a complete folder with CLAUDE.md, scope.md, findings/, evidence/, submissions.txt, notes.md, .gitignore.

If all three smoke tests pass, you're set up.

Step 7 — Cleanup

Delete the test target:

# macOS / Linux
rm -rf ~/Targets/acme-test

# Windows (PowerShell)
Remove-Item -Recurse -Force "$HOME\Targets\acme-test"

Then go find a real program and put it to work. See USAGE.md for the full workflow walkthrough.

Troubleshooting

Symptom Likely cause Fix
/mcp doesn't show burp Burp Suite not running, or extension not loaded Re-open Burp, confirm Extensions tab shows MCP Server with "Loaded" checked
hunt: command not found (macOS/Linux) Shell didn't pick up the source line Restart your terminal, or source ~/.zshrc
hunt not recognized (Windows) PowerShell didn't load the profile Open a new PowerShell window, or . $PROFILE; check execution policy is RemoteSigned or less restrictive (Get-ExecutionPolicy -List)
Skills don't trigger as expected Description-field keyword mismatch Mention the bug class explicitly in your prompt (e.g., "I'm testing IDOR on this endpoint")
burp - get_proxy_history_regex returns empty Burp's proxy history is empty for that target Browse the target through Burp first to populate history
Python build errors during step 5 Using system Python 3.9 macOS: use Homebrew Python 3.12 (/opt/homebrew/bin/python3.12 -m venv .venv); Windows: use the official python.org installer or py -3.12 -m venv .venv

Uninstall

The installer writes a manifest of exactly what it placed (under ~/.claude/.skill-manifests/claude-bughunter.txt). Remove that footprint — and only that footprint — with:

# macOS / Linux
bash scripts/install.sh --uninstall

# Windows (PowerShell)
pwsh ./scripts/install.ps1 -Uninstall

This removes the bundle's skills, slash commands, the hunt.sh/hunt.ps1 script, and its shell-rc source line. Skills you also installed from the sister bundle Claude-OSINT — offensive-osint and osint-methodology — are kept if Claude-OSINT's manifest still claims them, so uninstalling one bundle never breaks the other. (Install backups under ~/.claude/install-backups/ are left in place; delete them manually if you want.)

If you installed via the plugin instead of the script: /plugin uninstall claude-bughunter@elementalsouls.

Burp MCP, if you wired it, is removed separately: claude mcp remove burp.