File: README.md

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

Installation

bash

# stable version
pipx install bbot

# bleeding edge (dev branch)
pipx install --pip-args '\--pre' bbot

For more installation methods, including Docker, see Getting Started

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 (source) before upgrading.

Speed tip: BBOT's DNS resolver (blastdns) spins up multiple threads per resolver in /etc/resolv.conf. Adding more unfiltered resolvers dramatically speeds up scans. See the sample resolv.conf and Tips and Tricks 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.

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 of BBOT.

Output Modules

...and more!

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 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 ([email protected])
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. To learn how BBOT handles scope, see 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.

Complete Lists of Modules, Flags, etc.

Complete list of Modules.
Complete list of Flags.
Complete list of Presets.
- Complete list of Global Config Options.
- Complete list of Module Config Options.

Documentation

User Manual
- Basics
- Scanning
  - Scanning Overview
  - Presets
    - Overview
    - List of Presets
  - Events
  - Output
  - Tips and Tricks
  - Advanced Usage
  - Configuration
  - Scan Sanity
- Modules
- Migration
  - 2.x → 3.0 Breaking Changes
- Misc
Developer Manual
- Development Overview
- Setting Up a Dev Environment
- Core Dependencies
- BBOT Internal Architecture
- How to Write a BBOT Module
- Validating & Inspecting Presets
- Unit Tests
- Discord Bot Example
- Code Reference
  - Scanner
  - Presets
  - Event
  - Target
  - BaseModule
  - BBOTCore
  - Helpers
    - Overview
    - Command
    - DNS
    - Interactsh
    - Miscellaneous
    - Web
    - Word Cloud

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. If you want to get your hands dirty, see Contribution. There you can find setup instructions and a simple tutorial on how to write a BBOT module. We also have extensive Developer Documentation.

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 and 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 -->{ .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.

Docker & Self-Hosted Deployment Verified OCI

File: README.md Copy Chapter

**BEE·bot** is a multipurpose scanner inspired by [Spiderfoot](https://github.com/smicallef/spiderfoot), built to automate your **Recon**, **Bug Bounties**, and **ASM**! Copy Section

Installation Copy Chapter

Example Commands Copy Chapter

1) Subdomain Finder Copy Section

2) Web Spider Copy Section

3) Email Gatherer Copy Section

4) Web Scanner Copy Section

5) Everything Everywhere All at Once Copy Section

How it Works Copy Chapter

Output Modules Copy Chapter

BBOT as a Python Library Copy Chapter

Synchronous

Asynchronous

Feature Overview Copy Chapter

Targets Copy Chapter

API Keys Copy Chapter

Complete Lists of Modules, Flags, etc. Copy Chapter

Documentation Copy Chapter

Contribution Copy Chapter

File: docs/dev/helpers/command.md Copy Chapter

Command Helpers

File: docs/dev/helpers/dns.md Copy Chapter

DNS

File: docs/dev/helpers/index.md Copy Chapter

BBOT Helpers

File: docs/dev/helpers/interactsh.md Copy Chapter

Interact.sh

File: docs/dev/helpers/misc.md Copy Chapter

Misc Helpers

File: docs/dev/helpers/web.md Copy Chapter

Web

File: docs/dev/helpers/wordcloud.md Copy Chapter

Word Cloud

File: docs/dev/architecture.md Copy Chapter

BBOT Internal Architecture

Queues Copy Chapter

Event Flow Copy Chapter

Explore Related Technologies & Topics

File: README.md

BEE·bot is a multipurpose scanner inspired by [Spiderfoot](https://github.com/smicallef/spiderfoot), built to automate your Recon, Bug Bounties, and ASM!

Installation

Example Commands

1) Subdomain Finder

2) Web Spider

3) Email Gatherer

4) Web Scanner

5) Everything Everywhere All at Once

How it Works

Output Modules

BBOT as a Python Library

Feature Overview

Targets

API Keys

Complete Lists of Modules, Flags, etc.

Documentation

Contribution

File: docs/dev/helpers/command.md

File: docs/dev/helpers/dns.md

File: docs/dev/helpers/index.md

File: docs/dev/helpers/interactsh.md

File: docs/dev/helpers/misc.md

File: docs/dev/helpers/web.md

File: docs/dev/helpers/wordcloud.md

File: docs/dev/architecture.md

Queues

Event Flow