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 5d50c2e
Browse filesBrowse the repository at this point in the historyBrowse files
Return MCP scan reports as structuredContent (#270)
Tool results were JSON inside a text block only. mcp.Tool gains
OutputSchema and mcp.Result gains Structured, sent as
structuredContent. scan and lab_scan declare the report's JSON Schema
and return the report both ways, so clients that validate or chain
tool output can read it as data; the text stays for older clients. A
reflection test keeps the schema and the report struct in step.
Fixes#270
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). 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). The JSON-RPC layer is a small hand-written `internal/mcp` package, so there is no new dependency (#131).
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).
Description: fmt.Sprintf("Enumerate subdomains of %s in one of subenum's lab scenarios: fictional zones answered by a DNS server on this machine, so no traffic leaves it. Safe for practice and for learning how wildcards, rate limits and failing resolvers change a scan's verdict.", labDomain),
314
-
InputSchema: json.RawMessage(schema),
315
-
Annotations: mcp.Annotations{ReadOnlyHint: true},
311
+
Name: "lab_scan",
312
+
Title: "Scan a lab zone",
313
+
Description: fmt.Sprintf("Enumerate subdomains of %s in one of subenum's lab scenarios: fictional zones answered by a DNS server on this machine, so no traffic leaves it. Safe for practice and for learning how wildcards, rate limits and failing resolvers change a scan's verdict.", labDomain),
314
+
InputSchema: json.RawMessage(schema),
315
+
OutputSchema: mcpReportSchema,
316
+
Annotations: mcp.Annotations{ReadOnlyHint: true},
316
317
Call: func(ctx context.Context, raw json.RawMessage) mcp.Result {
Description: fmt.Sprintf("Enumerate subdomains of a real domain by DNS, through the operator's resolver at %d queries per second, testing at most %d names in %s. Only domains the operator allowed can be scanned: %s.",
0 commit comments