shulkwisec
03 Projects/Projects//16 min read

bb-huge: building a senior bug bounty hunter out of six layers

Forty to fifty minutes of a five or six hour hunting day go to remembering. Which endpoint I was about to fuzz three days ago. Which Burp attachment belongs to finding 42. Which program gave me a guest account and which one gave me an API key. None of that is testing, and all of it is what a senior hunter carries in their head between sessions.

The distance between having an agent and having one that hunts like a senior is not the model. It is the context architecture: what the session loads before it does anything, what it can call, what it remembers, who it can hand work to, and what runs while nobody is awake. Six layers. Each one stands alone, so you can deploy three and skip the rest, and the cost scales with what you switch on.

The six layers

Agent: Claude Code, OpenCode, Gemini CLI, Codex

1. Skills: SOPs loaded at session start

2. MCP tools: bb-huge, Burp, Kali, platform APIs

3. Portal: Flask and SQLite on localhost:5000

4. Sub-agents: orchestrator plus specialists

5. Scheduler: cron recon delta runs

6. Fine-tuning: QLoRA adapter on a 7B model

The layers are not a pipeline. Skills load every session whether or not anything else exists. The portal is worth running with no sub-agents at all. Fine-tuning is the only one I would leave off a first build.

Layer 1: skills, the methodology the session starts with

A skill is a markdown file full of methodology, loaded into the context window at session start. Not a system prompt, not a config file. It is the thing that decides whether the agent behaves like someone who has hunted this class of bug before or like autocomplete with a shell.

# /bb-huge Skill

You are a Senior Bug Bounty Hunter loaded with capture-first discipline.

## SOP-1: New Target Recon Setup
When the user says "/bb-huge" + target name:
1. Ask: What platform? (HackerOne, Bugcrowd, Intigriti?)
2. Ask: Any scope exclusions?
3. Load Pre-Hunt Q&A from portal
4. Stage your tools

The playbooks, in order

Five SOPs, and the order is the discipline:

  1. New target: /bb-huge plus a target name. Platform, scope exclusions, load the pre-hunt answers, stage the tools.
  2. Vulnerability found: capture first. Log a thin entry with bb_create_finding(), enrich it afterwards.
  3. Resume a finding: bb_get_finding(id), then bb_dump_attachments(id) to restore the evidence, then read the full context, then decide the next step.
  4. End session: summarise, confirm every critical finding is logged, and move each status through discovered, confirmed, reported, rewarded.
  5. New program: the pre-hunt questions, asked once and stored.

Step 2 exists because a perfect write-up of a finding you lost is worth nothing. Step 3 is the one that makes an overnight gap survivable.

What the core skill carries

The bb-huge skill is about 264 lines: the five SOPs, severity references, and five report templates (XSS, SQLi, IDOR, SSRF, stored XSS), each with title, description, severity, CVSS, CWE, PoC steps and remediation. Under references it holds a CWE taxonomy keyed to the classes I actually test: CWE-79 for XSS in all three variants, 89 for SQLi, 639 for authorization bypass and BOLA, 918 for SSRF, 352 for CSRF, 434 for file upload, 287 for authentication bypass, and about twenty more.

The skills I load

Skill What it carries Source
bb-huge the SOPs, taxonomy, templates skills/bb-huge in the repo
bb-recon subfinder, amass and ASNMap; nmap, masscan and Shodan queries; how to structure recon and deduplicate bb-huge/references/bb-recon.md
SAST XSS, SQLi, SSRF and RCE patterns in source, with Semgrep, CodeQL and AST parsing Pentest Agent Suite
hunt-xss parameter testing, DOM sink identification, WAF bypass, distilled from 681 or more disclosed reports Claude-BugHunter
hunt-ssrf AWS, GCP and Azure metadata endpoints, internal services, DNS rebinding, chaining SSRF with other bugs pentest-agents
Web3 auditor Solidity review, DeFi flow analysis, reentrancy, with Slither and Echidna Pentest Agent Suite
platform rules HackerOne and Bugcrowd scope rules, duplicate detection, what each platform rewards and how it scores bb-standards.md

The platform skill is not optional. Two platforms will score the same bug differently, and an agent that does not know which one it is on will draft the report for the wrong audience.

Layer 2: MCP tools, the hands

An MCP is the bridge between the agent describing an action and the action happening.

Agent: "I would run nmap against example.com"
You:   type nmap in the terminal, paste the output back into chat
Agent: "Here is what I found"

With a Kali MCP server in the loop, the same exchange is one tool call. The agent calls run_nmap, the server executes it and returns JSON, and the agent reads the result and picks the next step. That is worth about 35 minutes a session in tool integration alone.

The bb-huge tool surface

The findings server exposes 15 tools over stdio, which means any agent that speaks MCP can connect to it without state in between.

Tool What it does
bb_create_finding() log a vulnerability, thin entry now, enrich later
bb_get_finding(id) retrieve the full finding state
bb_update_finding(id) add a PoC, update the description, set the CWE
bb_upload_attachment(id, file_path) attach the Burp request, the screenshot, the PoC
bb_list_findings() search and filter
bb_get_context(program_id) load the pre-hunt answers
bb_create_program(name, platform) new program entry
bb_add_recon(program_id, category, value) log subdomains and endpoints
bb_get_stats() summary by severity and status
bb_update_status(id, status) discovered to confirmed to reported to rewarded
bb_notify(event, payload) fire the Discord or Telegram webhook

Four more are utilities. The server lives at mcp_server.py in the repo.

The rest of the rack

Server Tools I call Why it is there
Burp Suite MCP burp_get_scan_results(), burp_send_request(), burp_intruder(), burp_repeater() request and response pairs land in the agent’s context instead of my clipboard. The claimed effect is a 4x faster loop
Kali MCP run_nmap(), run_gobuster(), run_ffuf(), run_sqlmap(), run_metasploit_module() the whole Linux toolchain behind natural language. Free, local, no API cost, needs Docker or Kali with the tools installed
platform API MCPs scope, programs, report draft, submission status HackerOne, Intigriti, Bugcrowd, Immunefi for DeFi scope, YesWeHack for European programs
Octocode search_codebase(), get_file(), get_commits() source review against GitHub, GitLab or a local checkout
Firecrawl firecrawl_scrape(), firecrawl_map(), firecrawl_batch() asset discovery, JavaScript framework detection, site maps

The scope check is the one that earns its keep before a single request is sent. The agent asks whether example.com/admin is in scope and gets an answer from the platform instead of from my memory of a policy page I read last month. The three endpoints behind that are api.hackerone.com, api.bugcrowd.com and github.com/Intigriti/API.

Layer 3: the portal, memory that outlives the session

The portal is a Flask app and a SQLite database on my machine or a VPS. Between sessions nothing dies: the agent resumes exactly where it stopped because the state was never in the conversation.

HTTP POST / GET / PATCH

Agent: bb_get_finding(42), bb_upload_attachment(42, file), bb_update_status(42)

Flask app on localhost:5000

/api/v1/findings

/api/v1/findings/id/notes

/api/v1/programs/id/context

/api/v1/notify

SQLite findings.db

Discord and Telegram webhooks

Six tables carry it: findings, attachments, programs, recon_entries, notes, webhook_configs.

Capture first

The instinct is to analyse first and write the finding when it is complete. That instinct loses findings, because the session that ends mid-analysis takes the evidence with it.

XSS found on /search?q=
bb_create_finding(title="XSS on /search", target="example.com", severity="high")
Later: bb_update_finding(42, description="...", cwe="CWE-79", cvss=7.2)

A thin entry now beats a perfect entry never written. The notes table is the rest of the working memory: session logs and hypotheses that do not belong inside a finding. That is the scratchpad, and it is why a resumed session does not restart from zero.

Five questions, once per program

At the start of a new program the skill asks for what only I know:

  1. Do you have credentials, and at what level? Admin, user, guest, none.
  2. Any API keys or tokens to test with?
  3. Any endpoint or feature you already know is broken?
  4. Any recent code changes to focus on?
  5. Any area that always has bugs on this target?

The answers are stored per program, and every session after that loads them with bb_get_context(program_id). The agent never asks twice. Five minutes saved at the start of 250 sessions is 20 hours, against a minute of setup a year.

Recon deltas

Overnight recon only pays if the report is a delta, because the old assets were already tested.

OLD  287 subdomains, 42 live hosts, Node.js + React + PostgreSQL
NEW  291 subdomains, 45 live hosts, plus Redis

+ api-v2.example.com
+ legacy.example.com
+ staging-db.example.com
+ admin-panel.example.com
+ tech: Redis on 6379

Four new hosts is a morning’s work. A list of 291 is a week of ignoring it.

The review loop

A finding enters as discovered with whatever evidence exists at that second. The webhook fires. The status moves to confirmed when I have looked at the request or the screenshot attached to it, and the report agent drafts from confirmed findings only.

The 3 AM notification

[bb-huge] CRITICAL
Title:    RCE via arbitrary file upload
Target:   api.example.com
Severity: critical | CVSS: 9.8
Status:   discovered (waiting for your review)
Link:     http://localhost:5000/findings/127

I wake up, open the portal, look at the attached Burp request, and either confirm it or write down why it is wrong. The notification is not a result. It is a queue entry.

Layer 4: sub-agents, the muscle

A sub-agent is a specialist spawned by an orchestrator. Each one gets its own context window of 16K or 32K tokens, its own tool scope, its own skills, and its own worktree when the job is code review. The recon agent does not need Burp. The report agent does not need nmap. They do not talk to each other directly; they share a task list and a mailbox.

Orchestrator: plan the hunt, spawn, monitor, validate, prioritise

Recon agent

Hunter agent

SAST agent

Web3 agent

Report agent

Target and portal

The five roles

Agent Skills MCPs Job Output
Recon bb-recon.md, platform and scope rules Kali, Firecrawl, Shodan and Censys, platform API overnight recon, delta only subdomains, live hosts, tech stack, endpoint map
Hunter hunt-xss, hunt-ssrf, hunt-idor, hunt-sqli, each distilled from 100 or more reports bb-huge, Burp, Kali active testing on scoped targets confirmed vulnerabilities with a PoC
SAST hunt-rce, hunt-auth, hunt-llm-ai Octocode, Kali for Semgrep and ESLint, bb-huge read the codebase for patterns code-level findings with CWE
Web3 hunt-solidity, DeFi attack patterns Octocode, Kali for Slither and Mythril, bb-huge audit Solidity protocol-level bugs, unchecked reentrancy and similar
Report bb-report-templates.md, platform scoring rules bb-huge, platform API draft from confirmed findings submission-ready PoC and remediation

The orchestrator validates what comes back and flags conflicts before anything reaches the portal. Two agents reporting the same endpoint as two bugs is a duplicate the platform will score once.

Two ways to run the team

Claude Code has the Task tool built in:

const task = new Task({
  name: "Recon Scan",
  description: "Map assets and tech stack for example.com",
  agent: "recon-agent",
  tools: ["kali-mcp", "firecrawl-mcp"],
  skill: "skills/hunt-recon/SKILL.md"
});

await task.run();
// runs in a parallel worktree, reports back to the main agent

Simple syntax, managed context windows, and a hard limit of four parallel tasks. It only works in Claude Code.

OpenCode team mode is the more capable option. The team is a config file:

{
  "name": "hunting-team",
  "lead": { "kind": "subagent_type", "subagent_type": "sisyphus" },
  "members": [
    { "kind": "category", "name": "recon-scout", "category": "deep",
      "prompt": "Run comprehensive recon on the target." },
    { "kind": "subagent_type", "name": "hunter", "subagent_type": "sisyphus",
      "prompt": "Execute XSS and SSRF testing." },
    { "kind": "category", "name": "sast-reviewer", "category": "quick",
      "prompt": "Scan the codebase for high-severity patterns." }
  ]
}

Then it runs from the CLI:

team_create hunting-team
team_send_message recon-scout "Start subdomain enumeration"
team_status   # progress for every member

Eight members, four in parallel, a mailbox protocol, a shared task list, and mixed agent types in one team. The cost is more setup and being tied to OpenCode.

Layer 5: the scheduler, the clock

Manual hunting is reactive. Every day starts from whatever I remember. A scheduler turns the recon into a delta that is waiting at breakfast.

A week without it looks like this: five hours Monday for two bugs, five on Tuesday for one, five on Wednesday for none because the scope has not changed. With a 2 AM recon run, Monday morning starts with three new subdomains and the testing goes where the change is. The figure I use for the gain is three to five extra findings a week for no extra hours, and the mechanism is only that new assets get found before I sit down.

Cron, Task Scheduler, or a container

crontab -e

# recon at 2 AM daily, one program
0 2 * * * cd /home/user/bb-huge && python scripts/recon-scheduler.py --program example.com --agent recon-agent

# or every six hours across every active program
0 */6 * * * cd /home/user/bb-huge && python scripts/recon-scheduler.py --auto-all
$action = New-ScheduledTaskAction -Execute "python" -Argument "C:\bb-huge\scripts\recon-scheduler.py --auto-all"
$trigger = New-ScheduledTaskTrigger -Daily -At 2am
Register-ScheduledTask -TaskName "bb-huge-recon" -Action $action -Trigger $trigger -RunLevel Highest
FROM python:3.11

WORKDIR /app
COPY . .
RUN pip install -r requirements.txt

COPY crontab.txt /crontab.txt
RUN /usr/bin/crontab /crontab.txt

CMD ["cron", "-f"]

The delta script

scripts/recon-scheduler.py does four things: pull the last recon timestamp for a program, run recon through the agent, diff the two sets, and post the delta to the portal.

#!/usr/bin/env python3
# scripts/recon-scheduler.py
import os
import subprocess

import requests

PORTAL_URL = "http://localhost:5000"
API_KEY = os.getenv("BB_HUGE_API_KEY")

def get_last_recon(program_id):
    resp = requests.get(
        f"{PORTAL_URL}/api/v1/programs/{program_id}/recon",
        headers={"X-Dev-Key": API_KEY},
        params={"limit": 1, "sort": "date_desc"},
    )
    return resp.json()[0]["timestamp"] if resp.json() else None

def run_recon(program_name):
    result = subprocess.run([
        "python", "-m", "opencode", "run",
        f"Run comprehensive recon on {program_name}",
        "--agent", "recon-agent",
        "--skill", "skills/hunt-recon/SKILL.md",
    ], capture_output=True, text=True)
    return result.stdout

def compute_delta(program_id, subdomains_old, subdomains_new):
    return {
        "new": list(set(subdomains_new) - set(subdomains_old)),
        "deleted": list(set(subdomains_old) - set(subdomains_new)),
        "count_old": len(subdomains_old),
        "count_new": len(subdomains_new),
    }

The delta is set difference, which is the entire idea. log_recon_delta() posts it to /api/v1/programs/<id>/recon-report, and notify_new_findings() sends the first five new hosts to /api/v1/notify so the phone buzzes only when the set changed.

What a run looks like

[2024-05-16 02:00:00] Starting recon for program example.com
Running: subfinder -d example.com
Running: assetfinder --subs-only example.com
Running: amass enum -d example.com
Deduplicating...

OLD (2024-05-15):  287 subdomains, 42 live hosts, Node.js + React + PostgreSQL
NEW (2024-05-16):  291 subdomains, 45 live hosts, Redis added

DELTA:
  + api-v2.example.com        (200 OK)
  + legacy.example.com        (200 OK)
  + staging-db.example.com    (403 Forbidden)
  + admin-panel.example.com   (302 to login)
  + 10.0.0.55, 10.0.0.56, 10.0.0.57
  + Redis on 6379

Discord notification sent. Next run: 2024-05-17 02:00:00

Layer 6: fine-tuning, the edge

Skills beat fine-tuning for 90% of what I do here. Fine-tuning is worth the GPU when the target is the same one for the fiftieth time, when a platform has quirks nobody documented, when the agent keeps missing one class of bug, or when there are 100 or more confirmed findings to learn from. For general XSS, SSRF and IDOR work, on a new platform, or on a one-off engagement, a skill file is enough.

QLoRA on a 7B

An 8GB NVIDIA card is the floor. Unsloth does the training, and the portal exports the corpus:

git clone https://github.com/unslothai/unsloth
cd unsloth

python scripts/export-findings-to-training-data.py \
  --findings findings.db \
  --output training-data.jsonl \
  --min-confirmed-only

The format is instruction, input, output, one JSON object per line:

{"instruction": "Analyze this burp request for vulnerabilities", "input": "GET /api/users/123?id=456 HTTP/1.1\nHost: example.com\n...", "output": "IDOR vulnerability: the API does not validate user ownership. User 123 can access user 456's data. Severity: HIGH. CWE-639."}
{"instruction": "Review this Solidity code for security issues", "input": "contract Vault { mapping(address => uint) balances; function withdraw(uint amount) { balances[msg.sender] -= amount; msg.sender.call(amount); }}", "output": "Reentrancy in withdraw(): the external call happens before the state update. CWE-362."}

--min-confirmed-only matters. Training on discovered findings teaches the model my false positives.

huggingface-cli download mistralai/Mistral-7B-Instruct-v0.2

python unsloth/finetune_script.py \
  --model_name "mistralai/Mistral-7B-Instruct-v0.2" \
  --dataset "training-data.jsonl" \
  --output_dir "./bug-bounty-hunter-7b-lora" \
  --lora_rank 16 \
  --lora_alpha 32 \
  --lr 5e-4 \
  --epochs 3 \
  --batch_size 4

The output is a LoRA adapter around 200MB, not a second copy of the 7B model. You load it on top of the base at inference. Six hours on a single RTX 4090 is the whole bill.

What it buys: on the fiftieth pass over the same target the model stops walking the paths that never paid. That is a narrow gain, and it is the only one I would claim for it.

Distillation, zero GPU

Most of that gain is available without touching a GPU. Take the patterns out of your own last 100 findings and write them into a skill:

## Most Common Bugs in My Targets (Last 100 Findings)

### By platform
- HackerOne targets: 40% IDOR, 25% XSS, 20% SSRF, 15% other
- Bugcrowd targets: 30% auth bypass, 25% SQLi, 20% XSS, 25% other

### By tech stack
- GraphQL: test field-level authorization first (30% of findings)
- Node.js + Express: prototype pollution (15%)
- Serverless on Lambda: environment variable exposure (20%)

### By parameter name
- id, user_id, account: 60% likely IDOR
- file upload endpoints: type bypass
- GraphQL mutations: missing authorization checks

Then inject the two prompts the numbers justify:

HackerOne: "Focus on authorization bugs (IDOR, BOLA), then GraphQL
field-level bypasses, then parameter pollution. Look at how this program
structures its IDs."

Bugcrowd: "This platform favours authentication flaws. Test credential
spray, session fixation and JWT manipulation before general XSS."

The percentages come from your own sample, so they are only as good as that sample. The claim I will defend is 80% of what fine-tuning gives you for none of the GPU cost, and it scales to any model because it is just text.

Wiring it up

Prerequisites

Linux, Windows or WSL2. 8GB of RAM, Python 3.10 or newer, git. Docker is optional and only saves you the Flask setup. A HackerOne or Bugcrowd account for the API keys, and the platform MCPs install with them.

bb-huge and the portal

git clone https://github.com/ShulkwiSEC/bb-huge.git
cd bb-huge
python3 -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# .env
FLASK_ENV=development
SECRET_KEY=change-this
DEV_KEY=your-api-key-here
BB_HUGE_URL=http://127.0.0.1:5000
DATABASE_PATH=./findings.db

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your-webhook-id
TELEGRAM_BOT_TOKEN=your-telegram-bot-token
TELEGRAM_CHAT_ID=your-chat-id

HACKERONE_API_TOKEN=your-h1-token
INTIGRITI_API_KEY=your-intigriti-key
python run.py            # Flask dev server on http://localhost:5000
docker compose up -d     # or the container, same port

The agent

Claude Code, for a first build:

npm install -g @anthropic-ai/claude-code
claude-code init my-bug-bounty
mkdir -p my-bug-bounty/.claude/skills
cp -r ../bb-huge/skills/bb-huge my-bug-bounty/.claude/skills/
{
  "mcpServers": {
    "bb-huge": {
      "command": "python",
      "args": ["/path/to/bb-huge/mcp_server.py"],
      "env": {
        "DEV_KEY": "your-api-key",
        "BB_HUGE_URL": "http://127.0.0.1:5000"
      }
    }
  },
  "skillPaths": ["/path/to/bb-huge/skills/"]
}

That config goes in ~/.claude/claude_desktop_config.json. OpenCode takes the same server block under mcp_servers in .opencode/opencode.json, plus the team config from layer 4 in .omo/teams/hunting-team/config.json.

Gemini CLI configures the same server in .gemini/mcp.json:

npm install -g @google/gemini-cli
gemini auth login
gemini create my-bb-project \
  --skills /path/to/bb-huge/skills/ \
  --mcp /path/to/bb-huge/mcp_server.py

The security MCPs

Burp: install MCP from the BApp store, then enable the server under Extender and set the port. The default is 8888.

git clone https://github.com/kalilinux/kali-mcp-server
cd kali-mcp-server
docker build -t kali-mcp .
docker run -d -p 3000:3000 --name kali-mcp kali-mcp

The HackerOne MCP is the same shape as any other: clone, install, export the token, add the command to the agent config.

git clone https://github.com/bug-bounty-ai/hackerone-mcp
cd hackerone-mcp
pip install -r requirements.txt
export HACKERONE_API_TOKEN="your-token"

skills.sh

One skill directory per agent gets old at thirty skills and four agents.

git clone https://github.com/skills-sh/skills.sh
cd skills.sh
chmod +x skills.sh
sudo ln -s $(pwd)/skills.sh /usr/local/bin/skills

skills init ~/.skills
skills repo add bb-huge https://github.com/ShulkwiSEC/bb-huge/tree/main/skills
skills repo add pentest-agents https://github.com/H-mmer/pentest-agents/tree/main/skills
skills repo add claude-bughunter https://github.com/elementalsouls/Claude-BugHunter/tree/main/skills
skills repo add transilience https://github.com/transilienceai/communitytools/tree/main/skills

The sync is the command worth having. It detects each agent on the machine, copies the skills into each skill directory, updates the configs, and verifies they load:

skills sync --agents claude-code,opencode,gemini-cli,codex
skills sync --agents claude-code --skills bb-huge,hunt-xss,hunt-ssrf,bb-recon
skills sync --target /mnt/shared-skills --agents all

The other four I use: skills update, skills verify for conflicts across repos, skills show-usage to see which agent has which skill, and skills create my-skill --template vulnerability-hunter --category web to scaffold SKILL.md, references/ and scripts/. ~/.skills/config.json holds the repo list, each agent’s skill directory and config file, plus the auto-update and daily sync schedule.

The skill repos themselves, since the quality varies more than the README suggests:

Repo Contents
ShulkwiSEC/bb-huge core methodology, about 500 lines, SOPs, taxonomy, templates
H-mmer/pentest-agents 48 specialised hunters, 2,000 or more lines, a catalogue distilled from 1,218 real reports
elementalsouls/Claude-BugHunter 71 skills, 24 vulnerability classes, enterprise chains for M365 and Entra ID, Okta, vCenter, Android APKs, containers
transilienceai/communitytools 26 skills, coordination patterns and validation gates, aimed at false-positive reduction

Everything else in the rack comes from the official registry at github.com/modelcontextprotocol/servers, with github.com/punkpeye/awesome-mcp-servers as the community index and the protocol defined at spec.modelcontextprotocol.io.

One session, start to finish

/bb-huge

> bb-huge skill loaded
> Portal: 0 findings, 0 programs
> Pre-hunt Q&A not filled. Let's set up.
You:    My target is example.com on HackerOne
Agent:  One-time setup. Do you have credentials? (admin, user, guest, none)
You:    A user account, hunter@example.com, password in 1password
Agent:  Stored. Any API keys or tokens to test with?

The questions run once, then the portal has the program context. From there:

You:    Start with reconnaissance
Agent:  [Kali MCP] nmap example.com
        [Kali MCP] subfinder -d example.com
        [Kali MCP] assetfinder --subs-only example.com
        287 subdomains, 42 live hosts, Node.js, React, PostgreSQL
        bb_create_program(name="example.com", platform="HackerOne")
        bb_add_recon(program_id=1, category="subdomain", count=287)
You:    Fuzz endpoints
Agent:  Testing /api/users, /api/posts, /api/comments for IDOR
        [Burp Suite MCP] requests with varied ids

        IDOR on /api/users/{id}
        User 123 reads user 456's data. HIGH, CVSS 7.5, CWE-639

        bb_create_finding(...)
        bb_upload_attachment(id=1, file="burp_idor_request.txt")

The finding exists before the report does. Next session, /bb-huge loads the program, the answers and the open findings, and the work resumes at the endpoint instead of at the start.

When it breaks

MCP connection failed. Check the portal is alive and the key matches before restarting anything:

curl http://localhost:5000/api/v1/stats -H "X-Dev-Key: your-key"
echo $BB_HUGE_API_KEY
pkill -f mcp_server.py && python bb-huge/mcp_server.py &

Skill not found. The path in the config is wrong more often than the file is missing:

grep skillPaths ~/.claude/claude_desktop_config.json
ls -la ~/.claude/skills/bb-huge/SKILL.md

Out of scope tests ran. bb_get_context() came back without scope rules, so the agent had nothing to check against. Fill the pre-hunt Q&A, or set the rules directly:

curl -X PUT http://localhost:5000/api/v1/programs/1/context \
  -H "X-Dev-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"in_scope": ["example.com", "*.example.com", "api.example.com"],
                "out_of_scope": ["admin.example.com", "internal.example.com"]}}'

A missing scope list is how an agent ends up testing a host the program excluded.

skills.sh not found. The symlink did not land, or the PATH is stale:

sudo ln -s /path/to/skills.sh/skills.sh /usr/local/bin/skills
echo 'export PATH="$PATH:/path/to/skills.sh"' >> ~/.bashrc

Where a human still has to decide

Scope is mine. The platform MCP returns the rules and the agent checks against them, but a wildcard in a scope list, a staging host that looks internal, a program that quietly excludes a path, all of that is a judgement about a relationship I am the one holding. The out-of-scope failure above is what happens when the machine is asked to make that call with no context.

A finding is a claim until I have looked at the evidence. The status machine exists for this: discovered is the machine’s opinion, confirmed is mine, and the report agent will not draft from anything below it. A confident agent plus a wrong request is the fastest way to file a report that does not reproduce.

Severity and duplicates are platform judgement. The report agent knows that HackerOne and Bugcrowd score differently, but whether a bug is a duplicate depends on the program’s history, and whether it is critical depends on what the asset is worth to the customer.

The pre-hunt answers are context I have and the model does not: credentials, known-broken endpoints, what shipped last week, which area always has bugs. Nothing in the stack can derive those, which is why they are asked once and stored rather than guessed per session.

Which target to hunt is not automatable either. A scheduler can tell me four subdomains appeared overnight. It cannot tell me which of the four is worth the afternoon.

And the decision to submit is mine. The report agent drafts it, the platform MCP can file it, and neither should fire without a read.

The order I would build it in

Doing all six at once is how a weekend disappears. The staging I would use:

This week. The portal locally, one agent installed, the core skill copied, /bb-huge run once, and the pre-hunt questions answered for a single target.

This month. Kali MCP for recon, Burp MCP for web testing, five to ten specialised skills, and a first sub-agent workflow against a real target.

This quarter. The scheduler for overnight recon, custom skills written from your own findings, the optional 7B fine-tune, and the platform quirks written down where the next session can read them.

This year. A repeatable process per platform, team mode once more than one person is hunting, and findings contributed back to the skill repos.

What to take from this one

The pattern generalises past bug bounty, because it is not really about hunting:

  • Write the methodology down before you write the tools. The five SOPs change behaviour on day one and cost a markdown file. A tool with no procedure behind it just makes the agent faster at improvising.
  • Move the state out of the conversation. The portal is the reason an overnight gap costs nothing. If your agent’s memory is the context window, every session starts by rebuilding what you already knew.
  • Capture before you analyse. A thin record now survives a crash, a context limit and a bad night. The perfect record that was never written does not.
  • Give each specialist a narrow tool scope. A recon agent does not need Burp in front of it, and the less a specialist can reach, the less it does by accident.
  • Make the output a delta. Whatever runs on a schedule should tell you what changed, not what exists. The full list is how a useful overnight job becomes an ignored morning one.
  • Keep one gate that only a human can pass. Whether it is a finding moving to confirmed or a report moving to submitted, the gate is where the autonomy stops being a liability.
  • Reach for fine-tuning last. A distilled skill written from your own confirmed findings is text, runs anywhere, and does most of the job.

Build it in the order the layers were listed and each one stays optional, which is the property that matters. The failure mode is building the tools first: the agent gets faster at improvising, the context window fills with raw output, and the model takes the blame for an architecture problem.