Skip to content

BBOT Docs

Getting Started

 

blacklanternsecurity/bbot

• 9.2k
• 761

• User Manual
  • Basics
    • Getting Started
      • Installation
        • Python (pip / pipx)
        • Docker
      • Example Commands
      • API Keys
    • How it Works
    • Comparison to Other Tools
  • Scanning
    • Scanning Overview
    • Presets
      • Overview
      • List of Presets
    • Events
    • Output
    • Tips and Tricks
    • Advanced Usage
    • Configuration
  • Modules
    • List of Modules
    • Nuclei
    • Custom YARA Rules
    • Lightfuzz
  • Misc
    • Contribution
    • Release History
    • Troubleshooting

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're looking to tinker or write your own module, see Setting up a Dev Environment.

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.

Scans are output to ~/.bbot/scans (the usual place for BBOT 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

Note: If you need to pass in a custom preset, you can do so by mapping the preset into the container:

# use the preset `my_preset.yml` from the current directory
docker run --rm -it \
  -v "$HOME/.bbot/scans:/root/.bbot/scans" \
  -v "$PWD/my_preset.yml:/my_preset.yml" \
  blacklanternsecurity/bbot -p /my_preset.yml

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 -->

Made with Material for MkDocs