bbot README

The project's README from github.com/blacklanternsecurity/bbot. As one markdown file: README.md.

bbot_banner

Python Version License PyPi Downloads Ruff Tests Codecov Discord

BEE·bot is a multipurpose scanner inspired by 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

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

# 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 
description: Enumerate subdomains via APIs, brute-force

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.

subdomain-stats-ebay

2) Web Spider

# crawl evilcorp.com, extracting emails and other goodies
bbot -t evilcorp.com -p spider
spider.yml 
description: Recursive web spider

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

# 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 
description: Enumerate email addresses from APIs, web crawling, etc.

flags:
  - email-enum

output_modules:
  - emails

4) Web Scanner

# 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 
description: Quick web scan

include:
  - iis-shortnames

flags:
  - web
web-heavy.yml 
description: Aggressive web scan

include:
  # include the web preset
  - web

flags:
  - web-heavy

5) Everything Everywhere All at Once

# 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 
description: Everything everywhere all at once

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.

image

Output Modules

...and more!

BBOT as a Python Library

Synchronous

from bbot.scanner import Scanner

if __name__ == "__main__":
    scan = Scanner("evilcorp.com", presets=["subdomain-enum"])
    for event in scan.start():
        print(event)

Asynchronous

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!

bbot-discord

Feature Overview

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!):

bbot -t evilcorp.com evilcorp.org 1.2.3.0/24 -p subdomain-enum

Targets can be any of the following:

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:

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:

bbot -c modules.virustotal.api_key=dd5f0eee2e4a99b71a939bded450b246

For details, see Configuration.

Complete Lists of Modules, Flags, etc.

Documentation

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:

bbot (blacklanternsecurity/bbot)

Searching Database…

10.7K ·GitHub
Bbot
What is this?BBOT is a recursive internet scanner for hackers — it automates recon, bug bounty work and attack surface management (ASM), inspired by Spiderfoot.
Is BBOT a CLI tool or a Python library?Both: you normally drive it from the CLI with presets like web or kitchen-sink, but there is also a full Python API (sync and async) plus developer docs for writing your own modules.
Do I need API keys to run a scan?Not to start scanning, but BBOT supports API keys for third-party services like SecurityTrails — you enter them in ~/.config/bbot/secrets.yml, and multiple keys per service are allowed.
I'm on BBOT 2.x — can I upgrade straight to 3.0?Not without homework: 3.0 has breaking changes to the CLI, presets, modules, events and the Python API, so read the 2.x → 3.0 Migration Guide first.
Is it Linux-only, or does it run on macOS and Windows too?It's a Python tool, so it runs on Linux, macOS and Windows, and a Docker image is available if you'd rather keep it in a container.
What can I point BBOT at?Almost anything: DNS names, IPs, IP ranges, open TCP ports, URLs, email addresses, whole organizations (ORG:evilcorp), usernames (USER:bob), local filesystems and even mobile apps — with unlimited targets via -t.
What scan presets does it ship with?Six ready-made ones: subdomain-enum (passive sources plus recursive DNS brute-force), spider, email-enum, web, web-heavy and kitchen-sink, which runs everything at once.
Where do scan results end up?Natively into Neo4j for graph visualization, plus output modules for Slack, Discord, Teams, Splunk, Elasticsearch, Postgres, MySQL, SQLite, CSV, JSON, HTTP and Websockets.
Why does it find more subdomains than other tools?It combines passive API sources with a recursive DNS brute-force that uses target-specific, NLP-powered subdomain mutations — the team says it consistently finds 20-50% more subdomains, and the bigger the domain, the bigger the gap.
What are similar projects?OneForAll, spiderfoot, Sn1per, flowsint, gobuster, Sublist3r, theHarvester, subfinder
Which topics is it in?subdomain-enumeration, osint-framework, bruteforce, recon, bugbounty, neo4j, bug-bounty, threat-intelligence, scanner, reconnaissance, network, osint
Creator
blacklanternsecurity
Size
119.5 MB
Stars
10.7K
Updated
CommitAug 24Releasev3.0.2Aug 24
Age
4y
Commits · 90 Days