ShulkwiSEC/bb-huge

What it is

bb-huge (MIT license) is a Flask/SQLite portal, a stdio MCP server (mcp_server.py) and a skill (skills/bb-huge/SKILL.md, invoked as /bb-huge) that give an AI agent persistent bug bounty state. The page names gemini-cli, claude-code, codex and emmu as supported clients. The portal stores findings, programs, observations, hypotheses, evidence, assets and endpoints. The skill loads a persona and SOPs, and the 350+ curated skills in skills/curated/ (catalogued in MANIFEST.md) are pulled in on demand.

How it works

The skill's first rule is "capture first, enrich later". A finding is created with a thin entry, then enriched as evidence arrives:

flowchart LR
    A[Spotted] --> B[bb_create_finding: discovered]
    B --> C[bb_upload_attachment]
    C --> D[bb_update_finding: append PoC]
    D --> E[confirmed]
    E --> F[reported]
    F --> G[rewarded]

Observations promote to hypotheses and then to findings through /promote endpoints, and each step keeps a link back to its source. Resuming work (SOP-3) calls bb_get_finding, then bb_generate_report_context, then bb-dump-attachments.py <id>, and the agent reads every attachment before summarising. Everything is also exposed as a REST API (/api/v1/..., header X-Dev-Key) and a CLI, skills/bb-huge/scripts/bb.py.

The page says SOP-0 supports unattended "scheduled missions", with constraints read from im-scheduled.md.

What to do

Local setup:

git clone https://github.com/ShulkwiSEC/bb-huge.git
cd bb-huge
cp .env.example .env   # set SECRET_KEY and DEV_KEY
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python run.py          # or: docker compose up -d

The portal is at http://localhost:5000. Register the MCP server in the agent's config with command: python, args: [/absolute/path/to/bb-huge/mcp_server.py] and env DEV_KEY and BB_HUGE_URL=http://127.0.0.1:5000. Install the skill with cp -r skills/bb-huge ~/.gemini/skills/.

Optional recon tooling installs under the home directory without root, and can be re-run to update or retry:

docker compose exec bb-huge bash assets/scripts/bb-install-tools.sh
bash assets/scripts/bb-install-tools.sh

It installs Go if missing, then subfinder, httpx, katana, dnsx, naabu, nuclei, notify, waybackurls, assetfinder, gf, anew, unfurl, qsreplace, gau, ffuf and amass.

To smoke-test the MCP server:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | DEV_KEY=your-dev-key python mcp_server.py

To check that an agent absorbed the skill, run THEORY_QUIZ.md (10 questions, pass at 9/10).

Caveats

• The scheduled mission example runs an agent hourly with no human input (0 * * * * echo "/bb-huge This is a scheduled mission. Follow SOP-0 and execute." | opencode ...). The Windows variant uses -ExecutionPolicy Bypass. The page does not say how scope is enforced during such runs, and the recon tools include active scanners (nuclei, naabu, ffuf), so check program rules first.
• A single DEV_KEY authenticates the whole REST API and the MCP bridge. The page says nothing about network exposure or hardening beyond the localhost examples.
• The page gives inconsistent counts: "30+" versus "35+" MCP tools, "7" versus "12+" or 14 reference files, and "11 models" with 12 listed. It reports no tests beyond tests/test_api.py and no usage results. The 350+ skills are described as community-sourced, and the page does not describe how they are vetted.