bugbounty.sa (bbsa)

Read-only CLI + MCP server for bugbounty.sa — query programs, reports, invoices, the leaderboard, and notifications from your terminal or your agent. Report submission stays strictly manual.

• CLI: bbsa
• MCP server: bbsa-mcp
• Repo: github.com/ShulkwiSEC/bugbounty.sa

Features

• bbsa CLI — agent- and human-friendly: stable --json on every command, ANSI color only on a TTY, tab-separated plain output when piped, errors on stderr, exit codes 0/1/2/3.
• MCP server — 14 read-only tools + a bugbounty://me/profile resource for Claude, OpenCode, Gemini, etc.
• Read-only by construction — every request is GET. No mutations exist anywhere in the codebase.
• One HTTP layer — the CLI and the MCP server share a single api.py; no duplicated request handling, no drift.

Install

Requires Python 3.12+.

From PyPI (recommended)

# run without installing
uvx --from bugbounty.sa bbsa
# or install permanently:
uv tool install bugbounty.sa
# or with pip:
pip install bugbounty.sa

From source (dev)

uv tool install git+https://github.com/ShulkwiSEC/bugbounty.sa
# or, from a clone:
uv pip install -e .

Agent skill (auto-install)

The package ships a skills.sh-compatible agent skill. The first run of bbsa or bbsa-mcp silently installs it into every detected coding agent — no user interaction:

*opencode auto-loads ~/.claude/skills, so its own folder is skipped while Claude Code is present to avoid duplicates.

The install is idempotent: it skips when the bundled SKILL.md already matches, so the CLI stays silent on every run after the first.

Manual install

To install (or refresh) the skill by hand, copy SKILL.md from the repo into the target agent's folder:

# Claude Code (also covers opencode)
mkdir -p ~/.claude/skills/bbsa
curl -fsSL https://raw.githubusercontent.com/ShulkwiSEC/bugbounty.sa/main/SKILL.md \
  -o ~/.claude/skills/bbsa/SKILL.md

# Codex
mkdir -p ~/.codex/skills/bbsa
curl -fsSL https://raw.githubusercontent.com/ShulkwiSEC/bugbounty.sa/main/SKILL.md \
  -o ~/.codex/skills/bbsa/SKILL.md

# opencode (only if you don't use Claude Code)
mkdir -p ~/.config/opencode/skills/bbsa
curl -fsSL https://raw.githubusercontent.com/ShulkwiSEC/bugbounty.sa/main/SKILL.md \
  -o ~/.config/opencode/skills/bbsa/SKILL.md

Then restart your agent — skills are loaded at startup.

Setup

export BUGBOUNTY_SA_TOKEN="your-bugbounty-sa-token"

The token is your bugbounty.sa API token. Without it, private endpoints return a clear 401 telling you exactly what to set.

Usage

Quick tour

bbsa me                        your researcher profile
bbsa programs list             active programs
bbsa programs show <ID>        scope, policy, reward ranges, domains
bbsa reports list              your reports
bbsa reports show <ID-or-slug> one report's detail
bbsa reports stats [--group]   counts by status|severity|type
bbsa finance invoices          your invoices
bbsa finance stats             invoice totals (paid / unpaid)
bbsa leaderboard               top 10 researchers (public)
bbsa notifications             your notifications

Examples

$ bbsa programs list
ID    NAME              TYPE    STATUS  PLATFORM  ENDS
1475  CoderHub          public  active  Web       2027-08-31T21:00:00.000000Z
1474  Tuwaiq Academy    public  active  Web       2027-08-30T21:00:00.000000Z
313   Flagyard Platform public  active  Web       2026-12-31T03:00:05.000000Z

Next: bbsa programs show <ID> for scope, policy, reward ranges

Every command produces stable JSON with --json, so it drops straight into pipelines:

bbsa leaderboard --json | jq -r '.data[] | "\(.rank) \(.username)"'
bbsa reports list --json | jq -c '.data[] | select(.severity == "high")'
bbsa programs show 1475 --json | jq .data.domains

Exit codes: 0 ok, 1 error, 2 usage, 3 not found. --debug prints full tracebacks; --no-color forces plain output for scripting.

MCP server

After installing from PyPI (uv tool install bugbounty.sa or pip install bugbounty.sa), bbsa-mcp is on your PATH:

{
  "mcpServers": {
    "bugbounty.sa": {
      "command": "bbsa-mcp",
      "env": { "BUGBOUNTY_SA_TOKEN": "<your-token>" }
    }
  }
}

Or run directly without installing:

{
  "mcpServers": {
    "bugbounty.sa": {
      "command": "uvx",
      "args": ["--from", "bugbounty.sa", "bbsa-mcp"],
      "env": { "BUGBOUNTY_SA_TOKEN": "<your-token>" }
    }
  }
}

Tools: list_programs, get_program_scope, list_reports, get_report, get_report_stats, get_wallet_balance, list_invoices, get_invoice_stats, list_transactions, get_transaction_stats, get_public_leaderboard, list_companies, get_company, list_notifications. Resource: bugbounty://me/profile (GET /me).

Example

Agent prompts that work with the MCP server connected to your client (the agent calls the tools itself — no CLI needed):

1. Investigate your open work

   "List my reports, then for any still in triage pull the full detail and summarize the status, severity, and next step I should take for each."

2. Recon a program before hunting

   "Show me the active programs, then for the highest-bounty public one give me its full scope, reward ranges, and target domains."

3. Market-scan as a researcher

   "Write a short briefing: who's leading the researcher leaderboard, which recent notifications or new programs are relevant to me, and how my profile compares."

Contributing

Issues and PRs welcome at github.com/ShulkwiSEC/bugbounty.sa/issues. Keep it read-only: no write endpoints, no new dependencies without a good reason.

License

Apache-2.0 — full text in LICENSE.