## File: README.md [](https://github.com/blacklanternsecurity/bbot) [](https://www.python.org) [](https://github.com/blacklanternsecurity/bbot/blob/dev/LICENSE) [](https://pepy.tech/project/bbot) [](https://github.com/astral-sh/ruff) [](https://github.com/blacklanternsecurity/bbot/actions?query=workflow%3A"tests") [](https://codecov.io/gh/blacklanternsecurity/bbot) [](https://discord.com/invite/PZqkgxu5SA) ### **BEE·bot** is a multipurpose scanner inspired by [Spiderfoot](https://github.com/smicallef/spiderfoot), built to automate your **Recon**, **Bug Bounties**, and **ASM**! https://github.com/blacklanternsecurity/bbot/assets/20261699/e539e89b-92ea-46fa-b893-9cde94eebf81 _A BBOT scan in real-time - visualization with [VivaGraphJS](https://github.com/blacklanternsecurity/bbot-vivagraphjs)_ ## Installation ```bash # stable version pipx install bbot # bleeding edge (dev branch) pipx install --pip-args '\--pre' bbot ``` _For more installation methods, including [Docker](https://hub.docker.com/r/blacklanternsecurity/bbot), see [Getting Started](https://www.blacklanternsecurity.com/bbot/Stable/)_ > **Upgrading from 2.x?** BBOT 3.0 contains breaking changes to the CLI, presets, modules, events, and Python API. See the [2.x → 3.0 Migration Guide](https://www.blacklanternsecurity.com/bbot/Stable/migration/3.0_breaking_changes/) ([source](docs/migration/3.0_breaking_changes.md)) before upgrading. > **Speed tip:** BBOT's DNS resolver ([blastdns](https://github.com/blacklanternsecurity/blastdns)) spins up multiple threads per resolver in `/etc/resolv.conf`. Adding more unfiltered resolvers dramatically speeds up scans. See the [sample resolv.conf](docs/data/resolv-sample.conf) and [Tips and Tricks](https://www.blacklanternsecurity.com/bbot/Stable/scanning/tips_and_tricks/#speed-up-scans-with-more-dns-resolvers) for details. ## Example Commands ### 1) Subdomain Finder Passive API sources plus a recursive DNS brute-force with target-specific subdomain mutations. ```bash # find subdomains of evilcorp.com bbot -t evilcorp.com -p subdomain-enum # passive sources only bbot -t evilcorp.com -p subdomain-enum -rf passive ``` **`subdomain-enum.yml`** ```yaml flags: # enable every module with the subdomain-enum flag - subdomain-enum output_modules: # output unique subdomains to TXT file - subdomains config: dns: threads: 25 brute_threads: 1000 # put your API keys here # modules: # github: # api_key: "" # chaos: # api_key: "" # securitytrails: # api_key: "" ``` BBOT consistently finds 20-50% more subdomains than other tools. The bigger the domain, the bigger the difference. To learn how this is possible, see [How It Works](https://www.blacklanternsecurity.com/bbot/Stable/how_it_works/). ### 2) Web Spider ```bash # crawl evilcorp.com, extracting emails and other goodies bbot -t evilcorp.com -p spider ``` **`spider.yml`** ```yaml modules: - http blacklist: # Prevent spider from invalidating sessions by logging out - "RE:/.*(sign|log)[_-]?out" config: web: # how many links to follow in a row spider_distance: 2 # don't follow links whose directory depth is higher than 4 spider_depth: 4 # maximum number of links to follow per page spider_links_per_page: 25 ``` ### 3) Email Gatherer ```bash # quick email enum with free APIs + scraping bbot -t evilcorp.com -p email-enum # pair with subdomain enum + web spider for maximum yield bbot -t evilcorp.com -p email-enum subdomain-enum spider ``` **`email-enum.yml`** ```yaml flags: - email-enum output_modules: - emails ``` ### 4) Web Scanner ```bash # run a light web scan against www.evilcorp.com bbot -t www.evilcorp.com -p web # run a heavy web scan against www.evilcorp.com bbot -t www.evilcorp.com -p web-heavy ``` **`web.yml`** ```yaml include: - iis-shortnames flags: - web ``` **`web-heavy.yml`** ```yaml include: # include the web preset - web flags: - web-heavy ``` ### 5) Everything Everywhere All at Once ```bash # everything everywhere all at once bbot -t evilcorp.com -p kitchen-sink # roughly equivalent to: bbot -t evilcorp.com -p subdomain-enum cloud-enum code-enum email-enum spider web paramminer webbrute web-screenshots ``` **`kitchen-sink.yml`** ```yaml include: - subdomain-enum - cloud-enum - code-enum - email-enum - spider - web - paramminer - webbrute - web-screenshots - baddns-heavy config: modules: dnsbrute: recursive_mutations: true dnscommonsrv: recursive_mutations: true webbrute: avoid_wafs: False wayback: urls: True parameters: True archive: True ``` ## How it Works Click the graph below to explore the [inner workings](https://www.blacklanternsecurity.com/bbot/Stable/how_it_works/) of BBOT. [](https://www.blacklanternsecurity.com/bbot/Stable/how_it_works/) ## Output Modules - [Neo4j](docs/scanning/output.md#neo4j) - [Teams](docs/scanning/output.md#teams) - [Discord](docs/scanning/output.md#discord) - [Slack](docs/scanning/output.md#slack) - [Postgres](docs/scanning/output.md#postgres) - [MySQL](docs/scanning/output.md#mysql) - [SQLite](docs/scanning/output.md#sqlite) - [Splunk](docs/scanning/output.md#splunk) - [Elasticsearch](docs/scanning/output.md#elasticsearch) - [CSV](docs/scanning/output.md#csv) - [JSON](docs/scanning/output.md#json) - [HTTP](docs/scanning/output.md#http) - [Websocket](docs/scanning/output.md#websocket) ...and [more](docs/scanning/output.md)! ## BBOT as a Python Library #### Synchronous ```python from bbot.scanner import Scanner if __name__ == "__main__": scan = Scanner("evilcorp.com", presets=["subdomain-enum"]) for event in scan.start(): print(event) ``` #### Asynchronous ```python from bbot.scanner import Scanner async def main(): scan = Scanner("evilcorp.com", presets=["subdomain-enum"]) async for event in scan.async_start(): print(event.json()) if __name__ == "__main__": import asyncio asyncio.run(main()) ``` **SEE: This Nefarious Discord Bot** A [BBOT Discord Bot](https://www.blacklanternsecurity.com/bbot/Stable/dev/#discord-bot-example) that responds to the `/scan` command. Scan the internet from the comfort of your discord server! ## Feature Overview - Support for Multiple Targets - Web Screenshots - Suite of Offensive Web Modules - NLP-powered Subdomain Mutations - Native Output to Neo4j (and more) - Automatic dependency install with Ansible - Search entire attack surface with custom YARA rules - Python API + Developer Documentation ## Targets BBOT accepts an unlimited number of targets via `-t`. You can specify targets either directly on the command line or in files (or both!): ```bash bbot -t evilcorp.com evilcorp.org 1.2.3.0/24 -p subdomain-enum ``` Targets can be any of the following: - DNS Name (`evilcorp.com`) - IP Address (`1.2.3.4`) - IP Range (`1.2.3.0/24`) - Open TCP Port (`192.168.0.1:80`) - URL (`https://www.evilcorp.com`) - Email Address (`bob@evilcorp.com`) - Organization (`ORG:evilcorp`) - Username (`USER:bobsmith`) - Filesystem (`FILESYSTEM:/tmp/asdf`) - Mobile App (`MOBILE_APP:https://play.google.com/store/apps/details?id=com.evilcorp.app`) For more information, see [Targets](https://www.blacklanternsecurity.com/bbot/Stable/scanning/#targets-t). To learn how BBOT handles scope, see [Scope](https://www.blacklanternsecurity.com/bbot/Stable/scanning/#scope). ## API Keys Similar to Amass or Subfinder, BBOT supports API keys for various third-party services such as SecurityTrails, etc. The standard way to do this is to enter your API keys in **`~/.config/bbot/secrets.yml`**. Note that multiple API keys are allowed: ```yaml modules: shodan_dns: api_key: 4f41243847da693a4f356c0486114bc6 c99: # multiple API keys api_key: - 21a270d5f59c9b05813a72bb41707266 - ea8f243d9885cf8ce9876a580224fd3c - 5bc6ed268ab6488270e496d3183a1a27 virustotal: api_key: dd5f0eee2e4a99b71a939bded450b246 securitytrails: api_key: d9a05c3fd9a514497713c54b4455d0b0 ``` If you like, you can also specify them on the command line: ```bash bbot -c modules.virustotal.api_key=dd5f0eee2e4a99b71a939bded450b246 ``` For details, see [Configuration](https://www.blacklanternsecurity.com/bbot/Stable/scanning/configuration/). ## Complete Lists of Modules, Flags, etc. - Complete list of [Modules](https://www.blacklanternsecurity.com/bbot/Stable/modules/list_of_modules/). - Complete list of [Flags](https://www.blacklanternsecurity.com/bbot/Stable/scanning/#list-of-flags). - Complete list of [Presets](https://www.blacklanternsecurity.com/bbot/Stable/scanning/presets_list/). - Complete list of [Global Config Options](https://www.blacklanternsecurity.com/bbot/Stable/scanning/configuration/#global-config-options). - Complete list of [Module Config Options](https://www.blacklanternsecurity.com/bbot/Stable/scanning/configuration/#module-config-options). ## Documentation - **User Manual** - **Basics** - [Getting Started](https://www.blacklanternsecurity.com/bbot/Stable/) - [How it Works](https://www.blacklanternsecurity.com/bbot/Stable/how_it_works) - [Comparison to Other Tools](https://www.blacklanternsecurity.com/bbot/Stable/comparison) - **Scanning** - [Scanning Overview](https://www.blacklanternsecurity.com/bbot/Stable/scanning/) - **Presets** - [Overview](https://www.blacklanternsecurity.com/bbot/Stable/scanning/presets) - [List of Presets](https://www.blacklanternsecurity.com/bbot/Stable/scanning/presets_list) - [Events](https://www.blacklanternsecurity.com/bbot/Stable/scanning/events) - [Output](https://www.blacklanternsecurity.com/bbot/Stable/scanning/output) - [Tips and Tricks](https://www.blacklanternsecurity.com/bbot/Stable/scanning/tips_and_tricks) - [Advanced Usage](https://www.blacklanternsecurity.com/bbot/Stable/scanning/advanced) - [Configuration](https://www.blacklanternsecurity.com/bbot/Stable/scanning/configuration) - [Scan Sanity](https://www.blacklanternsecurity.com/bbot/Stable/scanning/scan_sanity) - **Modules** - [List of Modules](https://www.blacklanternsecurity.com/bbot/Stable/modules/list_of_modules) - [Internal Modules](https://www.blacklanternsecurity.com/bbot/Stable/modules/internal_modules) - [Nuclei](https://www.blacklanternsecurity.com/bbot/Stable/modules/nuclei) - [Wayback](https://www.blacklanternsecurity.com/bbot/Stable/modules/wayback) - [Custom YARA Rules](https://www.blacklanternsecurity.com/bbot/Stable/modules/custom_yara_rules) - [Lightfuzz](https://www.blacklanternsecurity.com/bbot/Stable/modules/lightfuzz) - [Webbrute](https://www.blacklanternsecurity.com/bbot/Stable/modules/webbrute) - **Migration** - [2.x → 3.0 Breaking Changes](https://www.blacklanternsecurity.com/bbot/Stable/migration/3.0_breaking_changes) - **Misc** - [Contribution](https://www.blacklanternsecurity.com/bbot/Stable/contribution) - [Release History](https://www.blacklanternsecurity.com/bbot/Stable/release_history) - [Troubleshooting](https://www.blacklanternsecurity.com/bbot/Stable/troubleshooting) - **Developer Manual** - [Development Overview](https://www.blacklanternsecurity.com/bbot/Stable/dev/) - [Setting Up a Dev Environment](https://www.blacklanternsecurity.com/bbot/Stable/dev/dev_environment) - [Core Dependencies](https://www.blacklanternsecurity.com/bbot/Stable/dev/core_dependencies) - [BBOT Internal Architecture](https://www.blacklanternsecurity.com/bbot/Stable/dev/architecture) - [How to Write a BBOT Module](https://www.blacklanternsecurity.com/bbot/Stable/dev/module_howto) - [Validating & Inspecting Presets](https://www.blacklanternsecurity.com/bbot/Stable/dev/preset_validation) - [Unit Tests](https://www.blacklanternsecurity.com/bbot/Stable/dev/tests) - [Discord Bot Example](https://www.blacklanternsecurity.com/bbot/Stable/dev/discord_bot) - **Code Reference** - [Scanner](https://www.blacklanternsecurity.com/bbot/Stable/dev/scanner) - [Presets](https://www.blacklanternsecurity.com/bbot/Stable/dev/presets) - [Event](https://www.blacklanternsecurity.com/bbot/Stable/dev/event) - [Target](https://www.blacklanternsecurity.com/bbot/Stable/dev/target) - [BaseModule](https://www.blacklanternsecurity.com/bbot/Stable/dev/basemodule) - [BBOTCore](https://www.blacklanternsecurity.com/bbot/Stable/dev/core) - **Helpers** - [Overview](https://www.blacklanternsecurity.com/bbot/Stable/dev/helpers/) - [Command](https://www.blacklanternsecurity.com/bbot/Stable/dev/helpers/command) - [DNS](https://www.blacklanternsecurity.com/bbot/Stable/dev/helpers/dns) - [Interactsh](https://www.blacklanternsecurity.com/bbot/Stable/dev/helpers/interactsh) - [Miscellaneous](https://www.blacklanternsecurity.com/bbot/Stable/dev/helpers/misc) - [Web](https://www.blacklanternsecurity.com/bbot/Stable/dev/helpers/web) - [Word Cloud](https://www.blacklanternsecurity.com/bbot/Stable/dev/helpers/wordcloud) ## Contribution Some of the best BBOT modules were written by the community. BBOT is being constantly improved; every day it grows more powerful! We welcome contributions. Not just code, but ideas too! If you have an idea for a new feature, please let us know in [Discussions](https://github.com/blacklanternsecurity/bbot/discussions). If you want to get your hands dirty, see [Contribution](https://www.blacklanternsecurity.com/bbot/Stable/contribution/). There you can find setup instructions and a simple tutorial on how to write a BBOT module. We also have extensive [Developer Documentation](https://www.blacklanternsecurity.com/bbot/Stable/dev/). Thanks to these amazing people for contributing to BBOT! :heart: Special thanks to: - @TheTechromancer for creating BBOT - @liquidsec for his extensive work on BBOT's web hacking features, including [badsecrets](https://github.com/blacklanternsecurity/badsecrets) and [baddns](https://github.com/blacklanternsecurity/baddns) - Steve Micallef (@smicallef) for creating Spiderfoot - @kerrymilan for his Neo4j and Ansible expertise - @domwhewell-sage for his family of badass code-looting modules - @aconite33 and @amiremami for their ruthless testing - Aleksei Kornev (@alekseiko) for granting us ownership of the bbot Pypi repository <3 --- ## File: docs/dev/helpers/command.md # Command Helpers These are helpers related to executing shell commands. They are used throughout BBOT and its modules for executing various binaries such as `masscan`, `nuclei`, etc. These helpers can be invoked directly from `self.helpers`, but inside a module they should always use `self.run_process()` or `self.run_process_live()`. These are light wrappers which ensure the running process is tracked by the module so that it can be easily terminated should the user need to kill the module: ```python # simple subprocess ls_result = await self.run_process("ls", "-l") for line in ls_result.stdout.splitlines(): # ... # iterate through each line in real time async for line in self.run_process_live(["grep", "-R"]): # ... ``` ::: bbot.core.helpers.command options: show_root_heading: false --- ## File: docs/dev/helpers/dns.md # DNS These are helpers related to DNS resolution. They are used throughout BBOT and its modules for performing DNS lookups and detecting DNS wildcards, etc. Note that these helpers can be invoked directly from `self.helpers`, e.g.: ```python await self.helpers.resolve("evilcorp.com") ``` ::: bbot.core.helpers.dns.DNSHelper handler: python options: members: - resolve - resolve_full - resolve_multi_full - resolve_batch_full - is_wildcard - is_wildcard_domain --- ## File: docs/dev/helpers/index.md # BBOT Helpers In this section are various helper functions that are designed to make your life easier when devving on BBOT. Whether you're extending BBOT by writing a module or working on its core, these functions are designed to act as useful machine parts to perform essential tasks, such as making a web request or executing a DNS query. The vast majority of these helpers can be accessed directly from the `.helpers` attribute of a scan or module, like so: ```python class MyModule(BaseModule): ... async def handle_event(self, event): # Web Request response = await self.helpers.request("https://www.evilcorp.com") # DNS query for ip in await self.helpers.resolve("www.evilcorp.com"): self.hugesuccess(str(ip)) # Execute shell command completed_process = await self.run_process("ls", "-l") self.hugesuccess(completed_process.stdout) # Split a DNS name into subdomain / domain self.helpers.split_domain("www.internal.evilcorp.co.uk") # ("www.internal", "evilcorp.co.uk") ``` [Next Up: Command Helpers -->](command.md){ .md-button .md-button--primary } --- ## File: docs/dev/helpers/interactsh.md # Interact.sh ::: bbot.core.helpers.interactsh.Interactsh options: show_root_heading: false --- ## File: docs/dev/helpers/misc.md # Misc Helpers These are miscellaneous helpers, used throughout BBOT and its modules for simple tasks such as parsing domains, ports, urls, etc. ::: bbot.core.helpers.misc options: show_root_heading: false --- ## File: docs/dev/helpers/web.md # Web These are helpers for making various web requests. Note that these helpers can be invoked directly from `self.helpers`, e.g.: ```python self.helpers.request("https://www.evilcorp.com") ``` ::: bbot.core.helpers.web options: show_root_heading: false members: - WebHelper --- ## File: docs/dev/helpers/wordcloud.md # Word Cloud These are helpers related to BBOT's Word Cloud, a mechanism for storing target-specific keywords that are useful for custom wordlists, etc. Note that these helpers can be invoked directly from `self.helpers`, e.g.: ```python self.helpers.word_cloud ``` ::: bbot.core.helpers.wordcloud options: show_root_heading: false --- ## File: docs/dev/architecture.md # BBOT Internal Architecture Here is a basic overview of BBOT's internal architecture. ## Queues Being both ***recursive*** and ***event-driven***, BBOT makes heavy use of queues. These enable smooth communication between the modules, and ensure that large numbers of events can be produced without slowing down or clogging up the scan. Every module in BBOT has both an ***incoming*** and ***outgoing*** queue. Event types matching the module's `watched_events` (e.g. `DNS_NAME`) are queued in its incoming queue, and processed by the module's `handle_event()` (or `handle_batch()` in the case of batched modules). If the module finds anything interesting, it creates an event and places it in its outgoing queue, to be processed by the scan and redistributed to other modules. ## Event Flow Below is a graph showing the internal event flow in BBOT. White lines represent queues. Notice how some modules run in sequence, while others run in parallel. With the exception of a few specific modules, most BBOT modules are parallelized. For a higher-level overview, see [How it Works](../how_it_works.md).