[liquidsec]

Adds docs/migration/3.1_breaking_changes.md, a migration page for 3.0 → 3.1 in the same format as the 3.0 one, and links it in the docs nav.

Covers: preset and custom-module hardening from #3593 (the module_dirs trust prompt and permission checks, config.module_dirs deprecation, -S no longer implying -y, a custom dir not being named modules, read-only preset conditions, and version/home validation), deprecated retries options (#3461), up-front nuclei option validation (#3479), the core CDN/WAF port filter replacing portfilter (#3534), dnsdumpster requiring an API key (#3458), the waf_bypass scan_targets_only default (#3460), wayback liveness checks (#3359), CPE technology names (#3535), the in-scope affiliate tag (#3524), wayback HTTP_RESPONSE changes and response_to_json() removal (#3473).

The preset/module section describes #3593, so this should merge after it.

Refs #3555

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91%. Comparing base (dacf31c) to head (c3f1108).
⚠️ Report is 24 commits behind head on dev.

Additional details and impacted files

@@           Coverage Diff           @@
##             dev   #3594     +/-   ##
=======================================
+ Coverage     91%     91%     +1%     
=======================================
  Files        463     463             
  Lines      50156   51266   +1110     
=======================================
+ Hits       45280   46388   +1108     
- Misses      4876    4878      +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[en0f]

By design?

Blocked: the custom module folders (module_dirs) section depends on code that isn’t in dev yet. The section describes the trust prompt, the world-writable refusal, the deprecation of config.module_dirs, and the refusal to let a custom module reuse an existing name. None of that is on this PR’s base:

config.module_dirs is still loaded (bbot/scanner/preset/validate.py:235).
No trust prompt exists anywhere in bbot/.

All of that behaviour lives only on the unmerged module-dirs-hardening branch. That branch also adds the “Custom Modules” text in docs/scanning/presets.md that this doc links to. CI rebuilds the Dev docs on every push to dev, so merging this PR first would publish migration guidance for behaviour that doesn’t exist. Merge module-dirs-hardening first, or hold this section until it lands.

[liquidsec]

@en0f Not included since its not merged yet. Once it is i will need to update.

[liquidsec]

@en0f the ordering dependency stands: this describes #3593's behavior, so it merges after #3593, not before. That's noted in the PR description.

I've expanded the module_dirs section to cover the rest of #3593 now that its scope grew: the -S-no-longer-implies--y change, world-writable parent/group permission notes, the modules-name refusal, read-only preset conditions, and version/home validation. Re-requesting review.

[en0f]

Approved. FYSA:

Merge order: the “Config and Presets” section describes behavior that exists only in #3593 (module-dirs-hardening), which hasn’t been merged into dev yet. On current dev:

-S still implies -y (args.py:458-460). The doc says it no longer does, and that a silent run without -y stops with an error.

config.module_dirs is still honored and gives no deprecation warning.

There’s no “Do you trust this folder?” prompt, no world-writable check, no name-collision refusal, and no rule against a folder named modules.

Preset conditions still run against the live preset (SandboxedEnvironment, not the read-only snapshot).
version and home aren’t validated.

If this PR lands first, the published docs describe behavior that isn’t in the code. Merge it after #3593, or together with it.

[liquidsec]

@en0f i changed wording slightly so i need a re-review. But we can keep this open until closer to release in case anything else comes up.

[singlerider]

Reviewed at c3f1108.

🟢 Every claim checks out against the code

Checked each section against dev and #3593: the trust prompt, sticky-parent exception, modules name refusal, name collision, bytecode skip and shell-metacharacter validation all match #3593, and the CDN filter keys, --exclude-cdn deprecation, dnsdumpster mandatory key, nuclei validators and response_to_event_dict() match dev. mkdocs build passes and the presets.md#custom-modules anchor resolves.

🟢 Merge order is stated

The body says this lands after #3593, which covers the concern from the earlier review.