Skip to content

Commit 4e7dc6b

Browse files
TMHSDigitalclaude
andcommitted
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>
1 parent bb98c4c commit 4e7dc6b

6 files changed

Lines changed: 81 additions & 5 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
## [Unreleased]
99

1010
### 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).
1212
- `-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).
1313
- `-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).
1414
- `-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).

‎docs/labs.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,11 @@ slow TIMEOUT # never answered
188188
broken SERVFAIL # also: REFUSED, NXDOMAIN
189189
```
190190

191+
Start a scenario in `examples/labs` with a comment saying what it teaches
192+
(`# Lab 6: <title>. <what to look for>`): `subenum mcp` shows that comment,
193+
without the lab number and any indented command line, to agents choosing a
194+
scenario.
195+
191196
Names the file does not define are NXDOMAIN. The scenario is the whole world
192197
during a lab, so names outside the scanned domain (such as an external CNAME
193198
target) are NXDOMAIN too. Use the

‎docs/mcp.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,9 @@ refused rather than ignored. A client that sends a `progressToken` with a
3333
compiled into the binary and answered by a DNS server on the loopback
3434
interface. No traffic leaves the machine, so it is always offered and always
3535
safe. It is the place for an agent to learn what wildcards, rate limits and a
36-
failing resolver do to a scan.
36+
failing resolver do to a scan. Its `scenario` argument describes each
37+
scenario, from the opening comment of its zone file, so an agent can pick one
38+
and explain it.
3739

3840
**`scan`** enumerates a real domain through the operator's resolver. It is
3941
offered only when `-allow` names at least one domain, and it refuses any domain

‎examples/labs/lab1-first-scan.zone‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
# Lab 1: first scan. Run:
1+
# Lab 1: first scan. A few hosts, one with IPv6, an alias, and a CNAME
2+
# that only shows up when CNAME lookups are on. Run:
23
# subenum -w examples/labs/words.txt -simulate-zone examples/labs/lab1-first-scan.zone -show-records lab.example
34
@ A 192.0.2.1
45
www A 192.0.2.10

‎main_mcp.go‎

Lines changed: 44 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -235,6 +235,46 @@ func labScenarios() []string {
235235
return names
236236
}
237237

238+
// labScenarioDescription is what a scenario teaches, from its file's opening
239+
// comment (#275): the comment lines before the first record, without the
240+
// "Lab N:" prefix, the "Run:" hint or the indented command under it.
241+
func labScenarioDescription(name string) string {
242+
b, _ := labFiles.ReadFile(path.Join(labDir, name+".zone"))
243+
var parts []string
244+
for line := range strings.Lines(string(b)) {
245+
text, ok := strings.CutPrefix(line, "#")
246+
if !ok {
247+
break
248+
}
249+
if strings.HasPrefix(text, " ") { // a command to run
250+
continue
251+
}
252+
text = strings.TrimSpace(text)
253+
if strings.HasPrefix(text, "Lab ") {
254+
if _, rest, ok := strings.Cut(text, ": "); ok {
255+
text = rest
256+
}
257+
}
258+
text = strings.TrimSpace(strings.TrimSuffix(text, "Run:"))
259+
if text != "" {
260+
parts = append(parts, text)
261+
}
262+
}
263+
return strings.Join(parts, " ")
264+
}
265+
266+
// labScenarioGuide lists every scenario with its description, for the
267+
// lab_scan schema.
268+
func labScenarioGuide() string {
269+
var b strings.Builder
270+
for _, name := range labScenarios() {
271+
if desc := labScenarioDescription(name); desc != "" {
272+
fmt.Fprintf(&b, " %s: %s", name, desc)
273+
}
274+
}
275+
return b.String()
276+
}
277+
238278
func labWords() []string {
239279
b, _ := labFiles.ReadFile(path.Join(labDir, "words.txt"))
240280
words, _ := wordlist.ReadLinesFrom(bytes.NewReader(b))
@@ -307,18 +347,20 @@ var recordTypeSchema = func() json.RawMessage {
307347

308348
func labScanTool(cfg mcpConfig) mcp.Tool {
309349
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()))
310352
schema := fmt.Sprintf(`{
311353
"type": "object",
312354
"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},
314356
"words": {"type": "array", "items": {"type": "string"}, "maxItems": %d, "description": "Subdomain labels to try; default the labs' short wordlist."},
315357
"types": %s,
316358
"rate": {"type": "integer", "minimum": 0, "maximum": 1000, "description": "Queries per second; 0 or absent is unlimited. Lab traffic stays on this machine."},
317359
"max_queries": {"type": "integer", "minimum": 1, "maximum": %d, "description": "Most names to test."},
318360
"force": {"type": "boolean", "description": "Scan a wildcard zone anyway, filtering answers that match the wildcard."}%s
319361
},
320362
"additionalProperties": false
321-
}`, scenarios, labDomain, maxMCPWords, recordTypeSchema, cfg.maxQueries, remediationProps)
363+
}`, scenarios, scenarioDesc, maxMCPWords, recordTypeSchema, cfg.maxQueries, remediationProps)
322364
return mcp.Tool{
323365
Name: "lab_scan",
324366
Title: "Scan a lab zone",

‎main_mcp_test.go‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -429,6 +429,32 @@ func TestMCPReportSchemaCoversTheReport(t *testing.T) {
429429
check("sources[]", reflect.TypeOf(mcpSource{}), props(top["sources"].(map[string]any)["items"].(map[string]any)))
430430
}
431431

432+
// TestMCPLabScenariosDescribed covers #275: lab_scan's schema tells the
433+
// agent what each scenario teaches, from the zone files' opening comments.
434+
func TestMCPLabScenariosDescribed(t *testing.T) {
435+
var schema struct {
436+
Properties map[string]struct {
437+
Description string `json:"description"`
438+
} `json:"properties"`
439+
}
440+
if err := json.Unmarshal(labScanTool(mcpConfig{maxQueries: 10}).InputSchema, &schema); err != nil {
441+
t.Fatalf("lab_scan inputSchema is not JSON: %v", err)
442+
}
443+
desc := schema.Properties["scenario"].Description
444+
for _, name := range labScenarios() {
445+
about := labScenarioDescription(name)
446+
if about == "" || strings.Contains(about, "subenum ") || strings.Contains(about, "Run:") || strings.HasPrefix(about, "Lab ") {
447+
t.Errorf("%s: description %q; want the opening comment without the lab number or the command", name, about)
448+
}
449+
if !strings.Contains(desc, name+": "+about) {
450+
t.Errorf("scenario schema description lacks %s's description:\n%s", name, desc)
451+
}
452+
}
453+
if want := "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 {
454+
t.Errorf("lab2-wildcard = %q, want %q", labScenarioDescription("lab2-wildcard"), want)
455+
}
456+
}
457+
432458
// TestE2EMCPStructuredContent: a scan reply carries the report as
433459
// structuredContent too, equal to the JSON in its text (#270).
434460
func TestE2EMCPStructuredContent(t *testing.T) {

0 commit comments

Comments
 (0)