bbot for recursive reconnaissance and attack surface mapping

bbot is a Python-based recursive internet scanner that chains OSINT, DNS brute-force, and web modules into a single event-driven pipeline, built for authorized recon, bug bounty, and attack surface management work.

Tool	blacklanternsecurity/bbot — recursive, modular internet scanner for recon, bug bounty, and ASM
Category	Reconnaissance / OSINT automation framework
Primary Use	Enumerating subdomains, emails, and web attack surface via composable presets like subdomain-enum, spider, and kitchen-sink
Safe Use	Run only against assets you own or have written authorization to assess, such as bug bounty programs in scope, internal labs, and client engagements with a signed rules-of-engagement
Telemetry Note	Generates heavy DNS query volume via blastdns and leaves fingerprints in third-party API logs (SecurityTrails, Shodan, etc.); passive-only scans with -rf passive are available for low-noise workflows and defenders can detect aggressive DNS brute-forcing patterns

bbot, maintained by blacklanternsecurity, describes itself as a multipurpose recursive scanner inspired by Spiderfoot, aimed squarely at automating reconnaissance, bug bounty workflows, and attack surface management. With over ten thousand stars and an active AGPL-3.0-licensed codebase written in Python 3.10+, it has become one of the most prominent frameworks in the OSINT and external asset discovery space. What distinguishes it from a simple subdomain tool is its recursive, event-driven architecture: every discovered artifact — a DNS name, an open port, an email address, a URL — becomes an event that can feed other modules, causing the scan to grow organically outward from the seed target. The README positions it explicitly against tools like Amass and Subfinder, both in its API-key ecosystem and in its claimed 20-50% improvement in subdomain yield.

Installation follows the modern Python packaging convention cleanly: pipx install bbot gets you the stable release, while pipx install --pip-args '--pre' bbot tracks the bleeding-edge dev branch. A Docker image is also published under blacklanternsecurity/bbot for those who prefer containerized execution. The project enforces quality signals that matter to operators — Ruff linting, continuous tests, and Codecov coverage tracking — which reduces the risk of running a half-maintained scanner against a production engagement. Note that BBOT 3.0 introduced breaking changes to the CLI, presets, modules, events, and the Python API, so teams upgrading from 2.x should consult the migration guide before swapping binaries mid-engagement.

The core abstraction to understand is the preset system. A preset is a YAML file that bundles modules, flags, output modules, and configuration into a reusable scan profile. The canonical example is subdomain-enum.yml, which enables every module carrying the subdomain-enum flag, combines passive API sources with recursive DNS brute-force, and writes unique subdomains to a TXT file via the subdomains output module. The README makes the internals visible by inlining the preset: dns.threads: 25 and dns.brute_threads: 1000 show how aggressively the brute-forcer parallelizes, and commented blocks reveal where github, chaos, and securitytrails API keys slot in.

Invocation is deliberately terse: bbot -t example.com -p subdomain-enum runs the full enumeration, while appending -rf passive restricts the scan to passive sources only. That passive/active distinction is operationally significant. On a stealth-sensitive authorized assessment, the passive variant avoids touching the client's DNS infrastructure directly and relies purely on third-party data aggregators. The README also documents a DNS resolver tip that reflects the tool's internals: bbot uses its own resolver, blastdns, which spins up multiple threads per resolver listed in /etc/resolv.conf, and adding more unfiltered resolvers scales scan speed accordingly.

Beyond subdomains, bbot ships presets for other reconnaissance lanes. The spider preset runs a recursive web crawler with thoughtful defaults, including a blacklist regex — RE:/.*(sign|log)[_-]?out — specifically to prevent the spider from invalidating your own authenticated sessions by accidentally clicking logout links. Crawl behavior is tunable through spider_distance: 2, spider_depth: 4, and spider_links_per_page: 25, which collectively bound how far the crawler wanders. The email-enum preset gathers addresses from free APIs and web scraping, and the README notes it composes well: bbot -t example.com -p email-enum subdomain-enum spider stacks all three profiles for maximum yield, since emails discovered by crawling feed back into other modules.

For web-focused work, web and web-heavy presets provide graduated intensity, the latter described honestly as an aggressive scan. The flagship composite is kitchen-sink, which chains subdomain-enum, cloud-enum, code-enum, email-enum, spider, web, paramminer, webbrute, web-screenshots, and baddns-heavy into a single everything-everywhere run. Its inline YAML reveals interesting tuning choices: dnsbrute and dnscommonsrv get recursive_mutations: true, and webbrute has an avoid_wafs toggle, showing the framework acknowledges WAF evasion as a configurable — and thus controllable — behavior rather than a hidden default. Operators should treat kitchen-sink as a scoped-lab or explicitly-authorized-ASM workload, not a first move.

Target handling is unusually flexible. bbot accepts unlimited targets via -t, mixing DNS names, IP addresses, CIDR ranges like 1.2.3.0/24, open TCP ports, URLs, email addresses, and typed entities such as ORG:, USER:, FILESYSTEM:, and MOBILE_APP:. This typing system is what makes the recursion powerful: an organization target may fan out into domains and usernames, each of which triggers different modules. The feature list adds NLP-powered subdomain mutations — likely the mechanism behind the claimed yield advantage, since word-aware mutation generates more plausible candidate names than static wordlists — plus web screenshots, YARA rules to search the entire attack surface, and automatic dependency installation via Ansible.

Output is where bbot earns its ASM credibility. Events can stream to Neo4j for graph visualization — the README shows a real-time render using bbot-vivagraphjs — alongside relational sinks like Postgres, MySQL, SQLite, flat formats like CSV and JSON, and pipeline integrations including Splunk, Elasticsearch, Teams, Discord, Slack, HTTP, and Websocket. The graph model matters analytically: reconnaissance data is inherently relational, and storing discoveries as a graph lets an analyst query paths between assets, trace which subdomain led to which email, and maintain longitudinal ASM state across scans rather than staring at flat text lists.

The Python API is a first-class citizen rather than an afterthought. The README shows both synchronous iteration over scan.start() events and an asyncio variant using async for event in scan.async_start(), with events exposing .json() for structured consumption. This makes bbot embeddable in larger automation — a CI job that scans newly provisioned external assets, or a custom orchestrator that reacts to discoveries in real time. There is even a documented Discord bot example responding to a /scan command, which is a fun demonstration of the API but one worth pausing on: scanning from a chat interface makes accidental out-of-scope targeting easy, so any deployment like that needs strict preset and scope controls.

API key management follows the expected pattern: keys live in ~/.config/bbot/secrets.yml under per-module YAML blocks, and the c99 example shows multiple keys can be stacked per module for rotation or rate-limit relief. Keys can also be passed inline with -c modules.virustotal.api_key=..., though that leaks secrets into shell history and process lists — the config file is the better operational default. From a defensive perspective, this API-key surface is also worth noting: bbot's activity is partially observable through the logs of the third-party services it queries, and its active modes produce distinctive DNS brute-force traffic patterns that enterprise DNS monitoring can flag.

Where bbot fits in an authorized workflow is clear: it is a front-of-engagement recon engine and a continuous ASM sensor. For a bug bounty hunter working inside defined scope, the typed target system plus preset composition replaces a half-dozen point tools. For an internal security team, scheduled passive scans piped into Neo4j or Elasticsearch produce a living map of externally exposed assets — exactly the kind of telemetry that catches shadow infrastructure before an attacker does. The AGPL license is compatible with internal use but relevant if you plan to embed it in a commercial SaaS offering.

The honest caveats are few but real. The 20-50% subdomain claim is the project's own benchmarking, so treat it as directional rather than gospel on your specific TLD mix. Aggressive presets like web-heavy and kitchen-sink generate substantial traffic, and the avoid_wafs option should stay off unless your rules of engagement explicitly cover it. But as a maintained, tested, well-documented framework that turns reconnaissance from a pile of scripts into a queryable pipeline, bbot is one of the strongest entries in the modern recon toolchain.

Official project repository for blacklanternsecurity/bbot.

Download Tool

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.