You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 4e7dc6b
Browse filesBrowse the repository at this point in the historyBrowse files
Describe each lab scenario in the lab_scan schema (#275)
lab_scan offered scenario names only as an enum, so an agent could not
tell what a lab teaches without docs/labs.md. The scenario argument's
description now lists each scenario with the opening comment of its
embedded zone file, minus the "Lab N:" prefix and the command line.
Lab 1's comment gains a real description, and docs/labs.md asks new
scenarios to open with one.
Fixes#275
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: CHANGELOG.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
8
8
## [Unreleased]
9
9
10
10
### Added
11
-
- `subenum mcp` serves subdomain enumeration to AI agents over the Model Context Protocol (stdio). Tools: `lab_scan`, which scans the compiled-in lab scenarios on a loopback DNS server; `scan`, offered only with `-allow` and refusing any domain outside it; and `explain_stats`, which explains a `-stats` report or `-format jsonl` output. The operator sets the resolver, rate, timeout and budgets (`-dns-server`, `-rate`, `-timeout`, `-max-queries`, `-max-duration`, which cannot be turned off). A call can lower `max_queries`, never raise it; unknown arguments are refused, and calls run one at a time. Each scan returns its results with a verdict (`complete`, `degraded`, `unreliable` or `not_run`), and sends progress notifications about once a second when the call carries a `progressToken` (#267). `-sources ct,wayback` lets `scan` calls seed candidates from passive sources through a `sources` argument; it is off by default, and the report counts each source's names or names its error (#268). `scan` and `lab_scan` accept `retry_inconclusive`, `auto_rate`, `exclude` and `depth` (up to 3), all within the operator's caps, so an agent can act on a verdict that is not complete; the report adds `retried`, `recovered`, `rate_backoffs` and `excluded` (#269). Their report is also declared as an `outputSchema` and sent as `structuredContent`, beside the same JSON as text (#270). `-max-calls` (default 100) caps the `scan` calls one session may make, and a client that stops reading replies ends the session, cancelling queued calls instead of scanning for nobody (#240). A request line over 16 MiB gets a JSON-RPC parse error instead of ending the session, a request reusing the ID of one still running is refused, and a scan cancelled before testing any name reports `not_run` rather than `degraded` (#241). The JSON-RPC layer is a small hand-written `internal/mcp` package, so there is no new dependency (#131).
11
+
- `subenum mcp` serves subdomain enumeration to AI agents over the Model Context Protocol (stdio). Tools: `lab_scan`, which scans the compiled-in lab scenarios on a loopback DNS server; `scan`, offered only with `-allow` and refusing any domain outside it; and `explain_stats`, which explains a `-stats` report or `-format jsonl` output. The operator sets the resolver, rate, timeout and budgets (`-dns-server`, `-rate`, `-timeout`, `-max-queries`, `-max-duration`, which cannot be turned off). A call can lower `max_queries`, never raise it; unknown arguments are refused, and calls run one at a time. Each scan returns its results with a verdict (`complete`, `degraded`, `unreliable` or `not_run`), and sends progress notifications about once a second when the call carries a `progressToken` (#267). `-sources ct,wayback` lets `scan` calls seed candidates from passive sources through a `sources` argument; it is off by default, and the report counts each source's names or names its error (#268). `scan` and `lab_scan` accept `retry_inconclusive`, `auto_rate`, `exclude` and `depth` (up to 3), all within the operator's caps, so an agent can act on a verdict that is not complete; the report adds `retried`, `recovered`, `rate_backoffs` and `excluded` (#269). Their report is also declared as an `outputSchema` and sent as `structuredContent`, beside the same JSON as text (#270). `-max-calls` (default 100) caps the `scan` calls one session may make, and a client that stops reading replies ends the session, cancelling queued calls instead of scanning for nobody (#240). A request line over 16 MiB gets a JSON-RPC parse error instead of ending the session, a request reusing the ID of one still running is refused, and a scan cancelled before testing any name reports `not_run` rather than `degraded` (#241). The JSON-RPC layer is a small hand-written `internal/mcp` package, so there is no new dependency (#131). `lab_scan`'s `scenario` argument describes what each lab teaches, taken from the opening comment of its zone file (#275).
12
12
-`-sources ct,wayback` picks keyless passive sources whose names become candidates and `-permute` seeds, each still verified by a lookup. `ct` is crt.sh, as `-ct`, which stays as shorthand. `wayback` is new: the hostnames in the Wayback Machine's index of archived URLs, one HTTPS request per target. The report gains a `sources` entry per source (`names`, or the `error` it hit; `ct_names` and `ct_error` are kept), a failed source is a warning, the resume state keeps each source's names, simulation ignores `-sources` and lab mode refuses it. Sources share one interface in a new `internal/passive` package. `pkg/subenum` gains `Config.Sources`, the `Source` interface, `CertificateTransparency()`, `WaybackMachine()` and `NoticeSource` (#193).
13
13
-`-axfr` tries a zone transfer (AXFR) of each target from its name servers before the scan: the NS records come from `-dns-server`, then each server (up to 8, two addresses each) is asked over TCP. A server that allows it is reported on stderr and in the run-quality report (`axfr_allowed`, `axfr_names`), and the zone's names become candidates and `-permute` seeds, each still verified by a lookup. Refusals, the correct configuration, stay quiet unless `-v`. The NS and address lookups and the transfers count in `queries_sent`; simulation ignores `-axfr`, lab mode refuses it, and a resumed scan reuses the transferred names. The test DNS server can answer AXFR (`Reply.Transfer`) (#85).
14
14
-`-axfr` also sends one DNSSEC probe per target to an authoritative server: a query for a name that does not exist, with the DNSSEC OK bit set. A zone that proves the absence with plain NSEC can be walked to list every name, so it is reported as `Zone walkable` on stderr. The report's `zone_denial` says `nsec`, `nsec3` or `none` (unsigned). subenum does not walk the zone. The test DNS server can sign negative answers (`Reply.Denial`) (#234).
@@ -307,18 +347,20 @@ var recordTypeSchema = func() json.RawMessage {
307
347
308
348
funclabScanTool(cfgmcpConfig) mcp.Tool {
309
349
scenarios, _:=json.Marshal(labScenarios())
350
+
scenarioDesc, _:=json.Marshal(fmt.Sprintf("Lab scenario to scan; default lab1-first-scan. Each is a fictional zone for %s served on this machine.%s",
351
+
labDomain, labScenarioGuide()))
310
352
schema:=fmt.Sprintf(`{
311
353
"type": "object",
312
354
"properties": {
313
-
"scenario": {"enum": %s, "description": "Lab scenario to scan; default lab1-first-scan. Each is a fictional zone for %s served on this machine."},
355
+
"scenario": {"enum": %s, "description": %s},
314
356
"words": {"type": "array", "items": {"type": "string"}, "maxItems": %d, "description": "Subdomain labels to try; default the labs' short wordlist."},
315
357
"types": %s,
316
358
"rate": {"type": "integer", "minimum": 0, "maximum": 1000, "description": "Queries per second; 0 or absent is unlimited. Lab traffic stays on this machine."},
ifwant:="spot the wildcard. Every name under lab.example resolves... except that a few of them are real hosts with their own addresses."; labScenarioDescription("lab2-wildcard") !=want {
0 commit comments