BBOT: Recursive Recon for External Attack Surface Mapping

How blacklanternsecurity/bbot's event-graph model works, where it beats Amass and Subfinder pipelines, and a passive scan recipe you can run in 10 minutes.

The Problem BBOT Solves

A single domain unravels fast: subdomains, ASNs, certificate records, leaked credentials, cloud buckets. Stitching a dozen single-purpose tools together to chase each thread is slow, error-prone, and hard to reproduce. blacklanternsecurity/bbot (BBOT) is an open-source reconnaissance framework built around a different premise — propagate new findings back into the scan as it runs, recursively, until the asset graph stabilises.

Nearly 10,000 GitHub stars at the time of writing. The project calls itself “the recursive internet scanner for hackers.” That framing is accurate.

How BBOT Works Under the Hood

The Event Graph Model

Every discovered artifact — hostname, IP, open port, URL — becomes a typed event. Modules both produce and consume events. When any module emits a DNS_NAME event, every module that accepts DNS_NAME as input receives it automatically. Seed a target domain and the graph expands outward: a new subdomain triggers certificate pulls, HTTP probing, and further DNS resolution, each of which may surface more subdomains. The loop runs until no module has new input to process.

This is architecturally distinct from pipeline tools. Subfinder → httpx → Nuclei runs left to right and stops. BBOT runs until the graph is exhausted.

Module Categories

The official documentation groups modules into:

• Subdomain enumeration — certificate transparency (crt.sh), DNS datasets (Chaos, passive sources), active brute-force
• Port scanning — native Nmap integration, built-in fast sweep scanner
• Web — HTTP probing, screenshot capture, spidering, Wappalyzer-based tech fingerprinting
• Cloud — S3 bucket permutation, Azure blob enumeration, GCP asset discovery
• OSINT — HaveIBeenPwned, GitHub secret scanning, LinkedIn employee enumeration, Shodan, Censys, Hunter.io
• Reporting — JSON, CSV, Neo4j, built-in web UI

Passive versus active modules are clearly flagged in the docs. That distinction matters for scoping.

Presets

Rather than enumerating modules by hand, BBOT ships with presets — curated bundles for common workflows. subdomain-enum pulls the full passive DNS suite plus active resolution. web-basic layers in HTTP probing and tech fingerprinting. Presets stack, and you can write your own in YAML, which makes it practical to commit org-specific API keys, scope lists, and module selections into a reproducible scan profile.

Where BBOT Fits

Recon has three phases: seeding (what you own), discovery (full attack surface), analysis (making sense of it). Most tools own one phase. BBOT spans all three but is strongest in discovery.

The Neo4j output is where BBOT earns its keep at the analysis stage. Once a scan is in a graph database, Cypher queries become straightforward: which subdomains share a TLS certificate with the primary domain? or which IPs resolve to more than five distinct hostnames? Those questions are painful to answer from flat files.

BBOT vs. Alternatives

BBOT vs. Amass

Amass has deeper DNS-focused logic and fits cleanly into automated pipelines. If a pure subdomain census is the goal and you already have an Amass workflow, there is no pressing reason to migrate. BBOT’s advantage is breadth: moving from what subdomains exist to what is running on each, and where else does this org have cloud exposure in a single pass. For that use case, BBOT is more efficient.

BBOT vs. Subfinder + httpx + Nuclei

This pipeline is fast, modular, and well-suited to bug bounty workflows. BBOT does not replace Nuclei’s template library — those are purpose-built for CVE checks and application fingerprinting, and nothing in BBOT touches that coverage. The two approaches complement each other: BBOT for recursive surface discovery, Nuclei against the resulting URL list for targeted vulnerability scanning.

BBOT vs. Commercial ASM Platforms

Censys ASM, CyCognito, and similar products offer continuous monitoring, business-context tagging, and managed integrations. They also carry significant per-seat costs. For ad-hoc engagements, red team exercises, or budget-constrained programs, BBOT covers a substantial portion of the same discovery capability. The trade-off is operational setup time versus licensing spend — a reasonable trade for most teams running recurring external recon.

Passive Scan Recipe

The following uses only passive modules. Active enumeration against infrastructure you do not own without written authorisation is illegal in most jurisdictions.

Prerequisites

• Python 3.9+
• pipx for isolated installation (or a venv)
• Optional: API keys for Shodan, Censys, SecurityTrails in ~/.config/bbot/secrets.yml

Install

pipx install bbot
bbot --version

Passive Subdomain Enumeration

bbot -t example.com -p subdomain-enum -rf passive -o ~/bbot-output/example --silent

• -t example.com — target seed
• -p subdomain-enum — subdomain enumeration preset
• -rf passive — passive modules only, no direct contact with target systems
• -o ~/bbot-output/example — output directory
• --silent — suppress the progress banner

On a mid-sized org domain this finishes in three to seven minutes, depending on API rate limits.

Review Output

ls ~/bbot-output/example/
# output.ndjson   output.txt   subdomains.txt   scan.log

subdomains.txt has the deduplicated hostname list. output.ndjson has every event in newline-delimited JSON:

cat ~/bbot-output/example/output.ndjson | jq 'select(.type=="DNS_NAME") | .data'

Layer in HTTP Probing (Authorised Targets Only)

bbot -t example.com -p subdomain-enum web-basic -o ~/bbot-output/example-web

Adds HTTP probing, tech fingerprinting, and basic spidering. The recursive engine picks up URLs, feeds them back through DNS resolution, and surfaces additional subdomains referenced in page content or HTTP headers.

Neo4j Export (Optional)

bbot -t example.com -p subdomain-enum -om neo4j

The official documentation covers the Neo4j module configuration, connection string format, and Cypher query patterns in detail.

Operational Notes

Scope creep is real. BBOT follows discovered assets outward. A scan seeded on a parent domain will surface third-party infrastructure, cloud providers, and SaaS assets that are technically associated with the target but outside engagement scope. Define a whitelist:

# ~/.config/bbot/bbot.yml
scope_search_distance: 1
scope_dns_search_distance: 2
whitelist:
  - example.com
  - 203.0.113.0/24

Skipping this on a large org domain is how you end up with 40,000 events spanning half the internet.

API key management. Shodan, Censys, SecurityTrails, GitHub — the best passive sources all require keys. Store them in ~/.config/bbot/secrets.yml and treat the file accordingly. The docs list which modules need keys and where to get them.

Noise profile. Passive-only scans generate no traffic to target infrastructure. Active modules will log on target systems — expected in authorised engagements, but the configuration exposes per-module rate limit settings if you need to tune aggressiveness down.

Verdict

BBOT fills a real gap. It is not the right call for every job — a quick subdomain list for a small scope does not need a full BBOT run, and Nuclei is unmatched for template-based vulnerability coverage — but for external attack surface mapping that needs to go beyond DNS, BBOT’s recursive event graph and broad module library are hard to beat in the open-source space.

The configuration system is well-documented and the preset model keeps the on-ramp shallow. Spend an afternoon with the YAML config and the Neo4j output module. The first time you run a Cypher query across a scan and surface certificate-sharing relationships that a flat subdomain list would have missed entirely, the investment makes sense.

Disclosure: No affiliate links. All tool references are to free, open-source software.