bb-huge 🤗

🤗 Join the bb-huge Community!

Find friends, share ideas, and start discussions with pro bug bounty hunters and software developers/engineers. Join the bb-huge Discord Server

/bb-huge — one command. Multi-Domain Security Expert, loaded. Not a portal. A Context Engineering Architecture that converts your AI agent into a disciplined hunter across Web, Mobile, Binary, and Source Code with a single slash command. The web UI is the visible tip — the real power is the 350+ curated security skills injected into the agent's brain.

|

The Architecture

┌─────────────────────────────────────────────────────────────┐
│                    YOUR AI AGENT                             │
│  (gemini-cli / claude-code / codex / emmu / any MCP client) │
└──────────┬─────────────────────────────────────┬────────────┘
           │  "/bb-huge"                         │  "find bugs on
           │  triggers skill                     │   example.apk"
           ▼                                     ▼
┌──────────────────────────┐    ┌──────────────────────────────┐
│  SKILL.md                │    │  MCP stdio Server            │
│  • Multi-Domain Persona  │    │  • 35+ tools (CRUD + stats)  │
│  • 7 SOPs loaded         │◄──►│  • stdio transport           │
│  • Field Dispatch system │    │  • stateless, fast           │
│  • 350+ Curated Skills   │    │  • any agent, same API       │
└──────────┬───────────────┘    └──────────┬───────────────────┘
           │                               │
           ▼                               ▼
┌──────────────────────────┐    ┌──────────────────────────────┐
│  references/ (12+ files) │    │  PORTAL (Flask + SQLite)     │
│  • Mobile Methodology    │    │  • Dashboard (Field Grouping)│
│  • Binary Analysis       │    │  • Findings CRUD (4 domains) │
│  • Source Code Audit     │    │  • Programs + Auto-Summary   │
│  • Field-routed Templates│    │  • Observations/Hypotheses   │
│  • Recon, Standards      │    │  • Evidence pipeline         │
│  • Eligible Vulns        │    │  • Assets & Endpoints        │
└──────────────────────────┘    │  • REST API                  │
                                │  • Webhooks (Discord/TG)     │
                                └──────────────────────────────┘

Two systems, one interface. The skill layer gives the agent domain-specific knowledge & discipline. The portal layer gives it persistent multi-field memory. They communicate through MCP.

The Signal Pipeline

bb-huge captures bug bounty work at every confidence level, from vague suspicion to confirmed payout:

Observation ──promote──► Hypothesis ──promote──► Finding
   (signal)                (candidate)            (confirmed)

Each step preserves provenance — a promoted finding keeps a link back to the hypothesis and observation it came from, along with the evidence that supports it.

Why This Works

Every bug hunter has the same problem: context resets to zero every session.

You spend 30 minutes re-reading your own notes, re-downloading attachments, trying to remember where you left off. Between sessions, you forget the half-baked hypothesis, the endpoint you were about to fuzz, the parameter that looked interesting.

bb-huge fixes this at the architectural level:

Problem	How bb-huge solves it
Agent forgets between sessions	Portal stores everything — findings, notes, attachments, evidence
You forget hunches and half-baked ideas	Observations & Hypotheses capture signals before they're findings
Losing evidence between sessions	Structured evidence records (Frida logs, disassembly, code snippets)
Disorganized attack surface	Assets & Endpoints track domains, APKs, binaries, and repos
One field only (Web)	Multi-Field support for Mobile, Binary, and Source Code Audit
You forget the methodology	Skill injects Multi-Domain Expert SOPs into every new session
You waste time on setup	`/bb-huge` command boots everything in one call
Testing blind — no context	Auto-Summarization Protocol identifies tech stack automatically
Limited expert knowledge	350+ Curated Security Skills injected into the agent's brain
Writing reports is painful	Field-routed report templates for every domain

📚 Curated Security Skills (350+)

bb-huge now comes bundled with a massive collection of 350+ community-sourced security skills, organized into 14 categories. This turns your AI agent into a polymath expert.

Web Security: XSS, SQLi, SSRF, JWT, GraphQL, WebSmuggling, etc.
Mobile: Android/iOS static & dynamic analysis, Frida, Deep Links.
Binary: Reverse engineering, Heap exploits, ROP, Ghidra/GDB SOPs.
Cloud/K8s: AWS, Azure, Docker escapes, RBAC misconfigs.
Offensive OSINT: Recon, Shodan, Subdomain discovery.
AI Security: Prompt injection, RAG poisoning, Model inversion.

Browse the collection: skills/curated/MANIFEST.md

What `/bb-huge` Actually Loads

When you type the command, the agent's brain gets injected with:

graph TB
    C["/bb-huge command"] --> SKILL[SKILL.md]
    SKILL --> SOP1["SOP-1: New Target<br/>Onboarding + Field Setup"]
    SKILL --> SOP2["SOP-2: Vulnerability Found<br/>Field-aware evidence pipeline"]
    SKILL --> SOP5["SOP-5: Pre-Hunt Q&A<br/>Domain-specific context"]
    SKILL --> SOP6["SOP-6: Report Prep<br/>Field-routed templates"]
    SKILL --> ASP["Auto-Summarization<br/>Tech stack identification"]
    SKILL --> DIS["Field Dispatch<br/>Methodology routing"]
    SKILL --> MCP["35+ MCP Tools<br/>Field filtering, Stats,<br/>Multi-domain CRUD"]
    SKILL --> CUR["350+ Curated Skills<br/>Community knowledge"]
    SKILL --> REFS["Reference Library"]
    REFS --> METH["Methodologies<br/>Mobile, Binary, Source"]
    REFS --> TEMP["Report Templates<br/>Field-routed index"]

    style C fill:#4a9,color:#fff
    style SKILL fill:#67b,color:#fff
    style MCP fill:#956,color:#fff
    style CUR fill:#c44,color:#fff
    style REFS fill:#567,color:#fff

~3,000+ lines of specialized knowledge — every session. The reference library and curated skills are lazy-loaded (you only pull what you need), but the core dispatch system is always active.

I WANT TO...

🚀 Set up bb-huge right now

Quick Start

git clone https://github.com/ShulkwiSEC/bb-huge.git
cd bb-huge
cp .env.example .env
# Edit .env — set SECRET_KEY and DEV_KEY

Run locally

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python run.py

Or with Docker

docker compose up -d

Open http://localhost:5000 — enter your DEV_KEY.

🤖 Connect my AI agent to bb-huge

The MCP server (mcp_server.py) uses stdio transport. Any MCP-compatible agent connects in seconds.

gemini-cli

Add to .gemini/settings.json (project or global):

{
  "mcpServers": {
    "bb-huge": {
      "command": "python",
      "args": ["/absolute/path/to/bb-huge/mcp_server.py"],
      "env": {
        "DEV_KEY": "your-dev-key",
        "BB_HUGE_URL": "http://127.0.0.1:5000"
      }
    }
  }
}

claude-code

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "bb-huge": {
      "command": "python",
      "args": ["/absolute/path/to/bb-huge/mcp_server.py"],
      "env": {
        "DEV_KEY": "your-dev-key",
        "BB_HUGE_URL": "http://127.0.0.1:5000"
      }
    }
  }
}

See mcp_config_examples.txt for codex, emmu, and other agents.

🧠 Load the Senior Bug Hunter skill

Copy the skill into your agent's skill directory:

cp -r skills/bb-huge ~/.gemini/skills/
# Project-local also works: .gemini/skills/bb-huge/

Now every time you type /bb-huge, the agent loads:

Senior Bug Hunter persona with capture-first discipline
7 Standard Operating Procedures (SOP-0 through SOP-6)
Full tool reference & severity/status guides
7 reference files covering methodology, recon, scope, reports, and scheduled missions
30+ MCP tools wired to your portal

The agent doesn't just "know about" bug bounty. It becomes a bug bounty hunter.

✅ Expected response when loading

After typing /bb-huge, the agent will acknowledge the injected methodology and prep the session.

Terminal / Text Output	Agent SOP Execution
🔵 bb-huge skill loaded — Senior Bug Hunter mode active 📊 Portal: 42 findings, 5 programs, 3 open observations 🔄 Resuming last session: finding #17 ❓ What target are we working on today?

If the agent does NOT acknowledge loading, does NOT run the Session Initialization Protocol, or seems confused → run the theory quiz.

📝 Log a finding immediately

From your agent:

bb_create_finding(title="IDOR on /api/users", target="api.example.com", severity="high")

That's it. The MCP server routes it to the portal. No browser, no forms, no friction.

The skill's #1 rule: capture first, enrich later. A thin entry now beats a perfect entry that never gets written. Fill in CWE, CVSS, PoC, and description as evidence accumulates.

graph LR
    A["Vulnerability Spotted"] --> B["bb_create_finding<br/>(status: discovered)"]
    B --> C["bb_upload_attachment<br/>(evidence files)"]
    C --> D["bb_update_finding<br/>(append PoC)"]
    D --> E["bb_update_status<br/>(confirmed)"]
    E --> F["bb_update_status<br/>(reported 🎯)"]
    F --> G["bb_update_status<br/>(rewarded 💰)"]

    style A fill:#c44,color:#fff
    style G fill:#4a4,color:#fff

🔍 Search and review findings

# From terminal (CLI script)
python skills/bb-huge/scripts/bb.py list --severity critical --status confirmed

# From agent
bb_list_findings(q="xss", severity="high")

# Get full detail
bb_get_finding(id=42)

Or open the web UI: http://localhost:5000/findings — filter by severity, status, agent, platform. Full-text search. CSV export.

📊 See my stats at a glance

# From agent
bb_get_stats()

# From terminal
python skills/bb-huge/scripts/bb.py stats

Returns totals by severity, status, and agent. The dashboard also renders bar charts for each dimension.

📎 Attach evidence to a finding

# From agent
bb_upload_attachment(id=42, file_path="./burp_request.txt")

# From terminal
python skills/bb-huge/scripts/bb-dump-attachments.py 42

Both scripts pull auth from environment variables (BB_HUGE_URL, DEV_KEY). No credentials hardcoded.

🔄 Resume work on a previous finding

SOP-3 handles this. The agent:

bb_get_finding(42) — reads current state, linked hypothesis & evidence
bb_generate_report_context(42) — gets evidence summary, unresolved gaps
python scripts/bb-dump-attachments.py 42 — pulls all attachments to local disk
Reads every attachment to restore full context
Gives you a one-paragraph summary of where things stand

Zero context loss between sessions. Even between different agents.

📬 Get notified when things happen

The portal supports Discord and Telegram webhooks. Configure in Settings → Webhooks.

The agent can notify on any event:

bb_notify(event="finding.confirmed", payload={"title": "RCE on admin panel", "message": "Go write the report!"})

Webhooks fire automatically on create/status-change if configured.

📋 Track multiple programs

Programs are first-class citizens. Each program tracks:

Platform (HackerOne, Bugcrowd, Intigriti, private)
Scope rules (in-scope / out-of-scope)
Findings, observations, hypotheses linked to it
Assets (domains, subdomains, API hosts, mobile apps, repos)
Endpoints (URL paths with method, protocol, auth info)
Recon entries (subdomains, technologies, parameters, credentials)

bb_create_program(name="Acme Corp", platform="HackerOne")
bb_add_recon(program_id=1, category="subdomain", value="admin.acme.com", source="subfinder")
bb_list_programs()

🔌 Use the REST API directly

All endpoints require X-Dev-Key header.

# Stats
GET    /api/v1/stats

# Enums
GET    /api/v1/enums

# Findings
GET    /api/v1/findings?q=&severity=&status=&agent=&limit=&offset=
POST   /api/v1/findings
GET    /api/v1/findings/<id>
PATCH  /api/v1/findings/<id>
DELETE /api/v1/findings/<id>
PATCH  /api/v1/findings/<id>/status
POST   /api/v1/findings/<id>/notes
DELETE /api/v1/notes/<id>
POST   /api/v1/findings/<id>/attachments
GET    /api/v1/findings/<id>/report-pack
GET    /api/v1/findings/similar?target=&cwe=&title=
PATCH  /api/v1/findings/bulk/status

# Programs
GET    /api/v1/programs
POST   /api/v1/programs
GET    /api/v1/programs/<id>
PATCH  /api/v1/programs/<id>
DELETE /api/v1/programs/<id>
GET    /api/v1/programs/<id>/context
PUT    /api/v1/programs/<id>/context
GET    /api/v1/programs/<id>/brief

# Recon
GET    /api/v1/programs/<id>/recon
POST   /api/v1/programs/<id>/recon
DELETE /api/v1/recon/<id>

# Observations
GET    /api/v1/programs/<id>/observations
POST   /api/v1/programs/<id>/observations
GET    /api/v1/observations/<id>
PATCH  /api/v1/observations/<id>
POST   /api/v1/observations/<id>/promote

# Hypotheses
GET    /api/v1/programs/<id>/hypotheses
POST   /api/v1/programs/<id>/hypotheses
GET    /api/v1/hypotheses/<id>
PATCH  /api/v1/hypotheses/<id>
POST   /api/v1/hypotheses/<id>/promote

# Evidence
GET    /api/v1/programs/<id>/evidence
POST   /api/v1/evidence
GET    /api/v1/evidence/<id>
PATCH  /api/v1/evidence/<id>

# Assets
GET    /api/v1/programs/<id>/assets
POST   /api/v1/programs/<id>/assets
PATCH  /api/v1/assets/<id>
DELETE /api/v1/assets/<id>

# Endpoints
GET    /api/v1/assets/<id>/endpoints
POST   /api/v1/assets/<id>/endpoints
PATCH  /api/v1/endpoints/<id>
DELETE /api/v1/endpoints/<id>

# Notifications
POST   /api/v1/notify

# Similarity check
POST   /api/v1/similarity/check

Example:

curl -X POST http://localhost:5000/api/v1/findings \
  -H "X-Dev-Key: your-dev-key" \
  -H "Content-Type: application/json" \
  -d '{"title":"Reflected XSS in search","target":"app.example.com","severity":"high","cwe":"CWE-79","cvss":7.2}'

🧪 Run the Theory Quiz (test your agent)

After loading /bb-huge, run the Theory Quiz to verify your agent fully understands the skill. 10 questions covering architecture, SOPs, tools, and workflow.

Pass threshold: 9/10 correct = agent is production-ready. Fail? Open an issue with the agent's output and question number.

🕒 Run bb-huge automatically on a schedule

Because of the SOP-0 scheduled mission protocol, you can easily run your agent fully hands-free on an hourly or daily basis. The agent will read its constraints from im-scheduled.md and execute without human input.

🤖 Native Agent Apps (OpenCode, Codex, etc.)

If your agent's UI already has a built-in task scheduler (like OpenCode), simply configure your time interval and paste this exact prompt into the task configuration:

/bb-huge This is a scheduled mission. Follow SOP-0 and execute.

❗If not (we can do it manuly)

🐧 Linux / WSL / macOS (Cron for CLI agents)

If you are using CLI agents, open your crontab (crontab -e) and add this line to run it at the top of every hour. Adjust the paths to your specific CLI tool and log directory.

Run hourly at minute 0

0 * * * * echo "/bb-huge This is a scheduled mission. Follow SOP-0 and execute." | opencode >> ~/.opencode/logs/bb-huge-hourly.log 2>&1

🪟 Windows (PowerShell + Task Scheduler)

Create a simple PowerShell script (e.g., hourly-hunt.ps1):

" /bb-huge This is a scheduled mission. Follow SOP-0 and execute." | opencode | Out-File -FilePath "$HOME\bb-huge-hourly.log" -Append

Open Task Scheduler, click Create Task.
Set Trigger: Daily, and check Repeat task every: 1 hour.
Set Action: Start a program, type powershell.exe, and add the argument -ExecutionPolicy Bypass -File C:\path\to\hourly-hunt.ps1.

(Note: Replace opencode with whichever CLI agent you are using).

🧪 Test MCP manually

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

Expect a JSON-RPC response with server capabilities. You can then pipe tools/list and tools/call messages.

🐳 Run everything in Docker

docker compose up -d

That's the whole command. The Dockerfile + docker-compose.yml handle the rest. Portal on :5000, ready to connect.

Everything in the Box

bb-huge/
├── app/
│   ├── __init__.py              # Flask app factory
│   ├── models.py                # 11 models: Finding, Attachment, Program,
│   │                            #   ReconEntry, Note, WebhookConfig,
│   │                            #   TargetContext, Observation, Hypothesis,
│   │                            #   EvidenceRecord, Asset, Endpoint
│   ├── migrations.py            # Schema migration functions
│   ├── routes/
│   │   ├── auth.py              # Login / logout
│   │   ├── findings.py          # Web UI: CRUD, upload, CSV, report-pack
│   │   ├── api.py               # REST API (45+ endpoints)
│   │   ├── programs.py          # Program management + observations,
│   │   │                        #   hypotheses, evidence, assets, recon
│   │   └── settings.py          # Webhooks, notes
│   ├── utils.py                 # File validation, webhook dispatch
│   ├── templates/               # 11+ Jinja2 templates (dark theme)
│   └── static/uploads/          # Attachment storage
├── skills/bb-huge/
│   ├── SKILL.md                 # The brain — agent instruction
│   ├── references/
│   │   ├── mobile-methodology.md        # Android/iOS hunting guide
│   │   ├── binary-analysis-methodology.md # RE & disassembly SOP
│   │   ├── source-code-audit-methodology.md # White-box SAST patterns
│   │   ├── mobile-report-templates.md   # Mobile-specific CWE templates
│   │   ├── binary-report-templates.md   # Binary/RE crash templates
│   │   ├── source-code-report-templates.md # Code-level vulnerability templates
│   │   ├── bb-operator.md               # Full hunting methodology
│   │   ├── bb-recon.md                  # Recon playbook + tool commands
│   │   ├── bb-eligible-vulnerabilities.md # Universal taxonomy (updated)
│   │   ├── bb-standards.md              # Evidence standards (updated)
│   │   ├── bb-report-templates.md       # Web templates & Field Index
│   │   ├── im-scheduled.md              # Scheduled mission routing
│   │   ├── bb-orchestrator.md           # Multi-skill coordination
│   │   └── tools-list.md                # Tool command reference
│   └── scripts/
│       ├── bb.py                        # CLI helper
│       └── bb-dump-attachments.py       # Download all evidence
├── skills/curated/
│   ├── MANIFEST.md              # Catalog of 350+ community skills
│   └── install.sh               # Cross-platform skill installer
├── mcp_server.py                # MCP stdio server (35+ tools)
├── THEORY_QUIZ.md               # 10-question agent comprehension test
├── tests/
│   └── test_api.py              # API integration tests
├── config.py                    # App configuration
├── run.py                       # Entry point (Flask / Waitress)
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── mcp_config_examples.txt

License

This project is licensed under the MIT License — see the LICENSE file for details.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

bb-huge 🤗

🤗 Join the bb-huge Community!

The Architecture

The Signal Pipeline

Why This Works

📚 Curated Security Skills (350+)

What `/bb-huge` Actually Loads

I WANT TO...

Quick Start

Run locally

Or with Docker

gemini-cli

claude-code

✅ Expected response when loading

🤖 Native Agent Apps (OpenCode, Codex, etc.)

❗If not (we can do it manuly)

🐧 Linux / WSL / macOS (Cron for CLI agents)

Run hourly at minute 0

🪟 Windows (PowerShell + Task Scheduler)

Everything in the Box

License

About

Uh oh!

Releases 1

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 81 Commits
.github		.github
app		app
assets		assets
skills		skills
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
THEORY_QUIZ.md		THEORY_QUIZ.md
config.py		config.py
docker-compose.yml		docker-compose.yml
mcp_config_examples.txt		mcp_config_examples.txt
mcp_server.py		mcp_server.py
requirements.txt		requirements.txt
run.py		run.py

Folders and files

Latest commit

History

Repository files navigation

bb-huge 🤗

🤗 Join the bb-huge Community!

The Architecture

The Signal Pipeline

Why This Works

📚 Curated Security Skills (350+)

What /bb-huge Actually Loads

I WANT TO...

Quick Start

Run locally

Or with Docker

gemini-cli

claude-code

✅ Expected response when loading

🤖 Native Agent Apps (OpenCode, Codex, etc.)

❗If not (we can do it manuly)

🐧 Linux / WSL / macOS (Cron for CLI agents)

Run hourly at minute 0

🪟 Windows (PowerShell + Task Scheduler)

Everything in the Box

License

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

What `/bb-huge` Actually Loads

Packages