BBRF: Building a Distributed Reconnaissance Database for Bug Bounty Teams

Hook

Bug bounty hunters generate gigabytes of reconnaissance data across dozens of VPSs and local machines—then spend hours manually reconciling duplicates, checking scope, and sharing results. BBRF treats this coordination problem as a database design challenge.

Context

Bug bounty reconnaissance is inherently distributed. You're running subfinder on your laptop while nuclei scans execute on three different cloud VPSs. A teammate discovers new subdomains while you're enumerating URLs. Each tool dumps output to text files, and before long, you're drowning in duplicate domains, forgetting which IPs you've already scanned, and accidentally testing out-of-scope assets.

Traditional approaches involve bash scripts that append to text files, git repositories for sharing results, or elaborate spreadsheets. These solutions break down at scale. They don't handle concurrent writes from multiple machines. They can't automatically validate scope or prevent duplicates. They require manual reconciliation. The Bug Bounty Reconnaissance Framework (BBRF) reimagines reconnaissance data as a distributed database problem, using CouchDB's replication capabilities to synchronize asset discovery across your entire infrastructure in real-time.

Technical Insight

BBRF's architecture centers on CouchDB as the single source of truth, with the Python client acting as both a CLI and a library for programmatic access. This separation is crucial: the server handles data persistence, validation, and conflicts, while lightweight clients can run anywhere with network access to the database.

The system organizes data into distinct document types—programs, domains, IPs, URLs, services, and agents. Each document type has specific validation rules enforced at the database level through CouchDB design documents. When you add a domain, BBRF doesn't just append it to a list; it creates or updates a structured document with metadata fields for tags, discovery source, timestamps, and resolution status.

Here's how you'd integrate BBRF into a subdomain enumeration pipeline:

# Initialize a new program with scope
bbrf new example_program
bbrf inscope add '*.example.com' -p example_program
bbrf outscope add 'admin.example.com' -p example_program
bbrf use example_program

# Pipe subdomain enumeration directly into BBRF
subfinder -d example.com -silent | bbrf domain add - 

# Only retrieve in-scope, unresolved domains for further scanning
bbrf domains --view unresolved | dnsx -silent -a -resp | bbrf domain update --resolved

# Add discovered IPs with source attribution
bbrf ips | httpx -silent -json | jq -r '.ip' | bbrf ip add -

The scope management system is particularly elegant. When you add domains, BBRF checks them against both inscope and outscope patterns stored in the program document. The --show-new flag reveals only assets that weren't previously in the database, while the --view unresolved filter returns domains that haven't been DNS-resolved yet. This prevents wasted scanning effort on domains you've already processed.

BBRF's approach to relationships between entities demonstrates thoughtful design restraint. Unlike automated systems that immediately resolve every domain and link IPs to domains, BBRF requires explicit intent. When you add a domain, it doesn't automatically resolve it and create IP documents—you must pipe it through DNS resolution and explicitly add those IPs. This might seem like extra work, but it prevents cascading data issues and maintains a clear audit trail of how each asset was discovered.

The tagging system provides a flexible metadata layer without rigid schemas:

# Tag domains by discovery method or purpose
bbrf domains --view unresolved | bbrf domain add - --tag subdomain-enum --tag needs-scanning

# Later, query only domains with specific tags
bbrf domains --where-tag subdomain-enum

# Remove tags as work progresses
bbrf domains --where-tag needs-scanning | httpx -silent | bbrf domain add - --remove-tag needs-scanning --tag scanned

The listener component (bbrf listen) runs as a background process that watches for database changes and sends real-time notifications to Slack or Discord. When a teammate discovers critical subdomains or a scheduled job identifies new attack surface, you're notified immediately rather than discovering it hours later during manual syncing.

BBRF's Unix philosophy integration is its killer feature for practitioners. Every command accepts stdin and outputs to stdout, making it composable with existing toolchains. The bbrf domains command becomes a database-backed filter that remembers state across sessions and machines. You're not rewriting your reconnaissance playbooks—you're augmenting them with persistent, coordinated storage.

Gotcha

BBRF's most significant limitation is the server dependency. You can't use the client at all until you've deployed the BBRF server, which requires a CouchDB instance and configuration. The official documentation points to a separate repository for server setup, and you'll need to understand CouchDB basics, manage authentication, and ensure network accessibility from all your reconnaissance machines. For solo hunters testing the waters, this infrastructure requirement feels heavy.

Scope changes present a data hygiene challenge. If you add 10,000 domains, then later realize you need to tighten the inscope pattern, those previously added out-of-scope domains remain in the database. BBRF won't automatically remove them. You'll need to query for out-of-scope assets and manually delete them, or accept that your database contains historical data that no longer matches current scope. This is a reasonable trade-off for data safety, but it means scope management requires ongoing maintenance rather than being set-and-forget.

The learning curve assumes reconnaissance expertise. Documentation examples jump straight into tool integration without explaining why you'd want separate views for resolved versus unresolved domains, or when tags are more appropriate than separate programs. Beginners will struggle to understand the workflow patterns that make BBRF valuable.

Verdict

Use BBRF if: you're running reconnaissance across multiple VPSs or cloud instances, collaborating with a team that needs real-time data sharing, managing more than three active bug bounty programs simultaneously, or spending significant time manually deduplicating reconnaissance results. The coordination benefits and scope management alone justify the server setup overhead when you have complex, ongoing workflows. Skip if: you're working solo on occasional targets, prefer file-based tracking with grep and sort, don't have infrastructure for running a persistent CouchDB instance, or are new to bug bounty hunting and still learning basic reconnaissance workflows. Start with simpler text file approaches and graduate to BBRF when coordination pain becomes your bottleneck.