bbscope: How Bug Bounty Hunters Track 50,000+ Targets Across Five Platforms
Hook
Bug bounty hunters manually tracking program scopes across multiple platforms spend significant time checking if companies added new domains. bbscope solves this with a unified CLI that polls all major platforms, detects changes automatically, and can use LLM models to clean up messy scope entries.
Context
Bug bounty programs constantly evolve their attack surfaces. A company might add new subdomains, expand wildcard scopes, or launch entirely new programs across different platforms. For hunters running continuous reconnaissance pipelines, missing these updates means missing opportunities—or worse, accidentally testing out-of-scope assets and facing consequences.
Traditional approaches force hunters to maintain separate scripts for each platform’s API, deal with inconsistent authentication mechanisms, and manually diff scope changes. bbscope v2 centralizes this into a single Go binary that aggregates scopes from HackerOne, Bugcrowd, Intigriti, YesWeHack, and Immunefi. The tool offers two operational modes: direct CLI output for quick queries, or PostgreSQL-backed persistence for change tracking and historical analysis. Version 2 introduced a restructured command hierarchy—moving from bbscope h1 to bbscope poll h1—alongside optional LLM-powered scope normalization that cleans malformed entries at scale.
Technical Insight
bbscope’s architecture separates data acquisition from data management through two primary command families: poll for fetching platform data and db for querying the PostgreSQL backend. This separation allows hunters to use the tool in stateless mode (direct output) or stateful mode (database persistence with change detection).
The polling mechanism handles five platforms with distinct authentication schemes. HackerOne uses standard API tokens, while Bugcrowd and YesWeHack require either session cookies or email/password/OTP combinations. The configuration file at ~/.bbscope.yaml centralizes credentials:
db_url: "postgres://bbscope:password@localhost:5432/bbscope?sslmode=disable"
hackerone:
username: "hunter"
token: "api_token_here"
bugcrowd:
email: "hunter@example.com"
password: "secure_password"
otpsecret: "TOTP_SECRET_KEY"
intigriti:
token: "bearer_token"
yeswehack:
email: "hunter@example.com"
password: "secure_password"
otpsecret: "TOTP_SECRET_KEY"
ai:
provider: "openai"
api_key: "sk-..."
model: "gpt-4o-mini"
max_batch: 25
max_concurrency: 10Command-line flags override config file values, enabling CI/CD integration where secrets come from environment variables. The tool also ships as a Docker image on GHCR, though this introduces networking complexity—containers must reach your PostgreSQL instance using host.docker.internal on macOS/Windows or explicit network addresses on Linux.
The LLM-powered scope normalization feature is opt-in and experimental. Bug bounty programs often contain typos, inconsistent formatting, or ambiguous entries. When polling with AI enabled (--ai flag), bbscope batches messy scope strings and sends them to configured LLM providers for cleanup. The max_batch: 25 parameter controls how many targets get normalized per API call, balancing cost against request overhead. Importantly, the tool preserves original entries if normalization fails—avoiding data loss from problematic LLM outputs. The AI can also detect out-of-scope indicators in text and adjust the in_scope flag accordingly.
Change tracking leverages PostgreSQL’s relational model to snapshot scopes over time. Each poll creates a new snapshot, allowing db get queries to show what targets appeared or disappeared between runs. For hunters with automated recon workflows, this means new domains automatically flow into subdomain enumeration pipelines without manual intervention.
The codebase’s Go implementation provides concurrency benefits when polling multiple platforms simultaneously. The poll command supports fetching from all platforms in one invocation, with the --concurrency flag (default 5) controlling parallel API requests per platform. Output formats (JSON, CSV, plain text) make integration with tools like jq, nuclei, or custom scripts straightforward.
Beyond scope aggregation, bbscope includes a HackerOne report downloader that fetches disclosed reports as Markdown files. This uses parallel fetching with filtering by program name, report state (e.g., resolved, triaged), or severity level—useful for competitive intelligence or learning from disclosed vulnerabilities.
Gotcha
The authentication requirements create operational challenges. Session cookies for Bugcrowd and YesWeHack expire unpredictably, forcing hunters to manually extract fresh tokens from browser developer tools. While the OTP secret approach enables programmatic login, storing these secrets in plaintext YAML files poses security risks if the configuration file is exposed. The tool doesn’t document credential rotation or vault integration, so operational security depends on filesystem permissions.
The v1 to v2 migration introduced breaking changes with a new command structure. Existing scripts using bbscope h1 must update to bbscope poll h1, and the configuration file schema changed requiring users to regenerate ~/.bbscope.yaml. This is documented as a major version change with important warnings in the README.
The AI normalization feature incurs costs from LLM API usage that scale with scope size. The batching configuration (max_batch and max_concurrency) provides some control over throughput, but there’s no documented budget cap mechanism to prevent unexpected API expenses. The README clearly labels this as an opt-in experimental feature, signaling users should carefully evaluate costs before enabling it for large-scale operations.
Verdict
Use bbscope if you’re a bug bounty hunter actively working programs across multiple platforms and need automated change detection for continuous recon pipelines. The PostgreSQL backend makes it valuable for teams sharing scope data or anyone running scheduled polling jobs. The unified CLI eliminates maintaining separate API clients for each platform, and the Docker image (available on GHCR) simplifies deployment to cloud environments. The HackerOne report downloader adds additional value if you study disclosed reports regularly.
Skip it if you exclusively hunt on a single platform (use their native API directly), can’t justify PostgreSQL setup overhead for personal workflows, or operate in environments where dependencies like Docker or external databases aren’t practical. The session cookie authentication for some platforms requires periodic manual intervention for fully automated deployments. For casual hunters who manually check programs, visiting bbscope.com (which the README mentions provides hourly-updated public scope data) may provide sufficient value without running the tool locally. The optional AI normalization should be evaluated carefully based on your scope volume and tolerance for LLM API costs.
