AGENTS.md: fix the options section and refresh stale module examples - #3420
AGENTS.md: fix the options section and refresh stale module examples#3420repins267 wants to merge 2 commits into
Conversation
|
All contributors have signed the CLA ✍️ ✅ |
The Options section documented `options` / `options_desc` dicts, but BBOT
3.0+ refuses to load a module that declares them:
[CRIT] Module "..." declares a legacy `options` dict, which is no
longer supported in BBOT 3.0+.
Since AGENTS.md is what we hand contributors (and their LLMs) before they
write a module, this sent them straight into a module that won't load.
Replaced with the pydantic `class Config(BaseModuleConfig)` form actually
in use -- the robots.py example is that module's current code, plus a
shodan_dns example showing `sensitive` / `mandatory` on an API key.
sslcert was reworked in 3.0 -- it now watches HTTP_RESPONSE instead of OPEN_TCP_PORT and no longer declares options, _module_threads, filter_event, deps_pip or deps_apt. AGENTS.md still cited it for all of those, so several examples described attributes the module doesn't have. Repointed each to a module that currently has the attribute, keeping the same teaching point: watched_events OPEN_TCP_PORT sslcert -> fingerprintx _module_threads sslcert -> iis_shortnames (4) deps_pip sslcert -> badsecrets deps_apt sslcert -> git_clone filter_event (False, reason) sslcert -> apkpure Also corrected sslcert's own flags example: it carries `safe`, which the section above requires, and it reads certs from already-fetched responses rather than connecting to ports itself. The sslcert citations that are still accurate (produced_events, scope_distance_modifier, _priority) are unchanged.
464531a to
407d913
Compare
|
I have read the CLA Document and I hereby sign the CLA |
|
recheck |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## dev #3420 +/- ##
=====================================
+ Coverage 90% 90% +1%
=====================================
Files 454 454
Lines 47081 47081
=====================================
+ Hits 42316 42322 +6
+ Misses 4765 4759 -6 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Welcome, and thanks. I checked every claim against dev rather than trusting the description. All of it holds.
The rejection is real: modules.py:800-812 raises, preload() catches at 421 and exits CRITICAL. Leaving the 6 template dicts alone was right, file_filter() at 340-345 means they never reach the rejection. Every example swap matches source, and the sslcert citations you kept are still true.
Nothing blocking. Ship it.
🟢 The Options rewrite fixes the highest-cost doc bug in the file
We hand this file to contributors and tell them to feed it to their LLM, so a wrong example here gets amplified.
| # sslcert.py - connects directly to target ports | ||
| flags = ["affiliates", "subdomain-enum", "email-enum", "active", "web"] | ||
| # sslcert.py - reads certs from responses the scan already fetched | ||
| flags = ["safe", "affiliates", "subdomain-enum", "email-enum", "active", "web"] |
There was a problem hiding this comment.
🟢 Catching the missing safe flag was sharp; the section above requires it and the module has it.
2 participants
AGENTS.md: fix the options section and refresh stale module examples
Summary
Two docs-only commits to
AGENTS.md. The first fixes a section that sends contributors into amodule that won't load; the second repoints example snippets at modules that still have the
attributes being illustrated.
1. The Options section documents a form BBOT 3.0 rejects
AGENTS.md§Options documentedoptions/options_descdicts. BBOT 3.0+ refuses to load a modulethat declares them. Dropping a module with a legacy dict into
bbot/modules/and runningbbot -l:Since
AGENTS.mdis the file you hand contributors — and explicitly tell them to feed to their LLM —before they write a module, this is the one doc bug that reliably produces a broken first module.
Replaced with the pydantic form actually in use.
robots.pyis quoted from its current source (itwas already the example in this section), plus a
shodan_dns.pyexample showingsensitive/mandatoryon an API key.For scale: on
devtoday, 118 modules useclass Configand 6 use the legacy dicts — and those6 are
bbot/modules/templates/*+base.py, where the dicts appear vestigial (concrete modules likeshodan_dnsdeclare their ownConfig, and their options surface correctly in--list-module-options). I left those alone — happy to open a separate issue if you'd like themcleaned up, but that's a code change and your call.
2.
sslcertexamples no longer match the modulesslcertwas reworked in 3.0: it watchesHTTP_RESPONSErather thanOPEN_TCP_PORT, and no longerdeclares
options,_module_threads,filter_event,deps_pip, ordeps_apt.AGENTS.mdstillcited it for each of those, so those snippets describe attributes the module doesn't have.
Each is repointed to a module that currently has the attribute, keeping the same teaching point:
watched_events(OPEN_TCP_PORT)fingerprintx_module_threadsiis_shortnames(4)deps_pipbadsecretsdeps_aptgit_clonefilter_event(False, "reason")apkpureAlso corrected sslcert's own
flagsexample: it carriessafe(which the section immediately aboverequires: "Must also include
safe,loud, orinvasive"), and it reads certs from responses thescan already fetched rather than connecting to ports itself.
The sslcert citations that are still accurate —
produced_events,scope_distance_modifier = 1,_priority = 2— are unchanged. Every replacement was verified against the module source ondev.Notes
AI Use Disclosure
Model: Claude Opus. I hit the
optionsguidance while writing a module, the module wouldn't load, and I used Claude to trace why and to check how widely the doc had drifted from the code. It drafted the edits; I confirmed each one against the source ondevand reproduced the load failure myself before filing.