blacklanternsecurity · liquidsec · Jul 7, 2026 · Jul 1, 2026 · Jul 1, 2026 · Jul 4, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -81,6 +81,18 @@ ruff format --check  # verify formatting without changes
 
 ---
 
+## AI Use Disclosure
+
+Use of AI is not prohibited -- and in many cases, encouraged. However, when reviewing a PR, it is helpful for the reviewer to know the extent to which AI was used, and which model.
+Please add a small section at the bottom of the PR with the header: `### AI Use Disclosure`, followed by the following information:
+
+* Extent of the AI use. For example, was this fully autonomous by the AI, or was it a collaborative back-and-forth, or did the user just use the AI to review their work, etc.
+* Model Used
+
+This should only apply to external contributors, not members of the blacklanternsecurity organization.
+
+---
+
 ## Architecture Overview
 
 ### How a Scan Works

diff --git a/README.md b/README.md
@@ -202,7 +202,7 @@ flags:
 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 dirbust-light web-screenshots
+bbot -t evilcorp.com -p subdomain-enum cloud-enum code-enum email-enum spider web paramminer webbrute web-screenshots
 ```
 
 <!-- BBOT KITCHEN-SINK PRESET EXPANDABLE -->
@@ -221,7 +221,7 @@ include:
   - spider
   - web
   - paramminer
-  - dirbust-light
+  - webbrute
   - web-screenshots
   - baddns-heavy
 
@@ -393,12 +393,15 @@ For details, see [Configuration](https://www.blacklanternsecurity.com/bbot/Stabl
         - [Tips and Tricks](https://www.blacklanternsecurity.com/bbot/Stable/scanning/tips_and_tricks)
         - [Advanced Usage](https://www.blacklanternsecurity.com/bbot/Stable/scanning/advanced)
         - [Configuration](https://www.blacklanternsecurity.com/bbot/Stable/scanning/configuration)
+        - [Scan Sanity](https://www.blacklanternsecurity.com/bbot/Stable/scanning/scan_sanity)
     - **Modules**
         - [List of Modules](https://www.blacklanternsecurity.com/bbot/Stable/modules/list_of_modules)
+        - [Internal Modules](https://www.blacklanternsecurity.com/bbot/Stable/modules/internal_modules)
         - [Nuclei](https://www.blacklanternsecurity.com/bbot/Stable/modules/nuclei)
         - [Wayback](https://www.blacklanternsecurity.com/bbot/Stable/modules/wayback)
         - [Custom YARA Rules](https://www.blacklanternsecurity.com/bbot/Stable/modules/custom_yara_rules)
         - [Lightfuzz](https://www.blacklanternsecurity.com/bbot/Stable/modules/lightfuzz)
+        - [Webbrute](https://www.blacklanternsecurity.com/bbot/Stable/modules/webbrute)
     - **Migration**
         - [2.x → 3.0 Breaking Changes](https://www.blacklanternsecurity.com/bbot/Stable/migration/3.0_breaking_changes)
     - **Misc**

diff --git a/bbot/presets/kitchen-sink.yml b/bbot/presets/kitchen-sink.yml
@@ -8,7 +8,7 @@ include:
   - spider
   - web
   - paramminer
-  - dirbust-light
+  - webbrute
   - web-screenshots
   - baddns-heavy
 

diff --git a/bbot/presets/nuclei/nuclei-heavy.yml b/bbot/presets/nuclei/nuclei-heavy.yml
@@ -22,7 +22,7 @@ conditions:
     {% endif %}
 
 
-# Example for also running a dirbust
+# Example for also running webbrute
 
 #include:
-#  - dirbust-light
+#  - webbrute
diff --git a/bbot/presets/nuclei/nuclei-technology.yml b/bbot/presets/nuclei/nuclei-technology.yml
@@ -17,7 +17,7 @@ conditions:
       {{ warn("Running nuclei with spider enabled is generally not recommended. Consider removing 'spider' preset.") }}
     {% endif %}
 
-# Example for also running a dirbust
+# Example for also running webbrute
 
 #include:
-#  - dirbust-light
+#  - webbrute
diff --git a/bbot/presets/web/dirbust-heavy.yml → bbot/presets/web/webbrute-heavy.yml b/bbot/presets/web/dirbust-heavy.yml → bbot/presets/web/webbrute-heavy.yml
diff --git a/bbot/presets/web/dirbust-light.yml → bbot/presets/web/webbrute.yml b/bbot/presets/web/dirbust-light.yml → bbot/presets/web/webbrute.yml
diff --git a/bbot/test/test_step_1/test_presets.py b/bbot/test/test_step_1/test_presets.py
@@ -916,7 +916,7 @@ def test_preset_include():
 
     # can't use both include= and presets= at the same time
     with pytest.raises(ValueError):
-        preset = Preset(presets=["subdomain-enum"], include=["dirbust-light"])
+        preset = Preset(presets=["subdomain-enum"], include=["webbrute"])
 
 
 @pytest.mark.asyncio

diff --git a/docs/comparison.md b/docs/comparison.md
@@ -2,7 +2,7 @@
 
 BBOT does a lot more than just subdomain enumeration. However, subdomain enumeration is arguably the most important part of OSINT, and since there's so many subdomain enumeration tools out there, they're the easiest class of tool to compare it to.
 
-Thanks to BBOT's recursive nature (and its `dnsbrute_mutations` module with its NLP-powered subdomain mutations), it typically finds about 20-25% more than other tools such as `Amass` or `theHarvester`. This holds true especially for larger targets like `delta.com` (1000+ subdomains):
+Thanks to BBOT's recursive nature (and its `dnsbrute_mutations` module with its NLP-powered subdomain mutations), it typically finds about 20-50% more than other tools such as `Amass` or `theHarvester`. This holds true especially for larger targets like `delta.com` (1000+ subdomains):
 
 ### Subdomains Found
 

diff --git a/docs/contribution.md b/docs/contribution.md
@@ -31,7 +31,7 @@ Modern AI is an incredibly valuable tool for development. We definitely use it.
 - **No low quality submissions.** If you just submitted the same slop PR to 20 other repos, we are going to close it. If it ignores all the normal patterns in use in BBOT and does its own thing, we are going to close it. If you make a good-faith attempt at doing it right, we're more than happy to help you along.
 - **Don't let the AI edit tests.** Of course, there will be some times where a test edit is legitimately needed, but this is a common antipattern for AI agents. 
 
-We don't require AI disclosure, but it's not discouraged either (usually we can tell though).
+We don't require AI disclosure, but it's welcome (and honestly, we can usually tell). If you'd like to include one, add a short **AI Use Disclosure** at the bottom of your PR: how extensively AI was used (fully autonomous, a collaborative back-and-forth, or an AI review of your own work) and which model.
 
 We provide an [AGENTS.md](https://github.com/blacklanternsecurity/bbot/blob/dev/AGENTS.md) file in the repo root. Feed this to your LLM before working on BBOT. It describes our conventions and should help steer AI-assisted contributions in the right direction.
 

diff --git a/docs/dev/module_howto.md b/docs/dev/module_howto.md
@@ -23,7 +23,7 @@ class whois(BaseModule):
     watched_events = ["DNS_NAME"] # watch for DNS_NAME events
     produced_events = ["DNS_NAME"] # we produce DNS_NAME events
     flags = ["passive", "safe"]
-    meta = {"description": "Query WhoisXMLAPI for related domains"}
+    meta = {"description": "Query WhoisXMLAPI for related domains", "created_date": "2024-01-01", "author": "@you"}
 
     class Config(BaseModuleConfig):
         api_key: str = Field("", description="WhoisXMLAPI Key", sensitive=True, mandatory=True)

diff --git a/docs/migration/3.0_breaking_changes.md b/docs/migration/3.0_breaking_changes.md
@@ -23,6 +23,9 @@ that actually drive passive modules at scan start).
 | `-s / --silent`                 | `-S / --silent` (capitalized; `-s` reassigned to `--seeds`) |
 | `--allow-deadly`                | removed (see flag changes below) |
 
+!!! warning "The `-s` flag changed meaning"
+    In 2.x `-s` was `--silent`; in 3.0 it's `--seeds`, and silent moved to `-S`. A script still passing `-s` for quiet output will now be adding a seed instead, with no error.
+
 Behavior:
 
 - If `--seeds` is omitted, seeds default to whatever was passed to `--targets`,
@@ -56,20 +59,27 @@ also removed.
 
 ## Flags
 
+### Renamed
+
+| 2.x                  | 3.0                |
+|----------------------|--------------------|
+| `web-basic`          | `web`              |
+| `web-thorough`       | `web-heavy`        |
+
+### Removed
+
 | Removed             | Replacement / notes |
 |---------------------|---------------------|
 | `aggressive`        | use `loud` (network volume) and/or `invasive` (destructive) |
 | `deadly`            | dropped along with `--allow-deadly`; affected modules now live under regular flags |
-| `noisy`             | renamed to `loud` |
-| `web-basic`         | renamed to `web` |
-| `web-thorough`      | renamed to `web-heavy` |
+
+### Added
 
 | Added       | Meaning |
 |-------------|---------|
 | `invasive`  | Intrusive or potentially destructive |
 | `safe`      | Non-intrusive and non-destructive (now enforced on every module) |
 | `download`  | Modules that download files, apps, or repositories |
-| `web-heavy` | More advanced web scanning functionality |
 
 Every module must now declare at least one of `passive` / `active` **and** at
 least one of `safe`, `loud`, or `invasive`. Custom modules carrying the removed
@@ -84,22 +94,19 @@ flags will fail validation.
 | 2.x                  | 3.0                |
 |----------------------|--------------------|
 | `web-basic`          | `web`              |
+| `web-thorough`       | `web-heavy`        |
 | `nuclei-intense`     | `nuclei-heavy`     |
 | `spider-intense`     | `spider-heavy`     |
-
-### Removed
-
-- `web-thorough` (use `web-heavy`)
-- `baddns-intense` (the baddns preset tiers were rebuilt; use `baddns` /
-  `baddns-heavy`)
-- `web/lightfuzz-medium`, `web/lightfuzz-superheavy` (lightfuzz preset tiers
-  were rebuilt; see `web/lightfuzz`, `web/lightfuzz-heavy`,
-  `web/lightfuzz-max`)
+| `baddns-intense`     | `baddns-heavy`     |
+| `dirbust-light`      | `webbrute`         |
+| `dirbust-heavy`      | `webbrute-heavy`   |
+| `lightfuzz-medium`   | `lightfuzz`        |
+| `lightfuzz-superheavy` | `lightfuzz-max`  |
 
 ### Added
 
-`baddns`, `baddns-heavy`, `web-heavy`, `web/lightfuzz`, `web/lightfuzz-max`,
-`web/paramminer-heavy`.
+`baddns`, `waf-bypass`, `wayback`, `wayback-heavy`, `web/paramminer-heavy`,
+`web/virtualhost`, `web/virtualhost-heavy`.
 
 ### Syntax
 
@@ -127,14 +134,8 @@ gone too; inject secrets with shell expansion
 
 ### Removed (no direct replacement)
 
-- `azure_realm`
-- `digitorus`
-- `passivetotal`
-- `sitedossier`
 - `smuggler`
-- `wappalyzer`
-- `wpscan` (dropped over a heavy Ruby/compiler install footprint and an
-  unmaintained upstream)
+- `wpscan`
 
 ### Removed and replaced
 
@@ -143,11 +144,9 @@ gone too; inject secrets with shell expansion
 | `httpx`          | `http`          |
 | `ffuf`           | `webbrute`      |
 | `ffuf_shortnames`| `webbrute_shortnames` |
-| `bucket_azure`   | `bucket_microsoft` |
 | `extractous`     | `kreuzberg` |
 | `output.http`    | `output.webhook` |
 | `vhost`          | `virtualhost` (rebuilt; emits the new `VIRTUAL_HOST` event) |
-| `censys` (single module) | split into `censys_dns` and `censys_ip` |
 
 If you used any of these in a custom preset or `-m` / `-em` invocation, update
 the module name accordingly. The `--list-modules` output is the source of
@@ -164,17 +163,23 @@ truth.
       `output.webhook` in 3.0.
 
     Old scans that ran `bbot -om http ...` were emitting events to a webhook;
-    in 3.0 the equivalent is `bbot -om webhook ...`. The new `bbot -m http ...`
-    is a scan module that probes URLs, which is a completely different thing.
+    in 3.0 the equivalent is `bbot -om webhook ...`. By contrast, `bbot -m http
+    ...` enables the scan module, which probes URLs and is unrelated to the
+    former output module.
+
+### Late 2.x removals
+
+These were dropped during the final 2.x releases, so they're already gone if you're on the latest 2.x, but may still surprise you if you're upgrading from an earlier 2.x version:
+
+- `digitorus`, `passivetotal`, `sitedossier`, `wappalyzer` (removed, no replacement)
+- `azure_realm` (functionality merged into `azure_tenant`)
+- `bucket_azure` (now `bucket_microsoft`)
+- `censys` (split into `censys_dns` and `censys_ip`)
 
-### New modules worth knowing about
+### New modules
 
-- `http` -- replaces `httpx`; runs through the in-process [blasthttp](https://github.com/blacklanternsecurity/blasthttp) client.
-- `webbrute` / `webbrute_shortnames` -- ffuf replacements, also via blasthttp.
-- `bucket_hetzner`, `shodan_enterprise`, `trajan`, `legba`.
-- `waf_bypass` -- finds WAF/CDN bypasses by reaching protected content directly via origin IPs (SimHash content matching, with optional ASN-neighbor exploration).
-- Output: `elastic`, `kafka`, `mongo`, `nats`, `rabbitmq`, `zeromq`.
-- Lightfuzz submodules `esi` and `ssrf`.
+- Scan: `bucket_hetzner`, `shodan_enterprise`, `trajan`, `waf_bypass`
+- Output: `elastic`, `kafka`, `mongo`, `nats`, `rabbitmq`, `zeromq`
 
 ### Module API
 
@@ -286,12 +291,6 @@ rest of the scan and the scan continues without it. This is separate from the
 ASN-as-target expansion above, which must abort because there would be nothing
 to scan.
 
-### SCAN event
-
-The `SCAN` event now includes a `network` key containing the scanner's hostname,
-primary outbound IP, network interfaces (IPv4/IPv6 with netmasks), and default
-routes. Useful for correlating scan activity back to a specific agent.
-
 ### JSON output: before and after
 
 If you have downstream tooling that parses BBOT's NDJSON output, the schema
@@ -513,7 +512,8 @@ architecture was deleted.
   Rust client. The `self.helpers.dns.resolver` `dnspython` resolver is gone.
 - **HTTP**: `bbot/core/helpers/web/client.py` and `web/engine.py` were
   removed. `WebHelper` no longer inherits from `EngineClient`. All HTTP goes
-  through the shared `self.helpers.blasthttp` client. The httpx-based
+  through the shared [blasthttp](https://github.com/blacklanternsecurity/blasthttp)
+  client (`self.helpers.blasthttp`). The httpx-based
   `request_batch` / `request_custom_batch` / `curl` methods were replaced by
   `request()`, `request_batch_stream(urls, threads=10, **kwargs)`, and
   `download()`.
@@ -596,10 +596,11 @@ If your downstream tooling relied on seeing `HTTP_RESPONSE` or
 ## Dependencies and tooling
 
 - **Build system**: migrated from Poetry to [uv](https://docs.astral.sh/uv/)
-  + hatchling. `pyproject.toml` is now PEP-621. `poetry.lock` is replaced by
-  `uv.lock`. Dev install: `uv sync --group dev`. The
-  `poetry-dynamic-versioning` integration is gone; version is now plain
-  `3.0.0`.
+  with a hatchling build backend. `pyproject.toml` now follows PEP 621, and
+  `uv.lock` replaces `poetry.lock`; install dev dependencies with
+  `uv sync --group dev`. Versioning is static (`version = "3.0.0"` in
+  `pyproject.toml`) rather than derived from git tags by
+  `poetry-dynamic-versioning`.
 - **License**: changed from `GPL-3.0` to `AGPL-3.0`.
 - **Python**: minimum bumped from `3.9` to `3.10`. Upper bound is now
   `<3.15`.
@@ -614,52 +615,3 @@ If your downstream tooling relied on seeing `HTTP_RESPONSE` or
 
 Custom modules that imported `httpx`, `dns.asyncresolver`, `radixtarget`
 subclasses, or `bbot.db.sql.models` will need to be ported.
-
----
-
-## Quick migration checklist
-
-- [ ] Replace `--whitelist` / `whitelist=` with positional target args; only
-      reach for `--seeds` / `seeds=` when you genuinely want a seed that isn't
-      in scope.
-- [ ] Replace `-s` with `-S` for silent runs.
-- [ ] Drop `--allow-deadly`.
-- [ ] Rename module references: `httpx -> http`, `ffuf -> webbrute`,
-      `bucket_azure -> bucket_microsoft`, `extractous -> kreuzberg`,
-      `output.http -> output.webhook`, `vhost -> virtualhost`,
-      `censys -> censys_dns / censys_ip`. Drop any `wpscan` references (removed,
-      no replacement).
-- [ ] Rename preset references: `web-basic -> web`, `web-thorough -> web-heavy`,
-      `*-intense -> *-heavy`.
-- [ ] Rename module flags: `noisy -> loud`, `web-basic -> web`,
-      `web-thorough -> web-heavy`. Drop `aggressive` / `deadly`. Add `safe` /
-      `loud` / `invasive` to satisfy the new validation rule.
-- [ ] Replace any `VULNERABILITY` emit with a `FINDING` carrying
-      `severity=...`.
-- [ ] Update FINDING severity strings: `INFORMATIONAL -> INFO`,
-      `MODERATE -> MEDIUM`. Add a `confidence` field from the new allowlist.
-- [ ] Stop reading `event.data` for URL events; use `event.url` /
-      `event.pretty_string`. Drop dependencies on `event.confidence` /
-      `cumulative_confidence`.
-- [ ] Stop mutating `event._resolved_hosts` / `event.dns_children` directly;
-      use the new `add_resolved_host` / `add_dns_child` helpers.
-- [ ] Update config keys: `web.httpx_timeout -> web.http_timeout` /
-      `web.http_timeout_infrastructure`,
-      `web.httpx_retries -> web.http_retries`,
-      `web.ssl_verify -> web.ssl_verify_target` / `web.ssl_verify_infrastructure`.
-- [ ] If an in-place upgrade fails with a config validation error pointing at
-      `~/.config/bbot/bbot.yml` or `secrets.yml`, back up your customizations
-      and run `bbot --reset-config` / `bbot --reset-secrets` to regenerate from
-      current defaults.
-- [ ] Update imports: `bbot.db.sql.models -> bbot.models.sql`.
-- [ ] If you ship a custom module that watches URLs but doesn't want
-      blasthttp auto-enabled, set `_disable_auto_module_deps = True`.
-- [ ] Switch your install/build pipeline from Poetry to uv.
-- [ ] If you relied on `-om` to replace default output modules, switch to
-      `-eom` to exclude the ones you don't want (output modules are now
-      purely additive).
-- [ ] Update any JSON parsers that read `event["data"]` for URL events --
-      the key is now `"data_json"` and the value is a dict, not a string.
-      Use `event["data_json"]["url"]` to get the URL string.
-- [ ] If your tooling consumed `HTTP_RESPONSE` or `URL_UNVERIFIED` from
-      output, remove them from `omit_event_types` in your config.
diff --git a/docs/modules/custom_yara_rules.md b/docs/modules/custom_yara_rules.md
@@ -51,7 +51,7 @@ rule find_AAAABBBB_regex {
 
 ```
 
-*Note: YARA uses it's own regex engine that is not a 1:1 match with python regexes. This means many existing regexes will have to be modified before they will work with YARA. The good news is: YARA's regex engine is FAST, immensely more fast than pythons!*
+*Note: YARA uses its own regex engine that is not a 1:1 match with Python regexes. This means many existing regexes will have to be modified before they will work with YARA. The good news is: YARA's regex engine is FAST, immensely faster than Python's!*
 
 Further discussion of art of writing complex YARA rules goes far beyond the scope of this documentation. A good place to start learning more is the [official YARA documentation](https://yara.readthedocs.io/en/stable/writingrules.html).
 
@@ -74,7 +74,7 @@ Example with no description provided:
 Example with the description added:
 
 ```
-[FINDING] {"description": "Custom Yara Rule [AAAABBBB] with description: [contains our test string] Matched via identifier [str1]", "host": "example.com, "url": "http://example.com"}     excavate
+[FINDING] {"description": "Custom Yara Rule [AAAABBBB] with description: [contains our test string] Matched via identifier [str1]", "host": "example.com", "url": "http://example.com"}     excavate
 ```
 
 That FINDING was produced with the following signature:
@@ -143,6 +143,7 @@ rule ContainsTitle
         description = "Contains an HTML title tag"
         severity = "HIGH"
         confidence = "CONFIRMED"
+    strings:
         $title_value = /<title>(.*)?<\/title>/i
     condition:
         $title_value