BBRF: The CouchDB-Powered Framework That Keeps Your Bug Bounty Recon Sane Across Devices
Hook
Most bug bounty hunters lose hours testing out-of-scope assets because their recon data lives in scattered terminal outputs across three different laptops. BBRF solves this with a single source of truth that knows what’s in scope before you waste time on it.
Context
Bug bounty reconnaissance generates massive amounts of data: subdomains, IP addresses, URLs, open ports, and service banners. When you’re running tools like subfinder, httpx, and nmap across multiple VPS instances, your laptop, and maybe a cloud function, keeping this data synchronized becomes a nightmare. You discover a subdomain on one machine, forget to check if it’s in scope, spend hours testing it, only to realize it’s explicitly listed as out-of-scope in the program brief you read three weeks ago on a different device.
Traditional approaches involve grep-ing through text files, manually checking spreadsheets, or building custom databases that don’t travel well. Recon-ng offers local SQLite databases but doesn’t sync. Shared Google Sheets lack validation logic. The Bug Bounty Reconnaissance Framework (BBRF) takes a different approach: it uses CouchDB as a centralized, replicated database that all your devices talk to, with a Python client that enforces scope rules, prevents duplicates, and notifies your team via Slack when something interesting appears. It’s infrastructure-heavy but purpose-built for the chaos of distributed reconnaissance.
Technical Insight
BBRF’s architecture centers on CouchDB’s master-master replication capabilities. When you add a domain via the CLI, the client makes an HTTP PUT request to your CouchDB server, storing the asset with metadata linking it to a program document. Each program contains scope definitions—regex patterns or explicit lists defining what’s fair game and what’s forbidden territory.
The scope validation happens client-side before data hits the database. When you pipe subfinder output into BBRF, it checks each domain against the program’s inscope and outscope arrays. Here’s how you’d set up a program and add domains with automatic filtering:
# Create a new program with scope definitions
bbrf new example-program
bbrf inscope add '*.example.com' -p example-program
bbrf outscope add 'admin.example.com' -p example-program
# Pipe recon tool output directly - only in-scope assets get stored
subfinder -d example.com -silent | bbrf domain add -
# Add domains with resolved IPs in one command
echo "api.example.com:192.0.2.1,192.0.2.2" | bbrf domain add -
# Query your data with filters
bbrf domains where program is example-program
bbrf ips where domain is api.example.comThe deduplication logic uses CouchDB’s document versioning. Each asset type (domain, IP, URL, service) becomes a document with a deterministic ID. If you try to add api.example.com from three different machines, CouchDB’s conflict resolution ensures only one document exists, with metadata tracking which tools discovered it and when. This prevents the “did I already scan this?” problem that plagues text-file-based workflows.
BBRF’s background listener process monitors the CouchDB _changes feed—a continuous stream of database modifications. When someone on your team adds a new domain with an interesting pattern (maybe a staging subdomain), the listener can fire webhooks to Slack or Discord. The implementation is straightforward Python using the requests library to poll the changes feed and match against user-defined alert rules stored as program documents.
What makes BBRF particularly clever is its relationship tracking without automatic linking. When you add a domain with IP addresses using the domain:ip1,ip2 syntax, BBRF stores both the domain document and IP documents, but doesn’t automatically create reverse DNS entries. This design choice prevents false associations—just because example.com resolves to 192.0.2.1 today doesn’t mean every other domain pointing to that IP is related. You maintain data integrity while still being able to query relationships explicitly.
The Python client is also importable as a module, letting you build custom reconnaissance pipelines:
from bbrf import BBRFClient
bbrf = BBRFClient()
program = 'example-program'
# Get all domains and check HTTP status
domains = bbrf.domains(program=program)
for domain in domains:
# Your custom logic here
status = check_http_status(domain)
bbrf.update_domain(domain, {'http_status': status})
# Add URLs with metadata atomically
bbrf.add_urls([
{'url': 'https://example.com/admin', 'status': 403, 'length': 1234},
{'url': 'https://example.com/api', 'status': 200, 'length': 5678}
])The optional web dashboard (bbrf.me) runs entirely client-side as a static JavaScript application. Your CouchDB credentials stay in your browser’s localStorage, and queries hit your server directly via CORS. This serverless approach means the dashboard maintainer never sees your reconnaissance data—a critical security consideration for bug bounty work.
Gotcha
The biggest friction point is the infrastructure requirement. You need a CouchDB server running somewhere before BBRF becomes useful, which means either managing a VPS, paying for a hosted CouchDB service, or running Docker containers. The official BBRF server repository provides setup scripts, but you’re still responsible for securing it, managing SSL certificates, and ensuring uptime. For solo hunters just starting out, this overhead might exceed the benefit—especially compared to grep and text files.
Data lifecycle management requires manual intervention. If a program updates its scope to remove a subdomain category, BBRF won’t automatically delete those domains from your database. You’ll need to run filter queries and manually purge outdated data. The framework also doesn’t handle program expiration or archiving—every program you’ve ever worked stays in the database unless you explicitly remove it. Over months of active bug hunting, this can lead to database bloat and slower queries. The documentation acknowledges this but offers limited guidance on maintenance patterns beyond basic CLI commands.
Verdict
Use BBRF if: You’re running reconnaissance across multiple machines (VPS instances, local laptop, cloud runners) and need a single source of truth with automatic scope enforcement. Teams collaborating on bug bounty programs will especially benefit from real-time notifications and shared state. The investment in CouchDB setup pays off when data quality and coordination matter more than setup speed. Skip if: You’re a solo hunter working locally with simple grep workflows, or you can’t commit to maintaining a CouchDB server. If your reconnaissance is primarily ad-hoc testing rather than continuous monitoring, the infrastructure overhead isn’t justified. Also skip if you’re already using platforms like Reconness or Pentest-Tools.com that provide collaboration features without requiring your own database infrastructure.
