blacklanternsecurity · liquidsec · Jun 30, 2026 · May 22, 2026 · May 22, 2026 · Jun 3, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -76,8 +76,8 @@ ruff format --check  # verify formatting without changes
 ### Git Workflow
 
 - `stable` - production releases
-- `dev` - active development, PR target
-- Feature branches are created from `dev`
+- `dev` - active development, **almost all PRs should target this branch**
+- Feature branches should be created from `dev`
 
 ---
 
@@ -121,7 +121,7 @@ BBOT is an async, recursive OSINT tool. A scan starts with **seed events** (targ
 
 Events are the currency of BBOT. Every piece of data -- a hostname, IP, URL, open port, finding -- is an event. Events have:
 
-- **type**: `DNS_NAME`, `IP_ADDRESS`, `URL`, `OPEN_TCP_PORT`, `HTTP_RESPONSE`, `FINDING`, `VULNERABILITY`, `EMAIL_ADDRESS`, etc.
+- **type**: `DNS_NAME`, `IP_ADDRESS`, `URL`, `OPEN_TCP_PORT`, `HTTP_RESPONSE`, `FINDING`, `EMAIL_ADDRESS`, etc.
 - **data**: the actual data (a string, dict, etc.)
 - **parent**: the event that led to this one (forming a discovery chain)
 - **scope_distance**: how many hops from the original target (0 = in-scope)

diff --git a/CONTRIBUTIONS.md b/CONTRIBUTIONS.md
@@ -0,0 +1,5 @@
+# Contributing to BBOT
+
+See our full contribution guide at:
+
+**https://www.blacklanternsecurity.com/bbot/Stable/contribution/**
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 [![bbot_banner](https://github.com/user-attachments/assets/f02804ce-9478-4f1e-ac4d-9cf5620a3214)](https://github.com/blacklanternsecurity/bbot)
 
-[![Python Version](https://img.shields.io/badge/python-3.10+-FF8400)](https://www.python.org) [![License](https://img.shields.io/badge/license-AGPLv3-FF8400.svg)](https://github.com/blacklanternsecurity/bbot/blob/dev/LICENSE) [![DEF CON Recon Village 2024](https://img.shields.io/badge/DEF%20CON%20Demo%20Labs-2023-FF8400.svg)](https://www.reconvillage.org/talks) [![PyPi Downloads](https://static.pepy.tech/personalized-badge/bbot?right_color=orange&left_color=grey)](https://pepy.tech/project/bbot) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![Tests](https://github.com/blacklanternsecurity/bbot/actions/workflows/tests.yml/badge.svg?branch=stable)](https://github.com/blacklanternsecurity/bbot/actions?query=workflow%3A"tests") [![Codecov](https://codecov.io/gh/blacklanternsecurity/bbot/branch/dev/graph/badge.svg?token=IR5AZBDM5K)](https://codecov.io/gh/blacklanternsecurity/bbot) [![Discord](https://img.shields.io/discord/859164869970362439)](https://discord.com/invite/PZqkgxu5SA)
+[![Python Version](https://img.shields.io/badge/python-3.10+-FF8400)](https://www.python.org) [![License](https://img.shields.io/badge/license-AGPLv3-FF8400.svg)](https://github.com/blacklanternsecurity/bbot/blob/dev/LICENSE) [![PyPi Downloads](https://static.pepy.tech/personalized-badge/bbot?right_color=orange&left_color=grey)](https://pepy.tech/project/bbot) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![Tests](https://github.com/blacklanternsecurity/bbot/actions/workflows/tests.yml/badge.svg?branch=stable)](https://github.com/blacklanternsecurity/bbot/actions?query=workflow%3A"tests") [![Codecov](https://codecov.io/gh/blacklanternsecurity/bbot/branch/dev/graph/badge.svg?token=IR5AZBDM5K)](https://codecov.io/gh/blacklanternsecurity/bbot) [![Discord](https://img.shields.io/discord/859164869970362439)](https://discord.com/invite/PZqkgxu5SA)
 
 ### **BEE·bot** is a multipurpose scanner inspired by [Spiderfoot](https://github.com/smicallef/spiderfoot), built to automate your **Recon**, **Bug Bounties**, and **ASM**!
 
@@ -20,7 +20,9 @@ pipx install --pip-args '\--pre' bbot
 
 _For more installation methods, including [Docker](https://hub.docker.com/r/blacklanternsecurity/bbot), see [Getting Started](https://www.blacklanternsecurity.com/bbot/Stable/)_
 
-> **Speed tip:** BBOT's DNS engine spins up ten workers per resolver in `/etc/resolv.conf`. Adding more unfiltered resolvers dramatically speeds up scans. See the [sample resolv.conf](docs/data/resolv-sample.conf) and [Tips and Tricks](https://www.blacklanternsecurity.com/bbot/Stable/scanning/tips_and_tricks/#speed-up-scans-with-more-dns-resolvers) for details.
+> **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](https://www.blacklanternsecurity.com/bbot/Stable/migration/3.0_breaking_changes/) ([source](docs/migration/3.0_breaking_changes.md)) before upgrading.
+
+> **Speed tip:** BBOT's DNS resolver ([blastdns](https://github.com/blacklanternsecurity/blastdns)) spins up multiple threads per resolver in `/etc/resolv.conf`. Adding more unfiltered resolvers dramatically speeds up scans. See the [sample resolv.conf](docs/data/resolv-sample.conf) and [Tips and Tricks](https://www.blacklanternsecurity.com/bbot/Stable/scanning/tips_and_tricks/#speed-up-scans-with-more-dns-resolvers) for details.
 
 ## Example Commands
 
@@ -71,7 +73,7 @@ config:
 
 <!-- END BBOT SUBDOMAIN-ENUM PRESET EXPANDABLE -->
 
-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](https://www.blacklanternsecurity.com/bbot/Dev/how_it_works/).
+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](https://www.blacklanternsecurity.com/bbot/Stable/how_it_works/).
 
 ![subdomain-stats-ebay](https://github.com/blacklanternsecurity/bbot/assets/20261699/de3e7f21-6f52-4ac4-8eab-367296cd385f)
 
@@ -225,10 +227,18 @@ include:
 
 config:
   modules:
+    baddns:
+      enable_references: True
     dnsbrute:
       recursive_mutations: true
     dnscommonsrv:
       recursive_mutations: true
+    webbrute:
+      avoid_wafs: False
+    wayback:
+      urls: True
+      parameters: True
+      archive: True
 
 ```
 
@@ -386,15 +396,19 @@ For details, see [Configuration](https://www.blacklanternsecurity.com/bbot/Stabl
     - **Modules**
         - [List of Modules](https://www.blacklanternsecurity.com/bbot/Stable/modules/list_of_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 (DAST)](https://www.blacklanternsecurity.com/bbot/Stable/modules/lightfuzz)
+        - [Lightfuzz](https://www.blacklanternsecurity.com/bbot/Stable/modules/lightfuzz)
+    - **Migration**
+        - [2.x → 3.0 Breaking Changes](https://www.blacklanternsecurity.com/bbot/Stable/migration/3.0_breaking_changes)
     - **Misc**
         - [Contribution](https://www.blacklanternsecurity.com/bbot/Stable/contribution)
         - [Release History](https://www.blacklanternsecurity.com/bbot/Stable/release_history)
         - [Troubleshooting](https://www.blacklanternsecurity.com/bbot/Stable/troubleshooting)
 - **Developer Manual**
     - [Development Overview](https://www.blacklanternsecurity.com/bbot/Stable/dev/)
     - [Setting Up a Dev Environment](https://www.blacklanternsecurity.com/bbot/Stable/dev/dev_environment)
+    - [Core Dependencies](https://www.blacklanternsecurity.com/bbot/Stable/dev/core_dependencies)
     - [BBOT Internal Architecture](https://www.blacklanternsecurity.com/bbot/Stable/dev/architecture)
     - [How to Write a BBOT Module](https://www.blacklanternsecurity.com/bbot/Stable/dev/module_howto)
     - [Validating & Inspecting Presets](https://www.blacklanternsecurity.com/bbot/Stable/dev/preset_validation)
@@ -407,7 +421,6 @@ For details, see [Configuration](https://www.blacklanternsecurity.com/bbot/Stabl
         - [Target](https://www.blacklanternsecurity.com/bbot/Stable/dev/target)
         - [BaseModule](https://www.blacklanternsecurity.com/bbot/Stable/dev/basemodule)
         - [BBOTCore](https://www.blacklanternsecurity.com/bbot/Stable/dev/core)
-        - [Engine](https://www.blacklanternsecurity.com/bbot/Stable/dev/engine)
         - **Helpers**
             - [Overview](https://www.blacklanternsecurity.com/bbot/Stable/dev/helpers/)
             - [Command](https://www.blacklanternsecurity.com/bbot/Stable/dev/helpers/command)

diff --git a/docs/contribution.md b/docs/contribution.md
@@ -1,8 +1,63 @@
-# Contribution
+# Contributing to BBOT
 
-We welcome contributions! If you have an idea for a new module, or are a Python developer who wants to get involved, please fork us or come talk to us on [Discord](https://discord.com/invite/PZqkgxu5SA).
+We welcome contributions! There are a number of ways to contribute to BBOT.
 
-To get started devving, see the following links:
+If you want to chat about BBOT or get help with a contribution, come find us on [Discord](https://discord.com/invite/PZqkgxu5SA).
+
+## Open an Issue
+
+Opening an issue is the simplest way to contribute. If you spot a bug or see a way to improve something, open an issue and we'll do our best to address it promptly.
+
+## Open a Discussion
+
+If you have an idea for a new module or feature, or just have questions about existing modules, discussions are the correct place for it. Issues opened for these items will most likely be moved here anyway.
+
+## Pull Requests
+
+We love pull requests. Before you submit them though, there are a few things to discuss.
+
+### Should It Be an Issue Instead?
+
+As AI-assisted contributions have become more common, we've seen an increase in large PRs trying to change things that touch complex core internals. Much of the core BBOT code is extremely complicated and load-bearing. If your AI doesn't grasp the full context, untangling your PR is going to take us longer than if we made the changes ourselves.
+
+Basically, don't feel pressured to submit a fix just because you found a bug. If the fix isn't straightforward, an issue that shows clearly how to reproduce the problem is often more helpful than a sprawling PR.
+
+### AI Policy
+
+Modern AI is an incredibly valuable tool for development. We definitely use it. However, it is still just a tool, and it REALLY matters how you use it.
+
+- **Blind trust is not good.** Even the most advanced models make horrific mistakes, just as they have moments of brilliance.
+- **Human accountability.** If your name is on the code, it's up to you to understand it. A simple rule: don't submit anything you don't understand.
+- **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 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.
+
+### Other Advice
+
+- **Work off the `dev` branch.** Almost all PRs should target `dev`, not `stable`. Create your feature branch from `dev` and open your PR against it.
+- The pull requests we are most likely to approve are ones that address a very specific thing in a focused way. Don't let that stop you from writing a whole new, even complicated module. However, expect some critical feedback and some rounds of revisions.
+- Be mindful of security. We have had multiple CVEs, including critical CVEs. If your module is doing potentially dangerous things like running commands, reading and writing files, etc. -  expect a lot of extra scrutiny.
+
+### Tests
+
+We believe tests are the backbone of any large scale project. Think of them like a save-point for a capability. Without them, regressions constantly creep in and accumulate.
+
+Every module MUST have module tests. There are tons of examples to draw from with existing modules. We can also help you write the tests. They shouldn't be there just to be there, they should really exercise as much of the code in your module as possible. 
+
+If you make a change to any core code, helpers, etc - chances are if you break anything, our massive amount of tests (as of this writing's creation over 300) will catch it. So run them. Try to run the entire test suite against your code before you submit it. 
+
+For more details, see [Unit Tests](./dev/tests.md).
+
+## Contributor License Agreement
+
+Like many open-source projects, we ask that you sign our [Contributor License Agreement](https://github.com/blacklanternsecurity/CLA/blob/main/ICLA.md) before we can accept your contribution.
+
+## Development
+
+Ready to dive in? See the following links to get started:
 
 - [Setting up a Dev Environment](./dev/dev_environment.md)
 - [How to Write a BBOT Module](./dev/module_howto.md)