### Setup BBOT Development Environment

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/AGENTS.md

Commands to clone the repository, install dependencies using uv, and initialize the development environment.

```bash
# 1. Fork and clone
git clone git@github.com:<you>/bbot.git
cd bbot

# 2. Switch to dev branch, then create a feature branch
git checkout dev
git checkout -b my-feature

# 3. Install uv (if you haven't already)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 4. Install all dependencies (including dev)
uv sync --group dev

# 5. Install pre-commit hooks (ruff, file checks, etc.)
uv run pre-commit install

# 6. Activate the virtualenv
source .venv/bin/activate

# 7. Verify
bbot --help
```

--------------------------------

### Implement setup for module initialization

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/AGENTS.md

Handles one-time setup; return values determine if the module succeeds, soft-fails, or hard-fails.

```python
# portscan.py - validates config, checks masscan, checks IPv6 support
async def setup(self):
    self.top_ports = self.config.get("top_ports", 100)
    self.rate = self.config.get("rate", 300)
    self.ports = self.config.get("ports", "")
    if self.ports:
        try:
            self.helpers.parse_port_string(self.ports)
        except ValueError as e:
            return False, f"Error parsing ports '{self.ports}': {e}"
    # ...
    return True
```

```python
# subdomain_enum_apikey template - soft-fail if API key is missing
async def setup(self):
    await super().setup()
    return await self.require_api_key()
    # Returns (None, "No API key set") if missing, disabling the module
```

--------------------------------

### Install BBOT with Python 3.12

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/troubleshooting.md

Use this sequence to install a compatible Python version and BBOT via pipx when standard installation fails.

```bash
# install a newer version of python
sudo apt install python3.12 python3.12-venv
# install pipx
python3.12 -m pip install --user pipx
# add pipx to your path
python3.12 -m pipx ensurepath
# reboot
reboot
# install bbot
python3.12 -m pipx install bbot
# run bbot
bbot --help
```

--------------------------------

### Install BBOT via pipx

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/README.md

Use these commands to install either the stable release or the latest development version of BBOT.

```bash
# stable version
pipx install bbot

# bleeding edge (dev branch)
pipx install --pip-args '--pre' bbot
```

--------------------------------

### Configure module flags

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/AGENTS.md

Examples of setting behavior tags for modules.

```python
# crt.py - queries a third-party API, never touches the target
flags = ["subdomain-enum", "passive"]

# sslcert.py - connects directly to target ports
flags = ["affiliates", "subdomain-enum", "email-enum", "active", "web"]
```

--------------------------------

### Configure module meta

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/AGENTS.md

Examples of defining module metadata and API requirements.

```python
meta = {
    "description": "Query crt.sh (certificate transparency) for subdomains",
    "created_date": "2022-05-13",
    "author": "@TheTechromancer",
}

# For API-key modules:
meta = {"description": "Query API for subdomains", "auth_required": True}
```

--------------------------------

### Custom Preset Configuration

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets.md

Example of a YAML file defining a custom preset configuration.

```yaml
config:
  web:
    spider_distance: 1
```

--------------------------------

### Preset Load Order Examples

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets.md

Demonstrates how the order of presets in the command line affects configuration overrides.

```bash
bbot -t evilcorp.com -p ./my_spider.yml spider
```

```bash
bbot -t evilcorp.com -p spider ./my_spider.yml
```

--------------------------------

### Install BBOT via pipx

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/index.md

Installs BBOT within an isolated virtual environment.

```bash
# stable version
pipx install bbot

# bleeding edge (dev branch)
pipx install --pip-args '--pre' bbot

# execute bbot command
bbot --help
```

--------------------------------

### Common preset usage patterns

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets.md

Examples of using presets with targets, multiple presets, flags, and configuration overrides.

```bash
# do a subdomain enumeration
bbot -t evilcorp.com -p subdomain-enum

# multiple presets - subdomain enumeration + web spider
bbot -t evilcorp.com -p subdomain-enum spider

# start with a preset but only enable modules that have the 'passive' flag
bbot -t evilcorp.com -p subdomain-enum -rf passive

# preset + manual config override
bbot -t www.evilcorp.com -p spider -c web.spider_distance=10
```

--------------------------------

### Example JSON Event Structure

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/output.md

Shows the structure of a standard IP_ADDRESS event.

```json
{
  "type": "IP_ADDRESS",
  "id": "IP_ADDRESS:13cd09c2adf0860a582240229cd7ad1dccdb5eb1",
  "data": "1.2.3.4",
  "scope_distance": 1,
  "scan": "SCAN:64c0e076516ae7aa6502fd99489693d0d5ec26cc",
  "timestamp": 1688518967.740472,
  "resolved_hosts": ["1.2.3.4"],
  "parent": "DNS_NAME:2da045542abbf86723f22383d04eb453e573723c",
  "tags": ["distance-1", "ipv4", "internal"],
  "module": "A",
  "module_sequence": "A"
}
```

--------------------------------

### Configure Elasticsearch Output

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/output.md

Setup steps and configuration for sending scan results to Elasticsearch.

```bash
docker run -d -p 9200:9200 --name=bbot-elastic --v "$(pwd)/elastic_data:/usr/share/elasticsearch/data" -e ELASTIC_PASSWORD=bbotislife -m 1GB docker.elastic.co/elasticsearch/elasticsearch:8.16.0
```

```bash
# send scan results directly to elasticsearch
# note: you can replace "bbot" with your own index name
bbot -t evilcorp.com -om elastic -c \
  modules.elastic.url=https://localhost:9200/bbot/_doc \
  modules.elastic.password=bbotislife
```

```yaml
output_modules:
  - elastic

config:
  modules:
    elastic:
      url: http://localhost:9200/bbot/_doc
      password: bbotislife
```

--------------------------------

### Configure Discord Webhook

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/output.md

Examples for configuring Discord webhooks via YAML presets or command line arguments.

```yaml
output_modules:
  - discord

config:
  modules:
    discord:
      webhook_url: https://discord.com/api/webhooks/1234/deadbeef
```

```bash
bbot -t evilcorp.com -om discord -c modules.discord.webhook_url=https://discord.com/api/webhooks/1234/deadbeef
```

```yaml
output_modules:
  - discord

config:
  modules:
    discord:
      webhook_url: https://discord.com/api/webhooks/1234/deadbeef
      event_types:
        - FINDING
        - STORAGE_BUCKET
```

```bash
bbot -t evilcorp.com -om discord -c modules.discord.webhook_url=https://discord.com/api/webhooks/1234/deadbeef -c modules.discord.event_types=["STORAGE_BUCKET","FINDING"]
```

```yaml
output_modules:
  - discord

config:
  modules:
    discord:
      webhook_url: https://discord.com/api/webhooks/1234/deadbeef
      min_severity: HIGH
```

--------------------------------

### Run BBOT with custom YARA rules

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/modules/custom_yara_rules.md

Command line example for executing BBOT with a custom YARA rule file.

```bash
bbot -m http --custom-yara-rules=substack.yara -t http://www.blacklanternsecurity.com/
```

--------------------------------

### YARA rule finding output examples

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/modules/custom_yara_rules.md

Examples of BBOT finding output showing the effect of including or omitting a description meta attribute.

```text
[FINDING] {"description": "Custom Yara Rule [find_string] Matched via identifier [str1]", "host": "example.com", "url": "http://example.com"} excavate
```

```text
[FINDING] {"description": "Custom Yara Rule [AAAABBBB] with description: [contains our test string] Matched via identifier [str1]", "host": "example.com", "url": "http://example.com"}     excavate
```

--------------------------------

### Configure produced_events

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/AGENTS.md

Examples of defining which event types a module may emit.

```python
# sslcert.py - can discover hostnames and emails from certificates
produced_events = ["DNS_NAME", "EMAIL_ADDRESS"]

# portscan.py - finds open ports
produced_events = ["OPEN_TCP_PORT"]
```

--------------------------------

### BBOT Scanning Command Examples

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/advanced.md

Common command-line patterns for executing various scan types and listing available modules or presets.

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

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

```bash
bbot -t evilcorp.com -p subdomain-enum -m portscan gowitness -n my_scan -o .
```

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

```bash
bbot -t www.evilcorp.com -p spider -c web.spider_distance=2 web.spider_depth=2
```

```bash
bbot -t evilcorp.com -p kitchen-sink
```

```bash
bbot -l
```

```bash
bbot -lo
```

```bash
bbot -lp
```

```bash
bbot -lf
```

```bash
bbot -mh <module_name>
```

--------------------------------

### DNS Wildcard Detection Output

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/index.md

Example output showing how BBOT tags wildcard domains and collapses them into a single host.

```text
[DNS_NAME]      github.io   TARGET  (a-record, a-wildcard-domain, aaaa-wildcard-domain, wildcard-domain)
                                               ^^^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^^^
```

```text
[DNS_NAME]      _wildcard.github.io     TARGET  (a-record, a-wildcard, a-wildcard-domain, aaaa-record, aaaa-wildcard, aaaa-wildcard-domain, wildcard, wildcard-domain)
                ^^^^^^^^^
```

--------------------------------

### Configure watched_events

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/AGENTS.md

Examples of defining which event types a module processes.

```python
# sslcert.py - watches for open ports to grab SSL certs from
watched_events = ["OPEN_TCP_PORT"]

# newsletters.py - watches HTTP responses to scan HTML
watched_events = ["HTTP_RESPONSE"]

# json.py (output module) - watches everything
watched_events = ["*"]
```

--------------------------------

### Test a BBOT module

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/AGENTS.md

Example test class using ModuleTestBase to verify module output.

```python
from .base import ModuleTestBase


class TestMyModule(ModuleTestBase):
    async def setup_after_prep(self, module_test):
        module_test.blasthttp_mock.add_response(
            url="https://api.example.com/lookup?domain=blacklanternsecurity.com",
            json={"emails": ["info@blacklanternsecurity.com"]},
        )

    def check(self, module_test, events):
        assert any(
            e.data == "info@blacklanternsecurity.com" and e.type == "EMAIL_ADDRESS"
            for e in events
        ), "Failed to find email"
```

--------------------------------

### Common BBOT Scan Commands

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/index.md

Examples of various scan configurations ranging from subdomain enumeration to full-scale reconnaissance.

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

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

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

```bash
# A basic web scan includes robots.txt, storage buckets, IIS shortnames, and other non-intrusive web modules
bbot -t evilcorp.com -p subdomain-enum web
```

```bash
# 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
```

```bash
# Subdomains, emails, cloud buckets, port scan, basic web, web screenshots, nuclei
bbot -t evilcorp.com -p kitchen-sink
```

--------------------------------

### Subdomains output format

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/output.md

Example content of the text file generated by the subdomains output module.

```text
evilcorp.com
www.evilcorp.com
mail.evilcorp.com
portal.evilcorp.com
```

--------------------------------

### Configure Engine and Dependencies

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/configuration.md

Sets engine debug mode and defines how module dependencies are handled during installation.

```yaml
### ENGINE ###

engine:
  debug: false

# Tool dependencies
deps:
  # How to handle installation of module dependencies
  # Choices are:
  #  - abort_on_failure (default) - if a module dependency fails to install, abort the scan
  #  - retry_failed - try again to install failed dependencies
  #  - ignore_failed - run the scan regardless of what happens with dependency installation
  #  - disable - completely disable BBOT's dependency system (you are responsible for installing tools, pip packages, etc.)
  behavior: abort_on_failure
```

--------------------------------

### BBOT Command-Line Help Reference

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/advanced.md

View the full list of available command-line arguments, flags, and module configurations.

```text
usage: bbot [-h] [-t TARGET [TARGET ...]] [-s SEEDS [SEEDS ...]]
               [-b BLACKLIST [BLACKLIST ...]] [--strict-scope]
               [-p [PRESET ...]] [-c [CONFIG ...]] [-lp]
               [-m MODULE [MODULE ...]] [-l] [-lmo] [-em MODULE [MODULE ...]]
               [-f FLAG [FLAG ...]] [-lf] [-rf FLAG [FLAG ...]]
               [-ef FLAG [FLAG ...]] [-n SCAN_NAME] [-v] [-d] [-S] [--force]
               [-y] [--fast-mode] [--dry-run] [--current-preset]
               [--current-preset-full] [-mh MODULE] [-o DIR]
               [-om MODULE [MODULE ...]] [-eom MODULE [MODULE ...]] [-lo]
               [--json] [--brief] [--no-color]
               [--event-types EVENT_TYPES [EVENT_TYPES ...]] [--exclude-cdn]
               [--no-deps | --force-deps | --retry-deps |
               --ignore-failed-deps] [--install-all-deps] [--version]
               [--reset-config] [--reset-secrets] [--proxy HTTP_PROXY]
               [--no-proxy HOST [HOST ...]]
               [-H CUSTOM_HEADERS [CUSTOM_HEADERS ...]]
               [-C CUSTOM_COOKIES [CUSTOM_COOKIES ...]]
               [--custom-yara-rules CUSTOM_YARA_RULES]
               [--user-agent USER_AGENT] [--user-agent-suffix SUFFIX]

Bighuge BLS OSINT Tool

options:
  -h, --help            show this help message and exit

Target:
  -t, --targets TARGET [TARGET ...]
                        Target scope
  -s, --seeds SEEDS [SEEDS ...]
                        Define seeds to drive passive modules without being in scope (if not specified, defaults to same as targets)
  -b, --blacklist BLACKLIST [BLACKLIST ...]
                        Don't touch these things
  --strict-scope        Don't consider subdomains of target to be in-scope - exact matches only

Presets:
  -p, --preset [PRESET ...]
                        Enable BBOT preset(s)
  -c, --config [CONFIG ...]
                        Custom config options in key=value format: e.g. 'modules.shodan.api_key=1234'
  -lp, --list-presets   List available presets.

Modules:
  -m, --modules MODULE [MODULE ...]
                        Modules to enable. Choices: affiliates,ajaxpro,anubisdb,apkpure,asn,aspnet_bin_exposure,azure_tenant,baddns,baddns_direct,baddns_zone,badsecrets,bevigil,bucket_amazon,bucket_digitalocean,bucket_file_enum,bucket_firebase,bucket_google,bucket_hetzner,bucket_microsoft,bufferoverrun,builtwith,bypass403,c99,censys_dns,censys_ip,certspotter,chaos,code_repository,credshed,crt,crt_db,dehashed,dnsbimi,dnsbrute,dnsbrute_mutations,dnscaa,dnscommonsrv,dnsdumpster,dnstlsrpt,docker_pull,dockerhub,dotnetnuke,emailformat,filedownload,fingerprintx,fullhunt,generic_ssrf,git,git_clone,gitdumper,github_codesearch,github_org,github_usersearch,github_workflows,gitlab_com,gitlab_onprem,google_playstore,gowitness,graphql_introspection,hackertarget,host_header,http,hunt,hunterio,iis_shortnames,ip2location,ipneighbor,ipstack,jadx,kreuzberg,leakix,legba,lightfuzz,medusa,myssl,newsletters,ntlm,nuclei,oauth,otx,paramminer_cookies,paramminer_getparams,paramminer_headers,pgp,portfilter,portscan,postman,postman_download,rapiddns,reflected_parameters,retirejs,robots,securitytrails,securitytxt,shodan_dns,shodan_enterprise,shodan_idb,skymem,social,sslcert,subdomaincenter,subdomainradar,telerik,trajan,trickest,trufflehog,url_manipulation,urlscan,viewdns,virtualhost,virustotal,waf_bypass,wafw00f,wayback,webbrute,webbrute_shortnames
  -l, --list-modules    List available modules.
  -lmo, --list-module-options
                        Show all module config options
  -em, --exclude-modules MODULE [MODULE ...]
                        Exclude these modules.
  -f, --flags FLAG [FLAG ...]
                        Enable modules by flag. Choices: active,affiliates,baddns,cloud-enum,code-enum,download,email-enum,iis-shortnames,invasive,loud,passive,portscan,safe,service-enum,slow,social-enum,subdomain-enum,subdomain-hijack,web,web-heavy,web-paramminer,web-screenshots
  -lf, --list-flags     List available flags.
  -rf, --require-flags FLAG [FLAG ...]
                        Only enable modules with these flags (e.g. -rf passive)
  -ef, --exclude-flags FLAG [FLAG ...]
                        Disable modules with these flags. (e.g. -ef loud)
```

--------------------------------

### List available presets

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets.md

Display all built-in presets available for use.

```bash
# list available presets
bbot -lp
```

--------------------------------

### Run webbrute via CLI

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/modules/webbrute.md

Execute basic directory brute-forcing, specify file extensions, or use pre-configured aggressive profiles.

```bash
# Basic directory brute-force
bbot -t example.com -m webbrute

# With file extensions
bbot -t example.com -m webbrute -c modules.webbrute.extensions=php,asp,jsp

# Aggressive mode with larger wordlist and recursion
bbot -t example.com -p webbrute-heavy
```

--------------------------------

### Run wayback preset

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/modules/wayback.md

Executes the basic URL discovery mode which includes subdomain enumeration.

```bash
bbot -p wayback -t evilcorp.com
```

--------------------------------

### Load Targets from File and Command Line

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/index.md

Targets can be provided as a list in a text file or passed directly as arguments.

```bash
$ cat targets.txt
4.3.2.1
10.0.0.2:80
1.2.3.0/24
evilcorp.com
evilcorp.co.uk
https://www.evilcorp.co.uk

# load targets from a file and from the command-line
$ bbot -t targets.txt fsociety.com 5.6.7.0/24 -m portscan
```

--------------------------------

### Preset Validation Error

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets.md

Example of the error message displayed when a preset contains an invalid key.

```text
$ bbot -p ./mypreset.yml
ERROR  [preset:modlues] Could not find preset option "modlues". Did you mean "modules"?
```

--------------------------------

### Run Neo4j with BBOT

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/output.md

Commands to initialize a Neo4j instance via Docker and execute a BBOT scan using the Neo4j output module.

```bash
# start Neo4j in the background with docker
docker run -d -p 7687:7687 -p 7474:7474 -v "$(pwd)/neo4j/:/data/" -e NEO4J_AUTH=neo4j/bbotislife neo4j
```

```bash
bbot -f subdomain-enum -t evilcorp.com -om neo4j
```

--------------------------------

### Validate API Keys

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/AGENTS.md

Call require_api_key within the setup method to ensure necessary credentials are configured.

```python
async def setup(self):
    return await self.require_api_key()
```

--------------------------------

### Typical BBOT Event JSON Structure

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/events.md

Example of a DNS_NAME event object as it appears in the scan output.

```json
{
  "type": "DNS_NAME",
  "id": "DNS_NAME:33bc005c2bdfea4d73e07db733bd11861cf6520e",
  "uuid": "DNS_NAME:6c96d512-090a-47f0-82e4-6860e46aac13",
  "scope_description": "in-scope",
  "netloc": "link.evilcorp.com",
  "data": "link.evilcorp.com",
  "host": "link.evilcorp.com",
  "resolved_hosts": [
    "184.31.52.65",
    "2600:1402:b800:d82::700",
    "2600:1402:b800:d87::700",
    "link.evilcorp.com.edgekey.net"
  ],
  "dns_children": {
    "A": [
      "184.31.52.65"
    ],
    "AAAA": [
      "2600:1402:b800:d82::700",
      "2600:1402:b800:d87::700"
    ],
    "CNAME": [
      "link.evilcorp.com.edgekey.net"
    ]
  },
  "web_spider_distance": 0,
  "scope_distance": 0,
  "scan": "SCAN:b6ef48bc036bc8d001595ae5061846a7e6beadb6",
  "timestamp": 1729266013.71688,
  "parent": "DNS_NAME:94c92b7eaed431b37ae2a757fec4e678cc3bd213",
  "parent_uuid": "DNS_NAME:c737dffa-d4f0-4b6e-a72d-cc8c05bd892e",
  "tags": [
    "a-record",
    "aaaa-record",
    "cdn-akamai",
    "cname-record",
    "in-scope",
    "subdomain"
  ],
  "module": "speculate",
  "module_sequence": "speculate->speculate",
  "discovery_context": "speculated parent DNS_NAME: link.evilcorp.com",
  "discovery_path": [
    "Scan insidious_frederick seeded with DNS_NAME: evilcorp.com",
    "TXT record for evilcorp.com contains IP_ADDRESS: 149.72.247.52",
    "PTR record for 149.72.247.52 contains DNS_NAME: o1.ptr2410.link.evilcorp.com",
    "speculated parent DNS_NAME: ptr2410.link.evilcorp.com",
    "speculated parent DNS_NAME: link.evilcorp.com"
  ],
  "parent_chain": [
    "DNS_NAME:34c657a3-0bfa-457e-9e6e-0f22f04b8da5",
    "IP_ADDRESS:efc0fb3b-1b42-44da-916e-83db2360e10e",
    "DNS_NAME:c737dffa-d4f0-4b6e-a72d-cc8c05bd892e",
    "DNS_NAME_UNRESOLVED:722a3473-30c6-40f1-90aa-908d47105d5a",
    "DNS_NAME:6c96d512-090a-47f0-82e4-6860e46aac13"
  ]
}
```

--------------------------------

### Run webbrute preset

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/modules/webbrute.md

Executes a surface-level directory discovery scan using the webbrute preset.

```bash
bbot -t example.com -p webbrute
```

--------------------------------

### Define Ansible dependencies

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/AGENTS.md

Uses Ansible tasks for complex installation requirements like downloading and unarchiving binaries.

```python
# fingerprintx.py - downloads a Go binary
deps_ansible = [
    {
        "name": "Download fingerprintx",
        "unarchive": {
            "src": "https://github.com/.../fingerprintx_{version}_{platform}_{arch}.tar.gz",
            "include": "fingerprintx",
            "dest": "#{BBOT_TOOLS}",
            "remote_src": True,
        },
    },
]
```

--------------------------------

### Configure webbrute extensions

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/modules/webbrute.md

Define file extensions to test against paths in the configuration file.

```yaml
modules:
  webbrute:
    extensions:
      - php
      - asp
      - aspx
      - jsp
```

--------------------------------

### Enable HTTP method switching

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/modules/lightfuzz.md

Configure the module to test parameters across different HTTP methods by enabling try_post_as_get and try_get_as_post.

```bash
bbot -p lightfuzz -t targets.txt -c modules.lightfuzz.try_post_as_get=true modules.lightfuzz.try_get_as_post=true
```

--------------------------------

### Virtual Host Discovery Preset

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets_list.md

Basic configuration for subdomain brute-force and Host header/SNI mutations.

```yaml
description: "Virtual host discovery: subdomain brute-force and mutations against the target host's Host header / SNI."

modules:
  - virtualhost
```

--------------------------------

### Run Kitchen Sink Scan

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/README.md

Execute all available modules at once.

```bash
# 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
```

--------------------------------

### YARA rule finding output with extracted match

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/modules/custom_yara_rules.md

Example of a BBOT finding output that includes the extracted regex match.

```text
[FINDING] {"description": "Custom Yara Rule [ContainsTitle] with description: [Contains an HTML title] Matched via identifier [title_value] and extracted [<title>Black Lantern Security</title>]", "host": "www.blacklanternsecurity.com", "url": "https://www.blacklanternsecurity.com/"}	excavate	(cdn-github, cdn-ip)
```

--------------------------------

### Configure Kafka output

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/output.md

Sets up the Kafka output module with bootstrap servers and topic.

```yaml
output_modules:
  - kafka

config:
  modules:
    kafka:
      bootstrap_servers: localhost:9092
      topic: bbot_events
```

--------------------------------

### YARA rule output with tags

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/modules/custom_yara_rules.md

Example of a BBOT finding output containing the custom tags defined in the YARA rule.

```text
[FINDING] {"description": "Custom Yara Rule [AAAABBBB] with description: [contains our test string] Matched via identifier [str1]", "host": "example.com", "url": "http://example.com/"} excavate   (tag1, tag2, tag3)
```

--------------------------------

### Separate Targets and Seeds

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/index.md

Use targets to define active scan scope and seeds to provide discovery starting points.

```bash
bbot -t 192.168.1.0/24 -s evilcorp.com -f subdomain-enum -m nuclei
```

--------------------------------

### Configure lightfuzz-light preset

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets_list.md

Minimal fuzzing configuration focusing on path traversal, SQLi, and XSS without POST requests.

```yaml
description: "Minimal fuzzing: only path traversal, SQLi, and XSS submodules. No POST requests. No companion modules. Safest option for running alongside larger scans with minimal overhead."

modules:
  - http
  - lightfuzz
  - portfilter
  
config:
  url_querystring_remove: False # don't strip off the querystring (BBOT normally does this; but lightfuzz needs it)
  url_querystring_collapse: True # in cases where the same parameter has multiple values, collapse them into a single parameter to save on fuzzing attempts
  modules:
    lightfuzz:
      enabled_submodules: [path,sqli,xss] # only look for the most common vulnerabilities
      disable_post: True # don't send POST requests (less aggressive)
      avoid_wafs: True

conditions:
- |
  {% if config.web.spider_distance == 0 %}
    {{ warn("Lightfuzz works much better with spider enabled! Consider adding 'spider' or 'spider-heavy' preset.") }}
  {% endif %}
```

--------------------------------

### Managing Output Modules via CLI

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/migration/3.0_breaking_changes.md

Demonstrates how to use the additive -om flag and the new -eom flag to control output modules in BBOT 3.0.

```bash
# defaults (csv, txt, json, stdout) are all enabled
bbot -t evilcorp.com -p subdomain-enum

# neo4j is added alongside all defaults
bbot -t evilcorp.com -p subdomain-enum -om neo4j

# json only -- explicitly exclude the other defaults
bbot -t evilcorp.com -p subdomain-enum -eom csv txt stdout
```

--------------------------------

### Execute Nuclei scans with BBOT

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/modules/nuclei.md

Examples of running Nuclei scans against single or multiple targets using different BBOT configurations.

```bash
# Scan a SINGLE target with a basic port scan and web modules
bbot -f web -m portscan nuclei -t app.evilcorp.com
```

```bash
# Scanning MULTIPLE targets
bbot -f web -m portscan nuclei -t app1.evilcorp.com app2.evilcorp.com app3.evilcorp.com
```

```bash
# Scanning MULTIPLE targets while performing subdomain enumeration
bbot -f subdomain-enum web -m portscan nuclei -t app1.evilcorp.com app2.evilcorp.com app3.evilcorp.com
```

```bash
# Scanning MULTIPLE targets on a BUDGET
bbot -f subdomain-enum web -m portscan nuclei -c modules.nuclei.mode=budget -t app1.evilcorp.com app2.evilcorp.com app3.evilcorp.com
```

--------------------------------

### Create a custom preset

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets.md

A complex YAML configuration that includes other presets, enables additional modules, and sets configuration options.

```yaml
description: Do a subdomain enumeration + basic web scan + nuclei

target:
  - evilcorp.com

include:
  # include these default presets
  - subdomain-enum
  - web

modules:
  # enable nuclei in addition to the other modules
  - nuclei

config:
  # global config options
  web:
    http_proxy: http://127.0.0.1:8080
  # module config options
  modules:
    # api keys
    securitytrails:
      api_key: 21a270d5f59c9b05813a72bb41707266
    virustotal:
      # multiple API keys are allowed
      api_key:
        - 4f41243847da693a4f356c0486114bc6
        - 5bc6ed268ab6488270e496d3183a1a27
```

--------------------------------

### Run wayback-heavy preset

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/modules/wayback.md

Executes the full-featured mode including parameter extraction and secret scanning in archived content.

```bash
bbot -p wayback-heavy -t evilcorp.com
```

--------------------------------

### Execute a custom preset

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets.md

Run a scan using a custom-defined YAML preset file.

```bash
bbot -p ./my_subdomains.yml
```

--------------------------------

### Configure ZeroMQ output

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/output.md

Sets up the ZeroMQ output module with a PUB socket address.

```yaml
output_modules:
  - zeromq

config:
  modules:
    zeromq:
      zmq_address: tcp://localhost:5555
```

--------------------------------

### Define Module Options

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/AGENTS.md

Configure user-defined settings for modules using dictionaries and access them via self.config.get().

```python
# robots.py - configurable parsing options
options = {"include_sitemap": False, "include_allow": True, "include_disallow": True}
options_desc = {
    "include_sitemap": "Include 'sitemap' entries",
    "include_allow": "Include 'Allow' Entries",
    "include_disallow": "Include 'Disallow' Entries",
}

# In handle_event():
if self.config.get("include_sitemap") is True:
    ...
```

```python
# sslcert.py - timeout and behavior options
options = {"timeout": 5.0, "skip_non_ssl": True}
options_desc = {"timeout": "Socket connect timeout in seconds", "skip_non_ssl": "Don't try common non-SSL ports"}
```

--------------------------------

### Execute a BBOT preset

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets.md

Run a scan using a specific preset file path.

```bash
bbot -p ./my_preset.yml
```

--------------------------------

### Web Scanner Configurations

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/README.md

YAML configurations for standard and aggressive web scanning presets.

```yaml
description: Quick web scan

include:
  - iis-shortnames

flags:
  - web
```

```yaml
description: Aggressive web scan

include:
  # include the web preset
  - web

flags:
  - web-heavy
```

--------------------------------

### Run subdomain-enum preset

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/modules/wayback.md

Performs basic subdomain enumeration without URL emission.

```bash
# Basic subdomain enumeration (default behavior, no URL emission)
bbot -p subdomain-enum -t evilcorp.com
```

--------------------------------

### Configure WebSocket output

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/output.md

Sets up the WebSocket output module with URL and optional authorization token.

```yaml
output_modules:
  - websocket

config:
  modules:
    websocket:
      url: ws://localhost:8080
      token: my-auth-token
```

--------------------------------

### Configure Lightfuzz Preset

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets_list.md

Sets up default fuzzing parameters including specific submodules and POST-to-GET parameter testing.

```yaml
description: "Default fuzzing: all 9 submodules (cmdi, crypto, path, serial, sqli, ssti, xss, esi, ssrf) plus companion modules (badsecrets, hunt, reflected_parameters). POST fuzzing disabled but try_post_as_get enabled, so POST params are retested as GET. Skips confirmed WAFs."

include:
  - lightfuzz-light

modules:
  - badsecrets
  - hunt
  - reflected_parameters
  
config:
  modules:
    lightfuzz:
      enabled_submodules: [cmdi,crypto,path,serial,sqli,ssti,xss,esi,ssrf]
      try_post_as_get: True
```

--------------------------------

### Configure SQLite output path

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/output.md

Use the -om flag to specify the sqlite module and -c to override the default database file location.

```bash
# specifying a custom database path
bbot -t evilcorp.com -om sqlite -c modules.sqlite.database=/tmp/bbot.sqlite
```

--------------------------------

### Kitchen Sink Configuration

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/README.md

YAML configuration for the kitchen-sink preset, including all modules and specific configuration overrides.

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

--------------------------------

### Configure custom module directories

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets.md

Add parent folders to module_dirs to load custom BBOT modules from non-standard locations.

```yaml
# load extra BBOT modules from this location
module_dirs:
  - /home/user/custom_modules
```

--------------------------------

### Define file-based targets in a preset

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets.md

Use file paths in target, seed, or blacklist fields to have BBOT expand file contents as individual entries.

```yaml
target:
  - targets.txt
  - extra.evilcorp.com

seeds:
  - seeds.txt

blacklist:
  - /home/user/blacklist.txt
```

--------------------------------

### Configure MySQL output module

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/output.md

Specify the database name via command line or use a YAML configuration file for full connection details.

```bash
# specifying an alternate database
bbot -t evilcorp.com -om mysql -c modules.mysql.database=custom_bbot_db
```

```yaml
output_modules:
  - mysql

config:
  modules:
    mysql:
      host: mysql.fsociety.local
      database: custom_bbot_db
      port: 3306
      username: root
      password: bbotislife
```

--------------------------------

### Configure lightfuzz-heavy preset

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/presets_list.md

Aggressive fuzzing configuration including paramminer, POST request fuzzing, and robots.txt parsing.

```yaml
description: "Aggressive fuzzing: everything in lightfuzz, plus paramminer brute-force parameter discovery (headers, GET params, cookies), POST request fuzzing enabled, try_get_as_post enabled (GET params retested as POST), and robots.txt parsing. Still skips confirmed WAFs."

include:
  - lightfuzz

flags:
  - web-paramminer

modules:
  - robots
  - wayback

config:
  modules:
    lightfuzz:
      enabled_submodules: [cmdi,crypto,path,serial,sqli,ssti,xss,esi,ssrf]
      disable_post: False
      try_post_as_get: True
      try_get_as_post: True
    wayback:
      urls: True
      parameters: True
```

--------------------------------

### Configure RabbitMQ output

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/output.md

Sets up the RabbitMQ output module with connection URL and queue name.

```yaml
output_modules:
  - rabbitmq

config:
  modules:
    rabbitmq:
      url: amqp://guest:guest@localhost/
      queue: bbot_events
```

--------------------------------

### Configure Output Modules via YAML

Source: https://github.com/blacklanternsecurity/bbot/blob/stable/docs/scanning/output.md

Define output module preferences within a preset YAML file.

```yaml
output_modules:
  - discord  # added on top of defaults

exclude_output_modules:
  - csv  # remove csv from defaults
```