bbscope: Aggregating Bug Bounty Scopes Across Five Platforms with Go

Hook

Bug bounty hunters manually check five different platforms daily for scope changes. By the time they notice a new in-scope subdomain added to a program, someone else has already found the critical vulnerability on it.

Context

The bug bounty ecosystem is fragmented. A security researcher serious about making money needs accounts on HackerOne, Bugcrowd, Intigriti, YesWeHack, and Immunefi—each with their own interface, scope format, and notification system. Program managers update scopes constantly: adding subdomains, removing deprecated services, or expanding to new mobile apps. Miss an update and you're either testing out-of-scope assets (risking account suspension) or missing fresh attack surface while competitors find bugs.

Manually checking five platforms daily doesn't scale. Each platform's scope format is different—HackerOne uses structured JSON, Bugcrowd has free-text descriptions, and smaller platforms mix formats unpredictably. Worse, there's no standard notification system for scope changes. Some platforms email you, others don't. bbscope emerged to solve this operational problem: aggregate all program scopes into one queryable database, track changes over time, and normalize the chaos into machine-readable formats that feed recon pipelines.

Technical Insight

bbscope's architecture centers on platform-specific polling clients that respect rate limits while maximizing concurrency. The v2 rewrite introduced a command-based structure with bbscope poll fetching fresh data and bbscope db querying stored results. Each platform requires different authentication—HackerOne uses API tokens, Bugcrowd needs session cookies, and some platforms require TOTP secrets for automatic 2FA solving.

The configuration lives in a YAML file specifying credentials and target programs:

hackerone:
  username: "your_username"
  api_token: "your_token"
  programs:
    - "security-program-1"
    - "security-program-2"

bugcrowd:
  email: "your_email"
  password: "your_password"
  programs:
    - "target-company"

intigriti:
  ott_secret: "your_totp_secret"
  programs:
    - "company-name"

The polling system uses Go's concurrency primitives to fetch multiple programs simultaneously without overwhelming platform APIs. Each platform client implements a common interface, making it straightforward to add new sources. The real architectural win is the PostgreSQL backend for change tracking. When you run bbscope poll, it doesn't just fetch current scopes—it diffs against historical data and flags additions/removals:

# Initial poll stores baseline
bbscope poll -p "program-name"

# Later polls detect changes
bbscope poll -p "program-name"
# Output: "Added: api-v2.example.com"
# Output: "Removed: legacy.example.com"

The database schema tracks scope entries by program, platform, and timestamp. Querying supports filtering by category—URLs, wildcards (*.example.com), CIDR blocks, mobile app identifiers, or Android/iOS package names. Output formats include JSON for tool integration, CSV for spreadsheets, or plain text for quick terminal review:

# Get all URLs for a specific program
bbscope db query -p "target-company" -c url -o json

# Export wildcards across all programs to feed subdomain enumeration
bbscope db query -c wildcard -o text > wildcards.txt

The most experimental feature is LLM-powered scope normalization. Bug bounty platforms often contain messy, human-written scope descriptions: "All subdomains of example.com (except test.example.com and dev.example.com)" or "Mobile apps: iOS and Android versions". bbscope v2 can send these through OpenAI-compatible APIs to extract structured data:

# Clean messy scope strings in bulk
bbscope ai clean -p "program-name" --llm-url "http://localhost:11434" --model "llama2"

The AI integration uses a prompt engineered to return JSON arrays of scope items, handling edge cases like exclusions and wildcards. However, it's marked experimental because LLMs occasionally hallucinate entries or miss critical exclusions. The tool maintains both original and cleaned versions, letting users choose reliability over convenience.

For users who don't want to run their own database, bbscope.com publishes hourly-updated scope dumps from public programs. This creates a useful dichotomy: run bbscope locally for private programs and change tracking, or scrape the public site for quick recon against well-known targets. The Go codebase is clean and modular enough that extending it for additional platforms takes a few hundred lines—mostly API client logic and response parsing.

Gotcha

The credential management model is bbscope's biggest weakness. Storing plaintext passwords, API tokens, and TOTP secrets in a YAML file is operationally risky. There's no keyring integration, no environment variable support for secrets, and no credential rotation handling. If your config file leaks, your bounty platform accounts are compromised—particularly problematic since these accounts often have payment information attached.

The AI normalization feature fails silently more often than you'd expect. Testing showed that complex scope descriptions with multiple exclusions or nested wildcards confuse even GPT-4, resulting in incomplete extractions. The tool doesn't validate AI output against the original scope, so you might unknowingly drop in-scope assets. For production use, treat AI-cleaned scopes as suggestions requiring manual review, not authoritative data. Additionally, the PostgreSQL requirement adds friction—you need a running database instance, migration management, and backup strategy just to track scope changes. Casual users who want simple scope listing without historical tracking will find this overkill. The Docker Compose setup helps, but it's still infrastructure to maintain.

Verdict

Use if: You're a professional bug bounty hunter actively monitoring 10+ programs across multiple platforms, need automated alerts for scope changes, or want to integrate scope data into custom recon pipelines (feeding subdomains to Amass, CIDRs to Nmap, etc.). The database-backed change detection pays for its complexity if you're serious about staying ahead of scope updates. Also compelling if you're building automation around bounty hunting and need a unified API for scope data instead of maintaining five separate platform integrations. Skip if: You participate in fewer than five programs casually, are uncomfortable storing credentials in config files, or just need a one-time scope export (use the free bbscope.com dumps instead). The operational overhead of running PostgreSQL and managing credentials isn't justified for occasional hunters. If your threat model includes protecting bounty platform credentials carefully, the current authentication model is too risky without adding your own secrets management layer.