# blacklanternsecurity/bbot architecture

> Architecture diagram of the GitHub repository blacklanternsecurity/bbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blacklanternsecurity/bbot
- Repository: https://github.com/blacklanternsecurity/bbot

## Overview

BBOT is a modular reconnaissance and attack-surface scanner. Users provide targets and presets through the CLI or Python API; a scan prepares its preset, seeds events, and runs modules that discover and enrich assets. Results are streamed as events or handled by output modules, with JSON and many other destinations documented. The graph preserves major discovery, web-scanning, and output capabilities. Several runtime connections are inferred from the architecture but were not visible in the excerpts, so those edges are dashed and uncited.

Main entry points: [`bbot/core/event/base.py`](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/core/event/base.py) (Scan events), [`bbot/scanner/scanner.py`](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/scanner/scanner.py) (Scanner API), [`bbot/scanner/preset/preset.py`](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/scanner/preset/preset.py) (Preset setup), [`bbot/modules/base.py`](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/base.py) (Module runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Scan entry"]
  node_cli["Command line<br/>[cli.py]"]
  node_scanner["Scanner API<br/>[scanner.py]"]
  node_preset["Preset setup<br/>[preset.py]"]
  node_preset_validation["Preset validation<br/>[validate.py]"]
end

subgraph group_runtime["Scan runtime"]
  node_manager["Scan manager<br/>[manager.py]"]
  node_dispatcher["Event dispatcher<br/>[dispatcher.py]"]
  node_module_loader["Module registry<br/>[modules.py]"]
  node_module_base["Module runtime<br/>[base.py]"]
end

subgraph group_discovery["Discovery modules"]
  node_dns["DNS discovery<br/>[dns.py]"]
  node_dns_modules["DNS enumeration<br/>[dnsbrute.py]"]
  node_internal_modules["Internal analysis"]
  node_enrichment["Asset enrichment"]
end

subgraph group_web["Web analysis"]
  node_http_module["HTTP crawling<br/>[http.py]"]
  node_web_helpers["Web helpers<br/>[web.py]"]
  node_lightfuzz["Web fuzzing<br/>[lightfuzz.py]"]
  node_fuzz_base["Fuzz submodules<br/>[base.py]"]
end

subgraph group_events["Events and models"]
  node_event["Scan events<br/>[base.py]"]
  node_event_model["Event model<br/>[pydantic.py]"]
  node_config["Configuration schema<br/>[models.py]"]
end

subgraph group_outputs["Output modules"]
  node_output_base["Output runtime<br/>[base.py]"]
  node_json_output["JSON output<br/>[json.py]"]
  node_other_outputs["Other destinations"]
end

node_user(("Scan user"))

node_user -->|"runs scan"| node_cli
node_user -->|"starts scan"| node_scanner
node_cli -->|"launches"| node_scanner
node_scanner -->|"loads preset"| node_preset
node_preset -.->|"validates"| node_preset_validation
node_scanner -->|"coordinates"| node_manager
node_scanner -->|"dispatches through"| node_dispatcher
node_scanner -->|"creates events"| node_event
node_manager -->|"inherits from"| node_module_base
node_preset -->|"loads modules"| node_module_loader
node_module_base -.->|"queues events"| node_event
node_dns_modules -.->|"uses resolver"| node_dns
node_http_module -.->|"uses web client"| node_web_helpers
node_lightfuzz -->|"uses submodules"| node_fuzz_base
node_lightfuzz -.->|"tests web targets"| node_web_helpers
node_internal_modules -.->|"analyzes events"| node_event
node_event -->|"serializes as"| node_event_model
node_preset -->|"configures scan"| node_config
node_module_base -->|"reads module config"| node_config
node_json_output -->|"extends"| node_output_base
node_json_output -->|"serializes events"| node_event
node_event -.->|"feeds destinations"| node_other_outputs
node_event -->|"streams results"| node_json_output

click node_cli "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/cli.py"
click node_scanner "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/scanner/scanner.py"
click node_preset "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/scanner/preset/preset.py"
click node_preset_validation "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/scanner/preset/validate.py"
click node_manager "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/scanner/manager.py"
click node_dispatcher "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/scanner/dispatcher.py"
click node_module_loader "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/core/modules.py"
click node_module_base "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/base.py"
click node_dns "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/core/helpers/dns/dns.py"
click node_dns_modules "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/dnsbrute.py"
click node_internal_modules "https://github.com/blacklanternsecurity/bbot/tree/stable/bbot/modules/internal"
click node_enrichment "https://github.com/blacklanternsecurity/bbot/tree/stable/bbot/modules"
click node_http_module "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/http.py"
click node_web_helpers "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/core/helpers/web/web.py"
click node_lightfuzz "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/lightfuzz/lightfuzz.py"
click node_fuzz_base "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/lightfuzz/submodules/base.py"
click node_event "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/core/event/base.py"
click node_event_model "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/models/pydantic.py"
click node_config "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/core/config/models.py"
click node_output_base "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/output/base.py"
click node_json_output "https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/output/json.py"
click node_other_outputs "https://github.com/blacklanternsecurity/bbot/tree/stable/bbot/modules/output"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_scanner,node_preset,node_preset_validation,node_user toneBlue
class node_manager,node_dispatcher,node_module_loader,node_module_base toneAmber
class node_dns,node_dns_modules,node_internal_modules,node_enrichment toneMint
class node_http_module,node_web_helpers,node_lightfuzz,node_fuzz_base toneRose
class node_event,node_event_model,node_config toneIndigo
class node_output_base,node_json_output,node_other_outputs toneTeal
```

## Components

### Scan entry

- [Command line](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/cli.py): `bbot/cli.py`
- [Scanner API](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/scanner/scanner.py): `bbot/scanner/scanner.py`
- [Preset setup](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/scanner/preset/preset.py): `bbot/scanner/preset/preset.py`
- [Preset validation](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/scanner/preset/validate.py): `bbot/scanner/preset/validate.py`

### Scan runtime

- [Scan manager](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/scanner/manager.py): `bbot/scanner/manager.py`
- [Event dispatcher](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/scanner/dispatcher.py): `bbot/scanner/dispatcher.py`
- [Module registry](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/core/modules.py): `bbot/core/modules.py`
- [Module runtime](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/base.py): `bbot/modules/base.py`

### Discovery modules

- [DNS discovery](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/core/helpers/dns/dns.py): `bbot/core/helpers/dns/dns.py`
- [DNS enumeration](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/dnsbrute.py): `bbot/modules/dnsbrute.py`
- [Internal analysis](https://github.com/blacklanternsecurity/bbot/tree/stable/bbot/modules/internal): `bbot/modules/internal`
- [Asset enrichment](https://github.com/blacklanternsecurity/bbot/tree/stable/bbot/modules): `bbot/modules`

### Web analysis

- [HTTP crawling](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/http.py): `bbot/modules/http.py`
- [Web helpers](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/core/helpers/web/web.py): `bbot/core/helpers/web/web.py`
- [Web fuzzing](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/lightfuzz/lightfuzz.py): `bbot/modules/lightfuzz/lightfuzz.py`
- [Fuzz submodules](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/lightfuzz/submodules/base.py): `bbot/modules/lightfuzz/submodules/base.py`

### Events and models

- [Scan events](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/core/event/base.py): `bbot/core/event/base.py`
- [Event model](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/models/pydantic.py): `bbot/models/pydantic.py`
- [Configuration schema](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/core/config/models.py): `bbot/core/config/models.py`

### Output modules

- [Output runtime](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/output/base.py): `bbot/modules/output/base.py`
- [JSON output](https://github.com/blacklanternsecurity/bbot/blob/stable/bbot/modules/output/json.py): `bbot/modules/output/json.py`
- [Other destinations](https://github.com/blacklanternsecurity/bbot/tree/stable/bbot/modules/output): `bbot/modules/output`

### Other components

- **Scan user**

## Connections

- Scan user → Command line: runs scan
- Scan user → Scanner API: starts scan
- Command line → Scanner API: launches (evidence: `bbot/cli.py`)
- Scanner API → Preset setup: loads preset (evidence: `bbot/scanner/scanner.py`)
- Preset setup → Preset validation: validates (evidence: `bbot/scanner/preset/preset.py`)
- Scanner API → Scan manager: coordinates (evidence: `bbot/scanner/scanner.py`)
- Scanner API → Event dispatcher: dispatches through (evidence: `bbot/scanner/scanner.py`)
- Scanner API → Scan events: creates events (evidence: `bbot/scanner/scanner.py`)
- Scan manager → Module runtime: inherits from (evidence: `bbot/scanner/manager.py`)
- Preset setup → Module registry: loads modules (evidence: `bbot/scanner/preset/preset.py`)
- Module runtime → Scan events: queues events
- DNS enumeration → DNS discovery: uses resolver
- HTTP crawling → Web helpers: uses web client
- Web fuzzing → Fuzz submodules: uses submodules (evidence: `bbot/modules/lightfuzz/lightfuzz.py`)
- Web fuzzing → Web helpers: tests web targets
- Internal analysis → Scan events: analyzes events
- Scan events → Event model: serializes as (evidence: `bbot/core/event/base.py`)
- Preset setup → Configuration schema: configures scan (evidence: `bbot/scanner/preset/preset.py`)
- Module runtime → Configuration schema: reads module config (evidence: `bbot/modules/base.py`)
- JSON output → Output runtime: extends (evidence: `bbot/modules/output/json.py`)
- JSON output → Scan events: serializes events (evidence: `bbot/modules/output/json.py`)
- Scan events → Other destinations: feeds destinations (evidence: `bbot/core/event/base.py`)
- Scan events → JSON output: streams results (evidence: `bbot/core/event/base.py`)
