Skip to content

Getting Started

A BBOT scan in real-time - visualization with VivaGraphJS


Supported Platforms

Only Linux is supported at this time. Windows and macOS are not supported. If you use one of these platforms, consider using Docker.

BBOT offers multiple methods of installation, including pipx and Docker. If you plan to dev on BBOT, see Installation (Poetry).

Python (pip / pipx)


pipx installs BBOT inside its own virtual environment.

# stable version
pipx install bbot

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

# execute bbot command
bbot --help


Docker images are provided, along with helper script to persist your scan data.

# bleeding edge (dev)
docker run -it blacklanternsecurity/bbot --help

# stable
docker run -it blacklanternsecurity/bbot:stable --help

# helper script
git clone && cd bbot
./ --help

Example Commands

Below are some examples of common scans.


# Perform a full subdomain enumeration on
bbot -t -f subdomain-enum

Subdomains (passive only):

# Perform a passive-only subdomain enumeration on
bbot -t -f subdomain-enum -rf passive

Subdomains + port scan + web screenshots:

# Port-scan every subdomain, screenshot every webpage, output to current directory
bbot -t -f subdomain-enum -m nmap gowitness -n my_scan -o .

Subdomains + basic web scan:

# A basic web scan includes wappalyzer, robots.txt, and other non-intrusive web modules
bbot -t -f subdomain-enum web-basic

Web spider:

# Crawl up to a max depth of 2, automatically extracting emails, secrets, etc.
bbot -t -m httpx robots badsecrets secretsdb -c web_spider_distance=2 web_spider_depth=2

Everything everywhere all at once:

# Subdomains, emails, cloud buckets, port scan, basic web, web screenshots, nuclei
bbot -t -f subdomain-enum email-enum cloud-enum web-basic -m nmap gowitness nuclei --allow-deadly

API Keys

No API keys are required to run BBOT. However, some modules need them to function. If you have API keys and want to make use of these modules, you can place them either in BBOT's YAML config (~/.config/bbot/secrets.yml):

    api_key: deadbeef
    api_key: cafebabe

Or on the command-line:

# specify API key with -c
bbot -t -f subdomain-enum -c modules.shodan_dns.api_key=deadbeef modules.virustotal.api_key=cafebabe

For more information, see Configuration. For a full list of modules, including which ones require API keys, see List of Modules.

Next Up: Scanning -->