A Claude Code skill bundle for bug hunting and external red-team work - 82 skills, 15 slash commands, 681 disclosed-report patterns curated across 24 core vulnerability classes, plus enterprise identity + infrastructure attack matrices.
Python ai-securityanthropicapplication-securitybug-bountybugbountybugcrowdclaudeclaude-codeclaude-skillsethical-hackinghackeroneoffensive-securitypentestingred-teamsecurity-toolsweb-security
Beginner-friendly Quick Start + USAGE Section 0
Sachin Sharma8dbca9ac4c40
diff --git a/README.md b/README.mdindex ff0c2e6..d4598df 100644--- a/README.md+++ b/README.md@@ -284,37 +284,175 @@ One NO = KILL. Move on. This single discipline separates productive researchers## Quick Start-### One-step install (recommended)+**Time to first hunt:** ~10 minutes if you have prerequisites, ~25 minutes if you're starting fresh.++### Step 1 — Prerequisites (5 minutes, one-time)++You need these BEFORE the install will work. Check each one:++| What | Why | Verify with | Where to get it |+|---|---|---|---|+| **macOS or Linux** | Install script + shell scaffold are POSIX | `uname -a` | (Windows users: use WSL2 Ubuntu) |+| **Claude Code CLI** | The bundle runs as skills loaded by Claude Code | `claude --version` | https://claude.ai/download |+| **Claude Pro/Team or Max plan** | Claude Code needs a subscription OR an API key | `claude /login` (then sign in) | https://claude.ai/upgrade |+| **Python 3.9+** | For the `cbh` CLI (terminal-side companion) | `python3 --version` | `brew install python` (mac) / `apt install python3` (linux) |+| **`git`** | To clone this repo | `git --version` | usually pre-installed |++**Optional but recommended:**+- **Burp Suite Pro or Community** — `https://portswigger.net/burp` — needed only if you want HTTP-history capture. Skills work fine without it.++### Step 2 — Install the bundle (2 minutes)++Copy-paste these three commands into your terminal:```bash+mkdir -p ~/Research && cd ~/Researchgit clone https://github.com/elementalsouls/Claude-BugHunter.git-cd Claude-BugHunter-./scripts/install.sh+cd Claude-BugHunter && ./scripts/install.sh+```++**Expected output** (scrolls past ~80 lines — you can ignore the per-skill detail; just look for the banner at the bottom):+```+Installing Claude-BugHunter bundle from /Users/you/Research/Claude-BugHunter++Skills → /Users/you/.claude/skills+ ✓ Installed skill: apk-redteam-pipeline+ ✓ Installed skill: bb-methodology+ ... (one line per skill — 51 total) ...++Commands → /Users/you/.claude/commands+ ✓ Installed command: /autopilot+ ... (15 total) ...++ ✓ Installed hunt shell command at /Users/you/.claude/scripts/hunt.sh+ ✓ Added 'source ~/.claude/scripts/hunt.sh' to /Users/you/.zshrc++============================================+✓ Install complete+============================================++Next: open a new terminal (or 'source ~/.zshrc') and try:+ hunt acme-test```-That copies all 51 skills to `~/.claude/skills/`, all 15 commands to `~/.claude/commands/`, and sources `hunt.sh` from your shell rc.+If you see `command not found` for `git` or `python3`, go back to Step 1.++Restart your terminal (or `source ~/.zshrc`) so the `hunt` shell command is available.-### First engagement+### Step 3 — Verify install (30 seconds)```bash-hunt acme-bb # scaffolds ~/Targets/acme-bb/ with CLAUDE.md, scope.md, findings/, evidence/, submissions.txt-cd ~/Targets/acme-bb-claude # opens Claude Code with engagement context+# Verify the hunt scaffold (running with no args shows usage — that means it loaded)+hunt+# Expected: prints "Usage: hunt <target-name>" + default base path++# Count the installed skills (should be 51)+ls ~/.claude/skills/ | wc -l+# Expected: 51++# Spot-check a few skills loaded+ls ~/.claude/skills/ | grep -E '^(hunt-xss|hunt-rce|m365-entra-attack|triage-validation)$'+# Expected: all 4 lines print back```-In Claude, describe what you're testing in plain English — *"I see a `?url=` parameter, looks SSRF-prone"* — and `hunt-ssrf` auto-loads with detection patterns, payloads, and the 11-bypass IP table.+If `hunt` says "command not found": run `source ~/.zshrc` (or `source ~/.bashrc` on Linux) and try again. If that doesn't fix it, see [INSTALL.md → Troubleshooting](INSTALL.md#troubleshooting).-### Drop-in usage (Claude.ai, Claude API, other harnesses)+### Step 4 — Your first hunt (5–10 minutes)++**Don't have a target yet?** Use one of these — they EXIST to be tested by people new to bug hunting:++| Where | What it is | Why use it for your first hunt |+|---|---|---|+| **`hackerone.com/security`** | HackerOne's own bug bounty | Mature program, accepts almost everything, fast response |+| **`bugcrowd.com/programs`** | Browse public programs | Filter "Open to anyone" + "VDP" (no payout but no review either) |+| **`juice-shop.herokuapp.com`** | OWASP Juice Shop (deliberately vulnerable) | Practice without authorization concerns |+| **`testphp.vulnweb.com`** | Acunetix test target (deliberately vulnerable) | Practice SQLi, XSS in a safe environment |++For your first real attempt against a public bug bounty program, use **HackerOne's own program** (`hackerone.com/security`). They're paid to receive your testing.++**Run your first engagement:**```bash-# Copy a single SKILL.md into a Project's system prompt:-cat skills/hunt-rce/SKILL.md | pbcopy-# Paste into Claude.ai project instructions or API system prompt.+# Set up an engagement folder (replace 'h1-vdp' with any name you want)+hunt h1-vdp+cd ~/Targets/h1-vdp++# Open Claude Code in this folder+claude+```++You're now inside Claude Code, in an engagement folder with `CLAUDE.md`, `scope.md`, `findings/`, `evidence/` already set up. Now ask Claude to start:++> **You type this into Claude:**+> *I want to do a bug bounty hunt on hackerone.com — their own VDP at https://hackerone.com/security. Walk me through the workflow from scratch. Start with recon.*++**What you'll see Claude do:**+1. ✅ Load `bb-methodology` skill (the 6-phase workflow)+2. ✅ Load `triage-validation` skill (the 7-Question Gate that runs before any submission)+3. ✅ Load `offensive-osint` + `web2-recon` for recon+4. ✅ Ask you to confirm scope and engagement mode (bug-bounty vs red-team vs pentest)+5. ✅ Generate concrete commands you can run to start mapping the target++You don't need to know what each skill does — they auto-load based on what you describe. Just keep telling Claude what you're seeing and what you want to do next.++### Step 5 — When you think you found something++**Before drafting any report, type this into Claude:**++```+/triage+```++Then describe the finding to Claude in plain English: *"I found that the password-reset page returns the user's email back in the response when given a valid user ID — looks like account-enumeration."*++Claude runs the **7-Question Gate** (Q1: real HTTP request? Q2: accepted-impact? Q3: in-scope? … Q6: concrete impact, not technically-possible? Q7: not on the never-submit list?). Returns one of:+- **PASS** → you're cleared to write the report (`/report`)+- **DOWNGRADE** → you have a finding but it's a lower tier+- **KILL** → don't draft this; move on+- **CHAIN REQUIRED** → it's only valid as part of a larger chain++**This single step prevents the most common mistake new hunters make: drafting reports for findings that get rejected as N/A.**++### Step 6 — When ready to submit++```+/report```-All skills are plain Markdown — also usable as personal cheat sheets without Claude.+Claude triggers `report-writing` (the report body template) + the platform-specific skill (`bugcrowd-reporting` for Bugcrowd, generic H1 template otherwise). The output is copy-paste-ready.++---++### Beginner FAQ++**Q: Do I need to know how to hack?**+No. The skills explain detection patterns + payloads + validation. If you can read English and run a terminal command, you can use the bundle. You'll learn faster than reading 20 hacking books.++**Q: What if a skill doesn't auto-load?**+Mention the bug class explicitly: instead of *"this looks weird"* say *"I think this is XSS — let me test"*. The keyword `XSS` triggers `hunt-xss`. Same for SQLi, IDOR, SSRF, RCE, CSRF, etc.++**Q: Can I use this on any website?**+**NO.** Only on assets you own OR have written authorization to test (bug-bounty in-scope assets, pentest with signed engagement letter, CTF challenges, your own test environments). The bundle has guardrails — `triage-validation` Q3 explicitly checks scope before accepting any finding. Unauthorized testing violates computer-fraud laws.++**Q: Where do I get bug bounty targets?**+HackerOne (`hackerone.com/opportunities/all/search`), Bugcrowd (`bugcrowd.com/programs`), Intigriti (`intigriti.com/programs`), YesWeHack (`yeswehack.com/programs`). Filter for **VDP** programs first — they don't pay but they're also lower-pressure to learn on.++**Q: What's the difference between bug bounty and red team?**+- **Bug bounty** = open-scope, pay-per-finding, hundreds of researchers competing. Use `bb-methodology` + the `hunt-*` skills.+- **Red team** = paid engagement, narrow scope, single tester, deliverable is a client-facing report. Use `redteam-mindset` + `redteam-report-template` + the platform-attack skills (`m365-entra-attack`, `enterprise-vpn-attack`, etc).+- **Pentest** = paid engagement, broader coverage, methodology-driven. Mix of both skill sets.++The bundle's `bb-methodology` Part 0 will ask you to confirm which mode at the start of every engagement.++**Q: Skills aren't triggering — what's wrong?**+Check `/mcp` inside Claude — see if everything's connected. Also: skills trigger on *keywords* in your prompt. If you say *"is this exploitable?"* nothing triggers because there's no keyword. Say *"is this an SSRF?"* and `hunt-ssrf` loads.++**Q: Can I use this in Claude.ai (not Claude Code)?**+Yes — copy any `skills/<name>/SKILL.md` content into a Claude.ai Project's system prompt. Single-file usage works but you lose the multi-skill composition. Claude Code is the intended interface.++----For Burp Suite Pro MCP integration and the optional skill-regenerator setup, see [INSTALL.md](INSTALL.md). For the full workflow walkthrough with a worked example, see [USAGE.md](USAGE.md).+For Burp Suite Pro MCP integration (optional layer), see [INSTALL.md](INSTALL.md). For the full engagement walkthrough with a worked example, see [USAGE.md](USAGE.md).---diff --git a/USAGE.md b/USAGE.mdindex 7a09b6a..2c0d7b7 100644--- a/USAGE.md+++ b/USAGE.md@@ -6,6 +6,128 @@ A practical guide to using the 51-skill Claude-BugHunter bundle for bug hunting---+## 0. Brand new? Start here++This section is for people who have **never used the bundle before, never used Claude Code, or never done bug hunting**. If you're already comfortable with any of those, skim to Section 1.++### What is this bundle, in plain English?++It's a collection of 51 markdown files (called **skills**) that turn Claude Code into a methodical bug-hunting assistant.++Without the bundle, asking Claude *"is this XSS?"* gets you a generic answer. With the bundle installed, the same question loads the `hunt-xss` skill — which contains specific detection patterns from 574+ disclosed reports, the exact payloads that have worked, and a validation gate that prevents you from filing a false-positive bug report.++You don't "learn" the bundle. You install it once, then describe what you're testing in plain English, and the relevant skill auto-loads. You read it together with Claude and follow the steps.++### What you DO need before starting++1. **A laptop running macOS or Linux** (Windows users: WSL2 Ubuntu works).+2. **Claude Code installed** (from https://claude.ai/download) — this is the CLI app, not Claude.ai in your browser.+3. **A Claude paid plan** (Pro/Team/Max) or an Anthropic API key with credit. Free Claude.ai doesn't include Claude Code.+4. **The terminal app open** and the willingness to copy-paste 3 commands.+5. **A target you're authorized to test** — meaning either: (a) you own it, (b) it's on a bug bounty program's in-scope list, (c) you have a signed pentest engagement letter, or (d) it's a deliberately-vulnerable practice site (OWASP Juice Shop, Vulnweb, HackTheBox, etc.).++### What you DON'T need++- ❌ You don't need to know how to write exploits. The skills include working payloads.+- ❌ You don't need to know Burp Suite. It's optional. Skills work with curl + browser.+- ❌ You don't need a bug bounty account yet. You can practice on OWASP Juice Shop first.+- ❌ You don't need to read all 51 skills. They auto-load when relevant.+- ❌ You don't need Python beyond `python3 --version` working.++### Your first 30 minutes++Open your terminal. Copy-paste this entire block:++```bash+# 1. Get the bundle+mkdir -p ~/Research && cd ~/Research+git clone https://github.com/elementalsouls/Claude-BugHunter.git+cd Claude-BugHunter++# 2. Install (copies 51 skills + 15 commands into Claude Code)+./scripts/install.sh++# 3. Reload your shell so the 'hunt' command becomes available+source ~/.zshrc 2>/dev/null || source ~/.bashrc++# 4. Verify — running 'hunt' with no args should print usage info+hunt+```++The last line should print:+```+Usage: hunt <target-name>+Creates a new engagement folder at $HUNT_BASE/<target-name>+Default $HUNT_BASE is /Users/you/Targets+```++If it says `command not found` instead, restart your terminal entirely and try again. Still failing? Go to [INSTALL.md → Troubleshooting](INSTALL.md#troubleshooting).++### Pick a practice target++If this is your first time, **do not point this at a real bug bounty program yet**. Practice on a deliberately-vulnerable site first so you get comfortable with the workflow before there are real stakes.++Three good first targets:++| Target | URL | Why |+|---|---|---|+| **OWASP Juice Shop** | https://juice-shop.herokuapp.com (or `docker run bkimminich/juice-shop`) | Designed for learning, every OWASP Top 10 bug is in there, no auth concerns |+| **Acunetix testphp** | http://testphp.vulnweb.com | Public, intentionally vulnerable, no signup |+| **HackerOne CTF (Hacker101)** | https://www.hacker101.com/ | Free CTF challenges by HackerOne, walkthroughs available |++### Walk through your first hunt on a practice target++```bash+# Set up an engagement folder+hunt juiceshop-practice+cd ~/Targets/juiceshop-practice++# Open Claude Code in this folder+claude+```++Claude Code opens. You'll see a prompt waiting for you to type. Copy-paste this:++> *I'm practicing on OWASP Juice Shop running at https://juice-shop.herokuapp.com. This is a deliberately vulnerable training app, no authorization concerns. Walk me through finding my first bug — start with how to do recon on this target.*++**What happens next:**+- Claude reads your `CLAUDE.md` (the engagement context file `hunt` created)+- Claude triggers `bb-methodology` (the 6-phase workflow) and walks you through Phase 1 (Scope)+- Claude asks: *"Is this practice / training mode? (No real submissions, just learning.)"* — say **yes**+- Claude triggers `web2-recon` or `offensive-osint` and gives you concrete commands to run++**You follow along.** Each time Claude gives you a command, paste it in another terminal tab and run it. Tell Claude what came back. Claude will spot vulnerable patterns and trigger the matching `hunt-*` skill.++For example, when you find Juice Shop's `/api/users` endpoint with an `id` parameter, Claude loads `hunt-idor` and walks you through testing for Insecure Direct Object Reference.++### Common beginner mistakes (and how the bundle prevents them)++1. **Filing a report for "200 OK on /admin without auth"** — the path 200's but content is the login page. Bundle catches this: `triage-validation` Q6 requires concrete impact (actual admin data shown), not "technically possible."+2. **Testing on out-of-scope assets** — bundle catches this: `triage-validation` Q3 explicitly asks scope.+3. **Submitting findings on the never-submit list** (missing security headers, clickjacking on non-sensitive pages, etc.) — bundle catches this: `triage-validation` Q7 has the rejection list.+4. **Sharing screenshots with cookies/PII visible** — bundle catches this: `evidence-hygiene` skill walks you through the redaction protocol BEFORE you take the screenshot.+5. **Brute-forcing a login form 10,000 times and getting your IP banned** — bundle catches this: `m365-entra-attack` + `bb-methodology` Part 3 enforce per-user attempt caps (1-2 max) with Smart Lockout math.++### Where to ask for help++- The bundle author: [GitHub Issues](https://github.com/elementalsouls/Claude-BugHunter/issues)+- HackerOne's bug-bounty Hacker Slack+- Bugcrowd's Discord+- Reddit r/bugbounty (read first, search second, ask last)++### When you're ready for a real bug bounty target++Once you've practiced on Juice Shop and run through the full workflow (recon → hunt → triage → report) at least once:++1. Sign up for HackerOne (`hackerone.com`) and/or Bugcrowd (`bugcrowd.com`)+2. Browse public programs — filter by **"VDP"** (vulnerability disclosure program, no payout but lower stress) first+3. Read the program's scope page carefully — paste it into Claude and ask it to parse with `bb-methodology`+4. Run `hunt <program-slug>` and start the same workflow you practiced++The skills behave the same on real and practice targets. The only difference is the report you produce at the end goes to a real program, not the trash.++---+## 1. Architecture overviewThe stack maps to a 6-phase bug-bounty workflow. Each phase has its own skill set; skills compose left-to-right through the workflow.