# BBOT: a recursive internet scanner for subdomain enumeration and OSINT

> BBOT is a Python scanner from Black Lantern Security that chains modules recursively across subdomains, web content and email addresses. It installs with pipx, ships preset YAML workflows, and is licensed AGPL-3.0.

**blacklanternsecurity/bbot** — The recursive internet scanner for hackers. 🧡

- Repository: https://github.com/blacklanternsecurity/bbot
- Website: https://www.blacklanternsecurity.com/bbot/
- Stars: 10,625 · Forks: 926
- Language: Python
- License: AGPL-3.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/blacklanternsecurity-bbot

## What BBOT scans that a one-shot subdomain tool does not

Most recon tooling stops at a list. BBOT keeps going. The README describes it as a multipurpose scanner inspired by Spiderfoot, built to automate recon, bug bounties and attack surface management. The word that matters is recursion: when a module discovers a new hostname, that hostname becomes a target for other modules rather than a line in a report.

The practical audience is narrow and technical. Bug bounty hunters, penetration testers and small ASM teams who already know what a subdomain is and want the enumeration, crawling and email gathering steps chained instead of scripted by hand. It is a command line tool first. The Python package is importable, and the repository ships examples/discord_bot.py, but nothing in the README presents it as an application framework.

The README makes a specific performance claim: BBOT consistently finds 20 to 50 percent more subdomains than other tools, and the gap widens with domain size. That figure comes from the project's own comparison, not from an independent test, so treat it as a vendor claim to reproduce on your own targets rather than a settled fact.

## How recursion, presets and modules fit together

BBOT's architecture is visible in its configuration rather than its prose. A scan starts from targets given with -t and a preset given with -p. A preset is a YAML file that declares flags, output modules and config overrides. Flags are the join key: a preset enables a flag such as subdomain-enum, and every module carrying that flag activates.

The subdomain-enum preset shows the pattern directly. It enables the subdomain-enum flag, selects the subdomains output module to write unique subdomains to a text file, and sets dns.threads to 25 and dns.brute_threads to 1000. API keys for services such as github, chaos and securitytrails are commented placeholders in the same file, which tells you the passive sources are optional and require credentials.

Presets compose. web-heavy.yml includes web, kitchen-sink.yml includes nine presets and then overrides individual modules, for example setting recursive_mutations to true for dnsbrute and dnscommonsrv, avoid_wafs to False for webbrute, and urls, parameters and archive to true for wayback. That is the real extension mechanism: a preset is a declaration, and the scanner resolves it into a module graph at runtime.

The README points to a separate How It Works page with an interactive graph for the internals. That page is where the event flow lives. The README itself does not spell out the event types or the internal queue, so anyone debugging module ordering has to leave the README.

## Installing BBOT with pipx and running a first scan

The README gives two install paths. The stable release installs with pipx, and the development branch installs with a pre-release flag. Both assume Python 3.10 or newer, which pyproject.toml pins as >=3.10,<3.15.

```bash
pipx install bbot
```

After that, bbot should be on your PATH. The README points to a Getting Started page and a Docker image for other installation methods, so pipx is the documented default rather than the only option.

A first useful scan is the subdomain-enum preset against a domain you are authorised to test. The README uses evilcorp.com as its example target.

```bash
bbot -t evilcorp.com -p subdomain-enum
```

The preset runs passive API sources plus a recursive DNS brute force with target-specific subdomain mutations, and writes unique subdomains to a text file. If you only want the API sources and no brute forcing, the README shows a second form that restricts the run to passive modules.

```bash
bbot -t evilcorp.com -p subdomain-enum -rf passive
```

For a broader run, kitchen-sink combines subdomain enumeration, cloud and code enumeration, email enumeration, spidering, web scanning, parameter mining, web brute forcing and screenshots. The README notes it is roughly equivalent to passing nine presets explicitly, which is the honest way to read it: kitchen-sink is a shorthand, not a different engine.

## The DNS resolver is the real throughput limit

The README's speed tip is blunt: BBOT's resolver, blastdns, spins up multiple threads per resolver listed in /etc/resolv.conf, and adding more unfiltered resolvers dramatically speeds up scans. A sample resolv.conf is shipped in docs/data/resolv-sample.conf.

This is the constraint most users will hit first, and it is easy to misread as a BBOT problem. Brute forcing at the preset default of 1000 brute_threads against a small resolver pool produces timeouts and retries, not results. The project's own advice is to change the system resolver list, which means BBOT's performance is partly a property of your network environment rather than of the tool.

There is a second, less advertised cost. Presets such as kitchen-sink enable webbrute with avoid_wafs set to False and pull in baddns-heavy. Those are noisy, active techniques. Running kitchen-sink against production infrastructure you do not own will generate traffic that looks like an attack, and the README gives no rate-limiting guidance for that scenario. The passive-only form of subdomain-enum exists precisely because the aggressive form is not always appropriate.

## Where BBOT is the wrong choice

BBOT is a scanner, not a monitoring platform. Nothing in the README describes scheduling, alerting on new assets, or diffing one scan against the next. The deepdiff dependency in pyproject.toml hints that comparison happens somewhere inside the codebase, but the README does not document a continuous monitoring workflow, so do not buy into BBOT as an ASM product replacement on the strength of the topic tags.

It is also a poor fit if you need a single fast subdomain lookup. The install pulls a long dependency list including ansible-core, ansible-runner, yara-python, pyzmq and blasthttp. That is the weight of a modular framework, and it is paid on every machine, container image and CI runner. A shell script around a certificate transparency API will be faster to install and easier to reason about for that one job.

The Python version window is narrower than it looks. The package metadata allows 3.10 through 3.14, and the Dockerfile builds on python:3.11-slim. If your platform is pinned to an older interpreter, you are outside the supported range.

Finally, the README carries a prominent warning that BBOT 3.0 contains breaking changes to the CLI, presets, modules, events and the Python API, with a dedicated migration guide. Anyone upgrading an existing 2.x deployment should read that guide before touching the package, because presets and module configuration are exactly the surface that changed.

## BBOT against Spiderfoot

The README names its inspiration directly: BBOT is inspired by Spiderfoot. The difference in approach is how the two are driven. Spiderfoot is commonly run as a service with a web interface, and the repository's topic list includes neo4j, which points at graph-backed storage for findings.

BBOT is a CLI-first tool. You express a scan as a preset name plus a target, and the preset is a YAML file you can read, copy and edit. That makes the configuration reviewable in a pull request and reproducible on a build agent, which suits scripted pipelines. The trade-off is that there is no documented web UI in the README. The only visualisation referenced is an external project, bbot-vivagraphjs, used to render a scan in real time.

If your team wants analysts clicking through a graph interface without a terminal, Spiderfoot's model matches that workflow more closely. If you want presets in version control and a command you can wrap in CI, BBOT's model is the better fit. Neither is a superset of the other, and the README does not attempt a feature-by-feature comparison.

## Licence and the cost of staying current

BBOT is licensed AGPL-3.0, and pyproject.toml declares license = "AGPL-3.0". That is a strong copyleft licence with a network clause. If you modify BBOT and let users interact with it over a network, the AGPL's source-availability condition is the part to examine. This matters for anyone embedding BBOT inside a commercial service rather than running it as an internal tool. It is not legal advice; take the licence text to whoever handles that for you.

Upgrade cost is unusually visible here. Releases move quickly: 3.0.0 on 2026-07-08, 3.0.1 on 2026-07-21, and 3.0.2 on 2026-08-24. The last push to the repository was on 2026-09-20, so the project is being worked on, but the 3.0 line is young and the migration guide exists because the jump from 2.x was disruptive.

The practical implication is that pinning matters. If your presets or Python integrations depend on BBOT internals, a minor version bump can move them. The README's own upgrade note is the signal: read the 2.x to 3.0 migration guide before upgrading, and expect the same discipline for future major versions.

## Conclusion

Adopt BBOT if you need recursive, module-driven recon and you are comfortable with AGPL-3.0 obligations and the 3.0 breaking changes. Skip it if you want a single-purpose subdomain tool or cannot run Python 3.10 to 3.14. Before installing, open the 2.x to 3.0 migration guide and confirm your resolver setup, because DNS throughput shapes scan duration more than any other setting.

## FAQ

### What does BBOT do?

BBOT is a multipurpose scanner inspired by Spiderfoot, built to automate recon, bug bounties and attack surface management. It runs modules recursively from a target, enumerating subdomains, crawling web content and gathering email addresses depending on the preset you choose.

### How can I build my own BBOT?

The README does not document building BBOT from source. It gives pipx install commands for the stable and development versions, and points to a Getting Started page for other installation methods including Docker.

### How do I install the BBOT scanner?

The README's stable install is pipx install bbot, and the bleeding edge version is pipx install --pip-args '\--pre' bbot. Both require Python 3.10 or newer.

### How does BBOT subdomain enumeration work?

The subdomain-enum preset enables the subdomain-enum flag, which activates every module carrying that flag, and combines passive API sources with a recursive DNS brute force using target-specific subdomain mutations. It writes unique subdomains to a text file through the subdomains output module.

### Can I run BBOT without brute forcing?

Yes. The README shows bbot -t evilcorp.com -p subdomain-enum -rf passive, which restricts the run to passive sources only.

## Sources

- [blacklanternsecurity/bbot on GitHub](https://github.com/blacklanternsecurity/bbot)
- [License: AGPL-3.0](https://github.com/blacklanternsecurity/bbot/blob/stable/LICENSE)
- [Project website](https://www.blacklanternsecurity.com/bbot/)
- [README](https://github.com/blacklanternsecurity/bbot/blob/stable/README.md)
- [Releases](https://github.com/blacklanternsecurity/bbot/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/blacklanternsecurity-bbot