bugbounty.sa 0.1.0__tar.gz

bugbounty_sa-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: bugbounty.sa
+Version: 0.1.0
+Summary: bugbounty.sa(bbsa): read-only CLI + MCP server for bugbounty.sa — programs, reports, finance, leaderboard
+Keywords: bugbounty,mcp,cli,bug-bounty,security,researcher
+Author: shulkwisec
+Author-email: shulkwisec <shulkwisec@gmail.com>
+License-Expression: Apache-2.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/ShulkwiSEC/bugbounty.sa
+Description-Content-Type: text/markdown
+
+# bugbounty.sa (bbsa)
+![bbsa demo](demo.gif)
+
+
+Read-only CLI + MCP server for [bugbounty.sa](https://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](https://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+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv tool install git+https://github.com/ShulkwiSEC/bugbounty.sa
+# or, from a clone:
+uv pip install -e .
+```
+
+Dependencies: [`httpx`](https://www.python-httpx.org/) (HTTP), [`mcp`](https://github.com/modelcontextprotocol/python-sdk) (MCP server). Build backend: [`uv_build`](https://docs.astral.sh/uv/concepts/build-backend/). The distribution is published on PyPI as `bugbounty.sa`; the import package is `bbsa`.
+
+## Setup
+
+```bash
+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
+
+```console
+$ 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:
+
+```bash
+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
+
+```json
+{
+  "mcpServers": {
+    "bugbounty.sa": {
+      "command": "bbsa-mcp",
+      "env": { "BUGBOUNTY_SA_TOKEN": "<your-token>" }
+    }
+  }
+}
+```
+
+Or via `uv run`:
+
+```json
+{
+  "mcpServers": {
+    "bugbounty.sa": {
+      "command": "uv",
+      "args": ["run", "bbsa-mcp"],
+      "cwd": "/path/to/repo",
+      "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](https://github.com/ShulkwiSEC/bugbounty.sa/issues). Keep it read-only: no write endpoints, no new dependencies without a good reason.
+
+## License
+
+[Apache-2.0](LICENSE) — full text in [`LICENSE`](LICENSE).

bugbounty_sa-0.1.0/README.md

@@ -0,0 +1,126 @@
+# bugbounty.sa (bbsa)
+![bbsa demo](demo.gif)
+
+
+Read-only CLI + MCP server for [bugbounty.sa](https://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](https://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+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv tool install git+https://github.com/ShulkwiSEC/bugbounty.sa
+# or, from a clone:
+uv pip install -e .
+```
+
+Dependencies: [`httpx`](https://www.python-httpx.org/) (HTTP), [`mcp`](https://github.com/modelcontextprotocol/python-sdk) (MCP server). Build backend: [`uv_build`](https://docs.astral.sh/uv/concepts/build-backend/). The distribution is published on PyPI as `bugbounty.sa`; the import package is `bbsa`.
+
+## Setup
+
+```bash
+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
+
+```console
+$ 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:
+
+```bash
+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
+
+```json
+{
+  "mcpServers": {
+    "bugbounty.sa": {
+      "command": "bbsa-mcp",
+      "env": { "BUGBOUNTY_SA_TOKEN": "<your-token>" }
+    }
+  }
+}
+```
+
+Or via `uv run`:
+
+```json
+{
+  "mcpServers": {
+    "bugbounty.sa": {
+      "command": "uv",
+      "args": ["run", "bbsa-mcp"],
+      "cwd": "/path/to/repo",
+      "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](https://github.com/ShulkwiSEC/bugbounty.sa/issues). Keep it read-only: no write endpoints, no new dependencies without a good reason.
+
+## License
+
+[Apache-2.0](LICENSE) — full text in [`LICENSE`](LICENSE).

bugbounty_sa-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "bugbounty.sa"
+version = "0.1.0"
+description = "bugbounty.sa(bbsa): read-only CLI + MCP server for bugbounty.sa — programs, reports, finance, leaderboard"
+readme = "README.md"
+keywords = [
+    "bugbounty",
+    "mcp",
+    "cli",
+    "bug-bounty",
+    "security",
+    "researcher",
+]
+license = "Apache-2.0"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[[project.authors]]
+name = "shulkwisec"
+email = "shulkwisec@gmail.com"
+
+[project.scripts]
+bbsa-mcp = "bbsa:main"
+bbsa = "bbsa.cli:main"
+
+[project.urls]
+Repository = "https://github.com/ShulkwiSEC/bugbounty.sa"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "bbsa"

bugbounty_sa-0.1.0/pyproject.toml.orig

@@ -0,0 +1,30 @@
+[project]
+name = "bugbounty.sa"
+version = "0.1.0"
+description = "bugbounty.sa(bbsa): read-only CLI + MCP server for bugbounty.sa — programs, reports, finance, leaderboard"
+readme = "README.md"
+authors = [
+    { name = "shulkwisec", email = "shulkwisec@gmail.com" }
+]
+keywords = ["bugbounty", "mcp", "cli", "bug-bounty", "security", "researcher"]
+license = "Apache-2.0"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+bbsa-mcp = "bbsa:main"
+bbsa = "bbsa.cli:main"
+
+[project.urls]
+Repository = "https://github.com/ShulkwiSEC/bugbounty.sa"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+# Distribution is "bugbounty.sa"; the import package/module dir is "bbsa".
+[tool.uv.build-backend]
+module-name = "bbsa"

bugbounty_sa-0.1.0/src/bbsa/__init__.py

@@ -0,0 +1,134 @@
+"""Read-only MCP server for bugbounty.sa — tools + 1 resource.
+
+Shares the HTTP layer with the bbsa CLI (see `api.py`).
+"""
+
+from __future__ import annotations
+
+from mcp.server.mcpserver import MCPServer
+
+from bbsa.api import get as _get
+
+mcp = MCPServer("bugbounty-sa")
+
+
+# ── Programs ─────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def list_programs() -> dict:
+    """List active programs on bugbounty.sa."""
+    return _get("/programs")
+
+
+@mcp.tool()
+def get_program_scope(program_id: int) -> dict:
+    """Get full program detail: scope, policy, reward ranges, domains."""
+    return _get(f"/programs/{program_id}")
+
+
+# ── Reports ──────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def list_reports() -> dict:
+    """List your submitted reports with triage status."""
+    return _get("/reports")
+
+
+@mcp.tool()
+def get_report(report_id_or_slug: str) -> dict:
+    """Get single report detail by ID or slug."""
+    return _get(f"/reports/{report_id_or_slug}")
+
+
+@mcp.tool()
+def get_report_stats(group_by: str = "status") -> dict:
+    """Dashboard stats: report counts grouped by status/severity/type."""
+    return _get("/reports/stats/grouped", {"groupBy": group_by})
+
+
+# ── Finance ──────────────────────────────────────────────────────────
+# ponytail: role-gated — wallet/transactions verified 403 with a researcher
+# token (invoices work, that's the researcher payout surface).
+
+
+@mcp.tool()
+def get_wallet_balance() -> dict:
+    """Get account wallet balance and total payout stats (company/admin role)."""
+    return _get("/wallet/balance")
+
+
+@mcp.tool()
+def list_invoices() -> dict:
+    """List bounty invoices."""
+    return _get("/invoices")
+
+
+@mcp.tool()
+def get_invoice_stats() -> dict:
+    """Invoice summary stats."""
+    return _get("/invoices/stats")
+
+
+@mcp.tool()
+def list_transactions() -> dict:
+    """List payment/transaction history."""
+    return _get("/transactions")
+
+
+@mcp.tool()
+def get_transaction_stats() -> dict:
+    """Transaction summary stats."""
+    return _get("/transactions/stats")
+
+
+# ── Leaderboard ───────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def get_public_leaderboard() -> dict:
+    """Top 10 researchers leaderboard (public, no auth needed)."""
+    return _get("/leaderboard")
+
+
+# ── Companies ────────────────────────────────────────────────────────
+# ponytail: role-gated — verified 403 with a researcher token. Keep for
+# admin/company tokens; drop these tools if the server is researcher-only.
+
+
+@mcp.tool()
+def list_companies() -> dict:
+    """List companies on the platform."""
+    return _get("/companies")
+
+
+@mcp.tool()
+def get_company(company_id: int) -> dict:
+    """Get company detail by ID."""
+    return _get(f"/companies/{company_id}")
+
+
+# ── Notifications ────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def list_notifications() -> dict:
+    """List notifications (unread count, recent alerts)."""
+    return _get("/notifications")
+
+
+# ── Resource ─────────────────────────────────────────────────────────
+
+
+@mcp.resource("bugbounty://me/profile")
+def get_my_profile() -> dict:
+    """Current researcher account profile."""
+    return _get("/me")
+
+
+# ── Entry point ──────────────────────────────────────────────────────
+
+
+def main() -> None:
+    mcp.run()

bugbounty_sa-0.1.0/src/bbsa/api.py

@@ -0,0 +1,86 @@
+"""Shared HTTP layer for bugbounty.sa — used by both the MCP server and the CLI.
+
+Read-only by design: the only verb ever issued is GET.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import httpx
+
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logging.getLogger("httpcore").setLevel(logging.WARNING)
+
+BASE_URL = "https://api.bugbounty.sa/api"
+HEADERS = {
+    "Accept": "application/json",
+    "Content-Type": "application/json",
+    "Accept-Language": "en",
+    "tz": "Asia/Riyadh",
+}
+
+
+class ApiError(Exception):
+    """Raised on any failed request. code + retryable let consumers act on it."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "api_error",
+        retryable: bool = False,
+        status: int | None = None,
+    ):
+        super().__init__(message)
+        self.code = code
+        self.retryable = retryable
+        self.status = status
+
+
+def _err_text(r: httpx.Response) -> str:
+    try:
+        return r.json().get("message") or r.text[:200]
+    except Exception:
+        return r.text[:200]
+
+
+def get(path: str, params: dict | None = None) -> dict:
+    """Single GET helper. Returns the full JSON envelope. Raises ApiError."""
+    token = os.environ.get("BUGBOUNTY_SA_TOKEN", "")
+    headers = dict(HEADERS)
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    try:
+        r = httpx.get(f"{BASE_URL}{path}", params=params, headers=headers, timeout=30)
+    except httpx.HTTPError as exc:
+        raise ApiError(
+            f"Request to {path} failed: {exc}", code="network_error", retryable=True
+        ) from exc
+
+    if r.status_code < 400:
+        return r.json()
+
+    msg = _err_text(r)
+    if r.status_code == 401:
+        raise ApiError(
+            "Unauthenticated. Set BUGBOUNTY_SA_TOKEN to a bugbounty.sa bearer token.",
+            code="unauthenticated",
+            retryable=True,
+            status=401,
+        )
+    if r.status_code == 403:
+        raise ApiError(
+            msg or "Forbidden — this token's role lacks access to the endpoint.",
+            code="forbidden",
+            retryable=False,
+            status=403,
+        )
+    if r.status_code == 404:
+        raise ApiError(msg or "Not Found.", code="not_found", retryable=False, status=404)
+    raise ApiError(
+        msg or "API error.",
+        code="http_error",
+        retryable=r.status_code >= 500,
+        status=r.status_code,
+    )

bugbounty_sa-0.1.0/src/bbsa/cli/__init__.py

@@ -0,0 +1,179 @@
+"""bbsa — read-only bugbounty.sa CLI.
+
+Divides into a `src/bbsa/api.py` (shared HTTP), a
+`formatters.py` (stable JSON, exit codes, tables) and one `commands/*` module
+per resource, mirroring the oh-my-ctf CLI conventions.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from bbsa import api
+from bbsa.cli.formatters import (
+    EXIT_ERROR,
+    EXIT_NOT_FOUND,
+    EXIT_OK,
+    EXIT_USAGE,
+    print_json_error,
+    red,
+    set_color_enabled,
+)
+from bbsa.cli.commands.finance import cmd_finance_invoices, cmd_finance_stats
+from bbsa.cli.commands.me import cmd_me
+from bbsa.cli.commands.misc import cmd_leaderboard, cmd_notifications
+from bbsa.cli.commands.programs import cmd_programs_list, cmd_programs_show
+from bbsa.cli.commands.reports import (
+    cmd_reports_list,
+    cmd_reports_show,
+    cmd_reports_stats,
+)
+
+__all__ = ["main"]
+
+
+def _common_flags() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", action="store_true", help="Emit stable JSON to stdout")
+    common.add_argument("--no-color", action="store_true", help="Disable ANSI color output")
+    common.add_argument("--debug", action="store_true", help="Show full stack traces on error")
+    return common
+
+
+def build_parser() -> argparse.ArgumentParser:
+    common = _common_flags()
+    parser = argparse.ArgumentParser(
+        prog="bbsa",
+        parents=[common],
+        description="bbsa: read-only bugbounty.sa CLI (programs, reports, finance, leaderboard).",
+        epilog="Examples:\n"
+        "  bbsa me\n"
+        "  bbsa programs list\n"
+        "  bbsa programs show 1475\n"
+        "  bbsa reports list --limit 25 --json\n"
+        "  bbsa reports show <ID-or-slug>\n"
+        "  bbsa reports stats --group severity\n"
+        "  bbsa finance invoices\n"
+        "  bbsa finance stats\n"
+        "  bbsa leaderboard --json\n"
+        "  bbsa notifications\n"
+        "\nPipeline-friendly: bbsa leaderboard --json | jq -r '.data[] | \"\\\\(.rank) \\\\(.username)\"'",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    sub = parser.add_subparsers(dest="subcommand", title="Commands")
+
+    # me
+    p_me = sub.add_parser("me", parents=[common], help="Show your researcher profile")
+    p_me.set_defaults(handler=cmd_me)
+
+    # programs
+    p_programs = sub.add_parser(
+        "programs", parents=[common], help="List programs or show one program's scope"
+    )
+    programs_sub = p_programs.add_subparsers(dest="programs_subcommand", title="Programs Commands")
+    p_pl = programs_sub.add_parser("list", parents=[common], help="List programs")
+    p_pl.add_argument("--limit", type=int, default=25, help="Max programs to show (default: 25)")
+    p_pl.set_defaults(handler=cmd_programs_list)
+    p_ps = programs_sub.add_parser("show", parents=[common], help="Show program scope, policy, reward ranges")
+    p_ps.add_argument("id", type=int, help="Program ID")
+    p_ps.set_defaults(handler=cmd_programs_show)
+
+    # reports
+    p_reports = sub.add_parser(
+        "reports", parents=[common], help="List, inspect, or aggregate your reports"
+    )
+    reports_sub = p_reports.add_subparsers(dest="reports_subcommand", title="Reports Commands")
+    p_rl = reports_sub.add_parser("list", parents=[common], help="List your reports")
+    p_rl.add_argument("--limit", type=int, default=25, help="Max reports to show (default: 25)")
+    p_rl.set_defaults(handler=cmd_reports_list)
+    p_rs = reports_sub.add_parser("show", parents=[common], help="Show one report's detail")
+    p_rs.add_argument("id", help="Report ID or slug")
+    p_rs.set_defaults(handler=cmd_reports_show)
+    p_rst = reports_sub.add_parser("stats", parents=[common], help="Report counts grouped by a field")
+    p_rst.add_argument(
+        "--group",
+        choices=("status", "severity", "type"),
+        default="status",
+        help="Grouping field (default: status)",
+    )
+    p_rst.set_defaults(handler=cmd_reports_stats)
+
+    # finance
+    p_finance = sub.add_parser(
+        "finance", parents=[common], help="Invoices and payout statistics"
+    )
+    finance_sub = p_finance.add_subparsers(dest="finance_subcommand", title="Finance Commands")
+    p_fi = finance_sub.add_parser("invoices", parents=[common], help="List your invoices")
+    p_fi.add_argument("--limit", type=int, default=25, help="Max invoices to show (default: 25)")
+    p_fi.set_defaults(handler=cmd_finance_invoices)
+    p_fs = finance_sub.add_parser("stats", parents=[common], help="Invoice summary stats")
+    p_fs.set_defaults(handler=cmd_finance_stats)
+
+    # leaderboard
+    p_lb = sub.add_parser("leaderboard", parents=[common], help="Top 10 researchers (public)")
+    p_lb.set_defaults(handler=cmd_leaderboard)
+
+    # notifications
+    p_nt = sub.add_parser("notifications", parents=[common], help="List your notifications")
+    p_nt.add_argument("--limit", type=int, default=25, help="Max notifications (default: 25)")
+    p_nt.set_defaults(handler=cmd_notifications)
+
+    return parser
+
+
+_SUBCOMMAND_CHILDREN = {"programs": ["list", "show"], "reports": ["list", "show", "stats"], "finance": ["invoices", "stats"]}
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    try:
+        parser = build_parser()
+        if not argv:
+            parser.print_help()
+            return EXIT_OK
+
+        args = parser.parse_args(argv)
+        if args.no_color:
+            set_color_enabled(False)
+
+        if not hasattr(args, "handler"):
+            if args.subcommand in _SUBCOMMAND_CHILDREN:
+                kids = ", ".join(_SUBCOMMAND_CHILDREN[args.subcommand])
+                if args.json:
+                    print_json_error(
+                        "invalid_arguments",
+                        f"Command 'bbsa {args.subcommand}' requires a subcommand ({kids}).",
+                    )
+                else:
+                    sys.stderr.write(
+                        f"Error: 'bbsa {args.subcommand}' requires a subcommand: {kids}\n"
+                        f"Run 'bbsa {args.subcommand} --help' for details.\n"
+                    )
+                return EXIT_USAGE
+            parser.print_help()
+            return EXIT_USAGE
+
+        return args.handler(args)
+    except api.ApiError as exc:
+        if "--json" in argv:
+            print_json_error(exc.code, str(exc), retryable=exc.retryable)
+        else:
+            sys.stderr.write(red(f"Error: {exc}\n"))
+        return EXIT_NOT_FOUND if exc.code == "not_found" else EXIT_ERROR
+    except SystemExit as exc:
+        return exc.code if isinstance(exc.code, int) else (0 if exc.code is None else 1)
+    except Exception as exc:
+        if "--debug" in argv:
+            raise
+        if "--json" in argv:
+            print_json_error("unexpected_error", str(exc), retryable=False)
+        else:
+            sys.stderr.write(red(f"Error: {exc}\n"))
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bugbounty_sa-0.1.0/src/bbsa/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules."""

bugbounty_sa-0.1.0/src/bbsa/cli/commands/finance.py

@@ -0,0 +1,66 @@
+"""bbsa finance — invoices and payout stats."""
+
+from __future__ import annotations
+
+import argparse
+
+from bbsa import api
+from bbsa.cli.formatters import (
+    EXIT_OK,
+    bold,
+    dim,
+    print_json_success,
+    render_kv,
+    render_table,
+    pick,
+    suggest_next_step,
+    text,
+)
+
+
+def cmd_finance_invoices(args: argparse.Namespace) -> int:
+    resp = api.get("/invoices")
+    items = resp.get("data") or []
+    meta = resp.get("meta") or {}
+    total = meta.get("total") if meta.get("total") is not None else len(items)
+    shown = items[: args.limit] if args.limit else items
+
+    if args.json:
+        print_json_success(shown, meta={"total": total, "shown": len(shown)})
+        return EXIT_OK
+    if not shown:
+        print(dim("No invoices found."))
+        return EXIT_OK
+
+    rows = [
+        [
+            str(i.get("id", "-")),
+            text(pick(i, "amount", "total", "price", default="-")),
+            text(pick(i, "status", "state", default="-")),
+            str(pick(i, "created_at", "date", "paid_at", default="-")),
+        ]
+        for i in shown
+    ]
+    print(render_table(["ID", "AMOUNT", "STATUS", "DATE"], rows))
+    if len(shown) < total:
+        suggest_next_step(f"Showing {len(shown)} of {total} invoices — --limit {total} to list all")
+    else:
+        suggest_next_step("bbsa finance stats")
+    return EXIT_OK
+
+
+def cmd_finance_stats(args: argparse.Namespace) -> int:
+    stats = api.get("/invoices/stats")
+    if args.json:
+        print_json_success(stats)
+        return EXIT_OK
+    pairs = []
+    for k, v in stats.items():
+        label = str(k).replace("_", " ").title()
+        if isinstance(v, dict):
+            v = f"{v.get('count', 0)} invoices, total amount {v.get('amount', 0)}"
+        pairs.append((label, str(v)))
+    print(bold("══ Invoice Stats ══\n"))
+    print(render_kv(pairs))
+    suggest_next_step("bbsa finance invoices")
+    return EXIT_OK

bugbounty_sa-0.1.0/src/bbsa/cli/commands/me.py

@@ -0,0 +1,36 @@
+"""bbsa me — current researcher profile."""
+
+from __future__ import annotations
+
+import argparse
+
+from bbsa import api
+from bbsa.cli.formatters import EXIT_OK, bold, print_json_success, render_kv, suggest_next_step
+
+
+def cmd_me(args: argparse.Namespace) -> int:
+    data = api.get("/me")["data"]
+    if args.json:
+        print_json_success(data)
+        return EXIT_OK
+
+    res = data.get("researcher") or {}
+    country = data.get("country")
+    if isinstance(country, dict):
+        country = country.get("name") or country.get("id")
+    pairs = [
+        ("Name", str(data.get("full_name") or data.get("name") or "-")),
+        ("Username", str(data.get("username") or "-")),
+        ("Email", str(data.get("email") or "-")),
+        ("Country", str(country or "-")),
+        ("Verified", str(bool(data.get("is_verified")))),
+        ("Rank", str(res.get("rank") or "-")),
+        ("Points", str(res.get("points") or 0)),
+        ("Total Bounties", str(res.get("total_bounties") or 0)),
+        ("Resolved Reports", str(res.get("resolved_reports") or 0)),
+        ("Full data", "run with --json"),
+    ]
+    print(bold("══ Your Profile ══\n"))
+    print(render_kv(pairs))
+    suggest_next_step("bbsa programs list")
+    return EXIT_OK

bugbounty_sa-0.1.0/src/bbsa/cli/commands/misc.py

@@ -0,0 +1,78 @@
+"""bbsa leaderboard / notifications — misc queries."""
+
+from __future__ import annotations
+
+import argparse
+
+from bbsa import api
+from bbsa.cli.formatters import (
+    EXIT_OK,
+    bold,
+    dim,
+    green,
+    print_json_success,
+    render_table,
+    suggest_next_step,
+    yellow,
+)
+
+
+def cmd_leaderboard(args: argparse.Namespace) -> int:
+    resp = api.get("/leaderboard")
+    items = resp.get("items") or []
+    if args.json:
+        print_json_success(items, meta={"total": len(items)})
+        return EXIT_OK
+    if not items:
+        print(dim("Leaderboard is empty."))
+        return EXIT_OK
+    rows = [
+        [
+            f"#{i.get('rank')}",
+            str(i.get("username", "-")),
+            str(i.get("company_researcher_points") or i.get("points") or 0),
+            green("verified") if i.get("is_verified") else "not verified",
+        ]
+        for i in items
+    ]
+    print(bold("══ Top Researchers ══\n"))
+    print(render_table(["RANK", "USERNAME", "POINTS", "VERIFIED"], rows))
+    suggest_next_step(r"jq filter: bbsa leaderboard --json | jq -r '.data[] | \"\(.rank) \(.username)\"'")
+    return EXIT_OK
+
+
+def cmd_notifications(args: argparse.Namespace) -> int:
+    resp = api.get("/notifications")
+    items = resp.get("data") or []
+    meta = resp.get("meta") or {}
+    total = meta.get("total") if meta.get("total") is not None else len(items)
+    shown = items[: args.limit] if args.limit else items
+
+    if args.json:
+        print_json_success(shown, meta={"total": total, "shown": len(shown)})
+        return EXIT_OK
+    if not shown:
+        print(dim("No notifications."))
+        return EXIT_OK
+
+    rows = []
+    for n in shown:
+        d = n.get("data")
+        d = d if isinstance(d, dict) else {}
+        title = d.get("title") if isinstance(d.get("title"), dict) else {}
+        message = d.get("message")
+        if isinstance(message, dict):
+            message = message.get("message_en") or str(message)
+        text = str(title.get("title_en") or message or "-")
+        rows.append([
+            str(n.get("id", "-")),
+            text,
+            green("read") if n.get("read_at") else yellow("unread"),
+            str(n.get("created_at", "-")),
+        ])
+    print(render_table(["ID", "MESSAGE", "STATUS", "AT"], rows))
+    if len(shown) < total:
+        suggest_next_step(f"Showing {len(shown)} of {total} — --limit {total} for all")
+    else:
+        suggest_next_step("bbsa reports list")
+    return EXIT_OK

bugbounty_sa-0.1.0/src/bbsa/cli/commands/programs.py

@@ -0,0 +1,106 @@
+"""bbsa programs list / show."""
+
+from __future__ import annotations
+
+import argparse
+
+from bbsa import api
+from bbsa.cli.formatters import (
+    EXIT_OK,
+    bold,
+    dim,
+    green,
+    print_json_success,
+    render_kv,
+    render_table,
+    red,
+    suggest_next_step,
+    text,
+)
+
+
+def _platform_name(p: dict) -> str:
+    plat = p.get("platform")
+    if isinstance(plat, dict):
+        return str(plat.get("name") or "-")
+    return str(plat or "-")
+
+
+def cmd_programs_list(args: argparse.Namespace) -> int:
+    resp = api.get("/programs")
+    items = resp.get("data") or []
+    meta = resp.get("meta") or {}
+    total = meta.get("total") if meta.get("total") is not None else len(items)
+    # ponytail: client-side slice; switch to server page/limit if lists grow large
+    shown = items[: args.limit] if args.limit else items
+
+    if args.json:
+        print_json_success(shown, meta={"total": total, "shown": len(shown)})
+        return EXIT_OK
+    if not shown:
+        print(dim("No programs found."))
+        return EXIT_OK
+
+    rows = [
+        [
+            str(p.get("id", "-")),
+            text(p.get("name", "-")),
+            str(p.get("type", "-")),
+            green("active") if p.get("is_active") else red("inactive"),
+            _platform_name(p),
+            str(p.get("end_date") or p.get("end") or "-"),
+        ]
+        for p in shown
+    ]
+    print(render_table(["ID", "NAME", "TYPE", "STATUS", "PLATFORM", "ENDS"], rows))
+    if len(shown) < total:
+        suggest_next_step(f"Showing {len(shown)} of {total} — see all with --limit {total}")
+    else:
+        suggest_next_step("bbsa programs show <ID> for scope, policy, reward ranges")
+    return EXIT_OK
+
+
+def cmd_programs_show(args: argparse.Namespace) -> int:
+    prog = api.get(f"/programs/{args.id}")["data"]
+    if args.json:
+        print_json_success(prog)
+        return EXIT_OK
+
+    pairs = [
+        ("ID", str(prog.get("id"))),
+        ("Name", str(prog.get("name") or "-")),
+        ("Type", str(prog.get("type") or "-")),
+        ("Platform", _platform_name(prog)),
+        ("Status", green("active") if prog.get("is_active") else red("inactive")),
+        ("Start", str(prog.get("start_date") or "-")),
+        ("End", str(prog.get("end_date") or "-")),
+    ]
+    print(bold(f"══ Program {prog.get('id')}: {prog.get('name')} ══\n"))
+    print(render_kv(pairs))
+
+    ranges = [
+        (lvl.title(), f"{prog.get(f'{lvl}_range_from')} - {prog.get(f'{lvl}_range_to')}")
+        for lvl in ("critical", "high", "medium", "low")
+        if prog.get(f"{lvl}_range_from") is not None
+    ]
+    if ranges:
+        print(f"\n{bold('Reward Ranges:')}")
+        print(render_kv(ranges))
+
+    domains = prog.get("domains") or []
+    if domains:
+        print(f"\n{bold('Domains:')}")
+        for d in domains:
+            print(f"  • {d.get('domain', d) if isinstance(d, dict) else d}")
+
+    policy = prog.get("policy")
+    if policy:
+        print(f"\n{bold('Policy:')}\n{policy}")
+
+    out = prog.get("out_of_scope")
+    if out:
+        print(f"\n{bold('Out of Scope:')}\n{out}")
+
+    print()
+    suggest_next_step("bbsa reports list --json | jq '.[] | {id, status}'")
+    return EXIT_OK

bugbounty_sa-0.1.0/src/bbsa/cli/commands/reports.py

@@ -0,0 +1,102 @@
+"""bbsa reports list / show / stats."""
+
+from __future__ import annotations
+
+import argparse
+
+from bbsa import api
+from bbsa.cli.formatters import (
+    EXIT_OK,
+    bold,
+    dim,
+    print_json_success,
+    render_kv,
+    render_table,
+    pick,
+    suggest_next_step,
+    text,
+)
+
+
+def cmd_reports_list(args: argparse.Namespace) -> int:
+    resp = api.get("/reports")
+    items = resp.get("data") or []
+    meta = resp.get("meta") or {}
+    total = meta.get("total") if meta.get("total") is not None else len(items)
+    # ponytail: client-side slice; switch to server page/limit if get large
+    shown = items[: args.limit] if args.limit else items
+
+    if args.json:
+        print_json_success(shown, meta={"total": total, "shown": len(shown)})
+        return EXIT_OK
+    if not shown:
+        print(dim("No reports found."))
+        return EXIT_OK
+
+    rows = [
+        [
+            str(r.get("id", "-")),
+            text(pick(r, "title", "name", default="-")),
+            text(pick(r, "status", default="-")),
+            text(pick(r, "severity", default="-")),
+            str(pick(r, "created_at", "updated_at", default="-")),
+        ]
+        for r in shown
+    ]
+    print(render_table(["ID", "TITLE", "STATUS", "SEVERITY", "UPDATED"], rows))
+    if len(shown) < total:
+        suggest_next_step(f"Showing {len(shown)} of {total} — see all with --limit {total}")
+    else:
+        suggest_next_step("bbsa reports show <ID-or-slug> for detail")
+    return EXIT_OK
+
+
+def cmd_reports_show(args: argparse.Namespace) -> int:
+    r = api.get(f"/reports/{args.id}")["data"]
+    if args.json:
+        print_json_success(r)
+        return EXIT_OK
+
+    pairs = [
+        ("Title", text(pick(r, "title", "name", default="-"))),
+        ("Status", text(pick(r, "status", default="-"))),
+        ("Severity", text(pick(r, "severity", default="-"))),
+        ("Program", text(pick(r, "program", default=""))),
+        ("Created", text(pick(r, "created_at", default="-"))),
+        ("Updated", text(pick(r, "updated_at", default="-"))),
+        ("Summary", text(pick(r, "summary", default=""))),
+    ]
+    pairs = [(k, v) for k, v in pairs if v]
+    print(bold(f"══ Report {args.id} ══\n"))
+    print(render_kv(pairs))
+
+    desc = pick(r, "description", "body", "reproduction_steps", default="")
+    if desc:
+        print(f"\n{bold('Description:')}\n{desc}")
+
+    print("\nFull fields available with --json.")
+    return EXIT_OK
+
+
+def cmd_reports_stats(args: argparse.Namespace) -> int:
+    resp = api.get("/reports/stats/grouped", {"groupBy": args.group})
+    payload = resp.get("data", resp)
+    if args.json:
+        print_json_success(payload, meta={"group_by": args.group})
+        return EXIT_OK
+
+    if isinstance(payload, dict):
+        print(bold(f"══ Report Stats (by {args.group}) ══\n"))
+        print(render_kv([(str(k), str(v)) for k, v in payload.items()]))
+    elif isinstance(payload, list):
+        rows = []
+        for x in payload:
+            if isinstance(x, dict):
+                rows.append([str(pick(x, "group", args.group, default="-")), str(x.get("count", "-"))])
+            else:
+                rows.append([str(x), "?"])
+        print(render_table([args.group.title(), "COUNT"], rows))
+    else:
+        print(str(payload))
+    suggest_next_step(r"jq filter: bbsa reports stats --json | jq '.data'")
+    return EXIT_OK

bugbounty_sa-0.1.0/src/bbsa/cli/formatters.py

@@ -0,0 +1,187 @@
+"""CLI formatters: JSON envelopes, exit codes, ANSI color, tables, hints.
+
+Mirrors the oh-my-ctf CLI conventions: stable JSON with --json, tab-separated
+plain text when piped, ANSI color only on a TTY, data on stdout / errors on
+stderr, bounded human output with next-step hints.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+EXIT_NOT_FOUND = 3
+
+_COLOR_OVERRIDE: bool | None = None
+
+
+def set_color_enabled(enabled: bool | None) -> None:
+    global _COLOR_OVERRIDE
+    _COLOR_OVERRIDE = enabled
+
+
+def is_color_enabled(stream=sys.stdout) -> bool:
+    if _COLOR_OVERRIDE is not None:
+        return _COLOR_OVERRIDE
+    if "NO_COLOR" in os.environ:
+        return False
+    return hasattr(stream, "isatty") and stream.isatty()
+
+
+def _ansi(code: str, text: str, stream=sys.stdout) -> str:
+    if not is_color_enabled(stream):
+        return str(text)
+    return f"\033[{code}m{text}\033[0m"
+
+
+def bold(text, stream=sys.stdout):
+    return _ansi("1", text, stream)
+
+
+def dim(text, stream=sys.stdout):
+    return _ansi("2", text, stream)
+
+
+def red(text, stream=sys.stdout):
+    return _ansi("31", text, stream)
+
+
+def green(text, stream=sys.stdout):
+    return _ansi("32", text, stream)
+
+
+def yellow(text, stream=sys.stdout):
+    return _ansi("33", text, stream)
+
+
+def cyan(text, stream=sys.stdout):
+    return _ansi("36", text, stream)
+
+
+def pick(d: dict, *keys, default: Any = "") -> Any:
+    """First present key in d, or default. Immune to unknown response shapes."""
+    for k in keys:
+        if isinstance(d, dict) and d.get(k) is not None:
+            return d[k]
+    return default
+
+
+def text(v: Any, max_len: int = 80) -> str:
+    """Human-friendly single-line rendering. Nested dicts collapse to their
+    name/label/title; long strings are truncated (bounded output)."""
+    if isinstance(v, dict):
+        for k in ("name", "label", "title", "title_en", "value"):
+            if v.get(k) is not None:
+                return text(v[k], max_len)
+        return str(v)[:max_len]
+    if isinstance(v, bool):
+        return str(v)
+    s = str(v)
+    if len(s) <= max_len:
+        return s
+    return s[: max_len - 1] + "…"
+
+
+# ── JSON envelopes ────────────────────────────────────────────────────
+
+
+def format_json_success(data: Any, meta: dict[str, Any] | None = None) -> str:
+    payload = {
+        "ok": True,
+        "data": data,
+        "meta": meta
+        or {"side_effects": False, "estimated_cost": None, "retryable": False},
+    }
+    return json.dumps(payload, indent=2)
+
+
+def format_json_error(
+    code: str, message: str, retryable: bool = False, details: Any = None
+) -> str:
+    payload = {
+        "ok": False,
+        "error": {"code": code, "message": message, "retryable": retryable, "details": details},
+    }
+    return json.dumps(payload, indent=2)
+
+
+def print_json_success(data: Any, meta: dict[str, Any] | None = None) -> None:
+    print(format_json_success(data, meta))
+
+
+def print_json_error(
+    code: str, message: str, retryable: bool = False, details: Any = None
+) -> None:
+    print(format_json_error(code, message, retryable, details))
+
+
+# ── Tables & text ─────────────────────────────────────────────────────
+
+
+def render_table(
+    headers: Sequence[str],
+    rows: Sequence[Sequence[str]],
+    alignments: Sequence[str] | None = None,
+    stream=sys.stdout,
+) -> str:
+    """Aligned table on a TTY; tab-separated plain rows when piped."""
+    if not rows:
+        return ""
+    is_tty = is_color_enabled(stream) or (hasattr(stream, "isatty") and stream.isatty())
+    align = list(alignments or ["<"] * len(headers))
+    while len(align) < len(headers):
+        align.append("<")
+
+    col_widths = [len(str(h)) for h in headers]
+    for row in rows:
+        for i, val in enumerate(row):
+            if i < len(col_widths):
+                col_widths[i] = max(col_widths[i], len(_strip_ansi(str(val))))
+
+    if not is_tty:
+        lines = ["\t".join(str(h) for h in headers)]
+        for row in rows:
+            lines.append("\t".join(str(cell) for cell in row))
+        return "\n".join(lines)
+
+    def cell(text: str, width: int, alignment: str) -> str:
+        clean = _strip_ansi(str(text))
+        padding = width - len(clean)
+        if padding <= 0:
+            return str(text)
+        return (" " * padding + str(text)) if alignment == ">" else str(text) + " " * padding
+
+    header_line = "  ".join(
+        bold(cell(headers[i], col_widths[i], align[i]), stream) for i in range(len(headers))
+    )
+    separator = "  ".join(dim("─" * col_widths[i], stream) for i in range(len(headers)))
+    lines = [header_line, separator]
+    for row in rows:
+        lines.append(
+            "  ".join(cell(str(row[i]) if i < len(row) else "", col_widths[i], align[i]) for i in range(len(headers)))
+        )
+    return "\n".join(lines)
+
+
+def _strip_ansi(text: str) -> str:
+    return re.sub(r"\x1b\[[0-9;]*m", "", text)
+
+
+def render_kv(pairs: list[tuple[str, str]], stream=sys.stdout) -> str:
+    if not pairs:
+        return ""
+    max_k = max(len(k) for k, _ in pairs)
+    return "\n".join(f"{bold(k.ljust(max_k), stream)} : {v}" for k, v in pairs)
+
+
+def suggest_next_step(hint: str, stream=sys.stdout) -> None:
+    """Print a context-aware next-step hint, TTY only."""
+    if hasattr(stream, "isatty") and stream.isatty():
+        print(f"\n{dim('Next:', stream)} {cyan(hint, stream)}")