Skip to content

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.

Beginner-friendly Quick Start + USAGE Section 0

Sachin Sharma8dbca9ac4c40
diff --git a/README.md b/README.md
index 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 ~/Research
git 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.md
index 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 overview
The stack maps to a 6-phase bug-bounty workflow. Each phase has its own skill set; skills compose left-to-right through the workflow.