bb-huge: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

bb-huge is two things wired together over MCP:

1. Portal (app/) — a Flask + SQLAlchemy (SQLite) web app that stores bug bounty findings, programs, recon data, observations/hypotheses, evidence, assets, and endpoints. It has a dashboard UI and a REST API.
2. Skill layer (skills/bb-huge/) — a SKILL.md persona + reference docs that, when loaded into an AI agent (Claude Code, gemini-cli, codex, etc.), turns it into a disciplined bug bounty hunter that calls the portal's API via MCP tools as it works.

mcp_server.py is the bridge: a stdio MCP server that translates ~35 MCP tool calls (bb_create_finding, bb_get_program_brief, ...) into REST calls against the running Flask portal. Any MCP-compatible agent can drive the portal through it.

skills/curated/ is a separate, large (350+) bundle of community security skills (per vuln class, per platform, per technique) that get lazy-loaded on demand — not core to the portal itself.

Running the portal

cp .env.example .env        # set SECRET_KEY and DEV_KEY before anything else
python -m venv .venv && source .venv/bin/activate   # (or .venv\Scripts\activate on Windows)
pip install -r requirements.txt
python run.py                # serves on :5000 (waitress in prod, Flask dev server if FLASK_DEBUG=1)

Docker: docker compose up -d (same port).

Auth is a single shared DEV_KEY, not per-user accounts:

• Web UI: session cookie set via /login (form posts dev_key, compared in app/routes/auth.py).
• REST API: X-Dev-Key header (or ?dev_key=) checked in app/routes/api.py, required on every /api/v1/* call.

Tests

python -m unittest tests/test_api.py -v          # whole file
python -m unittest tests.test_api.V2ApiTests.test_program_brief_includes_new_entities  # single test

Tests spin up a real create_app() instance against a temp SQLite DB + temp upload dir per test (see TestConfig / setUp in tests/test_api.py) — no mocking of the DB layer. Follow this pattern (fresh app + tempdir per test) for new API tests rather than reusing a shared instance.