Getting Started

A BBOT scan in real-time - visualization with VivaGraphJS

Installation

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)

Note

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

Docker images are provided, along with helper script bbot-docker.sh 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 https://github.com/blacklanternsecurity/bbot && cd bbot
./bbot-docker.sh --help

Example Commands

Below are some examples of common scans.

Subdomains:

# Perform a full subdomain enumeration on evilcorp.com
bbot -t evilcorp.com -p subdomain-enum

Subdomains (passive only):

# Perform a passive-only subdomain enumeration on evilcorp.com
bbot -t evilcorp.com -p subdomain-enum -rf passive

Subdomains + port scan + web screenshots:

# Port-scan every subdomain, screenshot every webpage, output to current directory
bbot -t evilcorp.com -p subdomain-enum -m portscan 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 evilcorp.com -p subdomain-enum web-basic

Web spider:

# Crawl www.evilcorp.com up to a max depth of 2, automatically extracting emails, secrets, etc.
bbot -t www.evilcorp.com -p spider -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 evilcorp.com -p kitchen-sink

API Keys

BBOT works just fine without API keys. However, there are certain modules that need them to function. If you have API keys and want to make use of these modules, you can place them either in your preset:

my_preset.yml

description: My custom subdomain enum preset

include:
  - subdomain-enum
  - cloud-enum

config:
  modules:
    shodan_dns:
      api_key: deadbeef
    virustotal:
      api_key: cafebabe

...in BBOT's global YAML config (~/.config/bbot/bbot.yml):

Note: this will ensure the API keys are used in all scans, regardless of preset.

~/.config/bbot/bbot.yml

modules:
  shodan_dns:
    api_key: deadbeef
  virustotal:
    api_key: cafebabe

...or directly on the command-line:

# specify API key with -c
bbot -t evilcorp.com -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 -->