bbot Tutorial: Features, Use Cases, How It Works

TL;DR, What is bbot?

bbot is a multipurpose, automated open-source recon framework for security professionals.

DevSecOps teams often struggle with chaining reconnaissance tools manually. bbot solves this by providing a unified, event-driven platform that automates the entire pipeline, from discovery to vulnerability scanning. The tool simplifies workflows like subdomain enumeration and correlates findings from over 100 integrated modules. Automating these steps allows your team to shift from scattered manual processes to proactive, continuous asset discovery for attack surface management and bug bounty reconnaissance.

The team at Black Lantern Security developed bbot to make reconnaissance accessible and efficient for security professionals.

Expose cloud risks no other tool can

Learn how Wiz Cloud surfaces toxic combinations across misconfigurations, identities, vulnerabilities, and data—so you can take action fast.

Work Email*

First Name*

Last Name*

Country

Phone Number*

Company*

Keep me updated about Wiz product releases, industry news, and events (You can unsubscribe at any time)

Subscribe me to the Wiz blog digest emails

Submit

For information about how Wiz handles your personal data, please see our Privacy Policy.

Your work email here

Get a demo

At-A-Glance

• GitHub: https://github.com/blacklanternsecurity/bbot

• License: GPL-3.0 license

• Primary Language: Python

• Stars: 9k ⭐

• Last Release: August 2025

• Topics/Tags: python, cli, automation, osint, neo4j, scanner, asm, hacking, recursion, pentesting, recon, bugbounty, threatintel, subdomains, threat-intelligence, subdomain-scanner, osint-framework, subdomain-enumeration, easm, attack-surface-management

Common use cases

1. Bug Bounty Reconnaissance: Security researchers use bbot to map a target's digital footprint for bug bounties. Starting with a single domain, you can use its recursive modules for subdomain enumeration and technology discovery to uncover web applications, APIs, and cloud infrastructure. By integrating vulnerability scanners, you can create a connected workflow from initial asset discovery to identifying and reporting security flaws.

2. Enterprise Attack Surface Management: Organizations use bbot for their attack surface management programs. By scheduling regular, automated scans with presets like subdomain-enum, web-basic  and web-thorough you can achieve continuous asset discovery across your external-facing infrastructure. bbot's structured data output connects with asset inventory systems and security orchestration (SOAR) platforms to help you maintain an accurate view of your security posture.

3. Penetration Testing Engagements: During penetration tests, consultants use bbot's kitchen-sink preset to conduct initial reconnaissance. The preset combines passive data gathering from dozens of APIs with active scanning to build a model of the target environment. The detailed output provides a starting dataset for later phases of the engagement, including a clear map of potential entry points and high-value assets.

4. Threat Intelligence Collection: Threat intelligence analysts use bbot's API integrations to aggregate and correlate data from different sources. By feeding the tool indicators of compromise (IOCs) like domains or IP addresses, you can quickly map out adversary infrastructure and identify related assets. Using bbot this way helps with tracking threat actor campaigns and enriching your internal threat intelligence platforms.

5. Automated Security Pipelines: DevSecOps teams integrate bbot into their CI/CD pipelines to automate security checks. Before deploying new applications or infrastructure, you can run targeted bbot scans to find unmanaged assets exposed to the internet. A proactive approach to asset discovery helps prevent security gaps and control attack surface expansion during development.

How does bbot work?

bbot operates on an event-driven architecture using Python's asyncio for scalable reconnaissance. The workflow begins when the central scanner component receives initial targets (like a domain or IP address) as "events." The events are distributed to relevant modules through a queue-based pipeline. Modules process their input events and emit new ones based on their findings—for example, a subdomain module consumes a DNS_NAME event and produces new subdomain events. The recursive process continuously expands the attack surface map until no new information is found.

• Modular Event Processing: The core is a pipeline where specialized modules communicate via input and output queues for parallelized processing.

• Centralized Orchestration: The scanner component manages the entire lifecycle, from initializing modules and distributing events to coordinating the scan's start and end.

• Recursive Discovery: Events flow recursively. A discovered subdomain feeds back into the pipeline to trigger further DNS, port scanning, or web enumeration modules.

• Efficient & Scalable: The system uses asynchronous operations, event deduplication, and scope management for high throughput and focused scanning.

Core Capabilities:

1. Event-Driven Module System: bbot operates on an event-driven architecture with over 100 specialized modules. Each module consumes and produces specific event types, such as IP_ADDRESS, DNS_NAME, or VULNERABILITY, allowing them to be chained together in an event pipeline. The design enables recursive discovery workflows where the output of one module automatically becomes the input for another. Modules are tagged with flags like “passive” or “aggressive” to give you control over scan behavior. The framework manages the routing and correlation of these events, so you can build reconnaissance strategies by selecting which modules to activate.

2. Preset-Based Scan Configurations: To simplify its capabilities, bbot uses a system of pre-configured scan presets. Presets like subdomain-enum, web-basic, email-enum, spider, web-thorough, and tech-detect  bundle modules and settings for common reconnaissance scenarios. The approach helps new users launch scans immediately. Advanced users can combine multiple presets, override parameters, or define new workflows from scratch using YAML configuration files.

3. Comprehensive API Integration: Native integration with dozens of external APIs and services, including Shodan, VirusTotal, SecurityTrails, and Censys, expands the tool's data-gathering capabilities. bbot's framework manages API keys, handling rate limiting, request retries, and automatic failover between multiple keys for the same service. This integration helps with large-scale passive reconnaissance, allowing the tool to aggregate and correlate intelligence from different sources to map a target's attack surface. Without API keys, the system falls back to open-source alternatives.

4. Advanced Output and Reporting: bbot produces structured data through specialized output modules. The tool supports multiple formats, including JSON, CSV, and plain text, as well as direct integration with databases like Neo4j, Postgres/MySQL/SQLite, Splunk, and Elasticsearch. The output contains metadata like event timestamps, source modules, and the relationships between discovered assets. The structured data helps with integration into other security tools and platforms. Additionally, real-time visualization capabilities, such as through VivaGraphJS, allow you to monitor scan progress and explore the discovered asset network.

5. Intelligent Scope and Filter Management: To help you run efficient and targeted scans, bbot includes a scope and filter management system. The system features configurable whitelists and blacklists, automatic scoping of discovered subdomains, and filtering to exclude assets on common CDNs. A key feature is distance-based scoping, which constrains how many relational “hops” the scan can take from the initial targets, preventing uncontrolled recursive discovery. The framework also includes wildcard domain detection to avoid infinite scanning loops. The controls allow you to define the boundaries of your reconnaissance, reducing noise and focusing resources on in-scope assets.

Limitations

1. Steep Learning Curve for Customization: While presets make initial use accessible, using the event-driven architecture takes time to learn. Creating custom modules, writing complex YAML configurations, and debugging the flow of events between modules require a deep understanding of the framework. The complexity can be a barrier for users who want to move beyond pre-defined scenarios and tailor the tool for specific tasks.

2. High Resource Consumption: Scans using aggressive presets like kitchen-sink can be resource-intensive. Running many modules at once, making thousands of API requests, and processing a large volume of event data can consume significant CPU, memory, and network bandwidth. Because of the resource use, bbot may be less suitable for low-specification machines or environments with constrained network access, and might require dedicated hardware for large-scale scanning.

3. Dependency on External API Keys: Much of the tool's passive intelligence-gathering capability is tied to third-party APIs. The quality of reconnaissance data depends on having valid, and often paid, API keys for services like Shodan, Censys, and SecurityTrails. Without these keys, the framework falls back to less effective, open-source methods. The dependency on external services can create a hidden cost.

4. Potential for Configuration-Induced Noise: The recursive discovery engine, if not carefully configured, can generate a lot of irrelevant data or scan out-of-scope assets. Misconfigured scope rules, permissive filters, or a failure to handle wildcard domains can lead to noisy datasets. You must define precise scanning parameters to ensure the results are focused and relevant.

5. Focused on Reconnaissance, Not Exploitation: bbot does not include native capabilities for vulnerability exploitation or post-exploitation. While bbot can integrate with external tools like Nuclei to identify potential vulnerabilities, the tool remains one component within a broader security assessment toolkit. Teams looking for a single solution for discovery and exploitation will need to connect bbot's output with other penetration testing tools.

Getting Started:

Step 1: Ensure you have Python 3.9 or higher and pipx installed on your system.

Step 2: Install bbot using pipx by running:

pipx install bbot

Step 3: Once installed, verify bbot is available by running:

bbot --help

Step 4: Run your first scan. For example, to find subdomains of a target domain, use:

bbot -t evilcorp.com -p subdomain-enum

Step 5:  Explore further scanning options with presets:

# quick web scan
bbot -t www.evilcorp.com -p web-basic

# heavier web scan
bbot -t www.evilcorp.com -p web-thorough

# emails (pair with spider + subdomain-enum for best yield)
bbot -t evilcorp.com -p email-enum

# everything everywhere all at once (dangerous on prod targets)
bbot -t evilcorp.com -p kitchen-sink --allow-deadly

FAQ

Alternatives