Skip to content

Commit 5d50c2e

Browse files
TMHSDigitalclaude
andcommitted
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>
1 parent 0bf74b2 commit 5d50c2e

6 files changed

Lines changed: 159 additions & 15 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). 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).
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/mcp.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,9 @@ same summary. It says how far the results can be trusted, why, and what to
4646
change next time.
4747

4848
`lab_scan` and `scan` return JSON with the names found and their records, how
49-
every lookup ended, any notices, and the scan's verdict:
49+
every lookup ended, any notices, and the scan's verdict. Both declare it as an
50+
`outputSchema`, and send it as `structuredContent` as well as text, so a client
51+
can read the report as data without parsing it:
5052

5153
| Verdict | Meaning for the agent |
5254
| :--- | :--- |

‎internal/mcp/mcp.go‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,10 @@ type Tool struct {
4242
Title string `json:"title,omitempty"`
4343
Description string `json:"description"`
4444
InputSchema json.RawMessage `json:"inputSchema"`
45-
Annotations Annotations `json:"annotations"`
45+
// OutputSchema, when set, describes Result.Structured, which every
46+
// successful call of the tool then returns (#270).
47+
OutputSchema json.RawMessage `json:"outputSchema,omitempty"`
48+
Annotations Annotations `json:"annotations"`
4649

4750
// Call runs the tool. ctx is cancelled when the client cancels the
4851
// request or the session ends.
@@ -56,10 +59,13 @@ type Annotations struct {
5659
}
5760

5861
// Result is what a tool call returns: text for the model, and whether it
59-
// reports a failure the model should see as one.
62+
// reports a failure the model should see as one. Structured, when set, is
63+
// sent as structuredContent for clients that read results as data; Text
64+
// should then hold the same value as JSON, for clients that do not.
6065
type Result struct {
61-
Text string
62-
IsError bool
66+
Text string
67+
IsError bool
68+
Structured any
6369
}
6470

6571
// Errorf is a failed tool call with a message for the model.
@@ -276,10 +282,14 @@ func (ss *session) call(ctx context.Context, params json.RawMessage) (any, *rpcE
276282
}
277283

278284
func toolResult(r Result) map[string]any {
279-
return map[string]any{
285+
m := map[string]any{
280286
"content": []map[string]any{{"type": "text", "text": r.Text}},
281287
"isError": r.IsError,
282288
}
289+
if r.Structured != nil {
290+
m["structuredContent"] = r.Structured
291+
}
292+
return m
283293
}
284294

285295
func (ss *session) reply(id json.RawMessage, result any, rerr *rpcError) {

‎internal/mcp/mcp_test.go‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,37 @@ func TestProgressNotifications(t *testing.T) {
222222
}
223223
}
224224

225+
// TestStructuredContent: a tool's outputSchema is listed, and a Structured
226+
// result is sent as structuredContent beside the text (#270).
227+
func TestStructuredContent(t *testing.T) {
228+
tool := Tool{
229+
Name: "data",
230+
InputSchema: json.RawMessage(`{"type":"object"}`),
231+
OutputSchema: json.RawMessage(`{"type":"object","properties":{"n":{"type":"integer"}}}`),
232+
Call: func(context.Context, json.RawMessage) Result {
233+
return Result{Text: `{"n":1}`, Structured: map[string]int{"n": 1}}
234+
},
235+
}
236+
send, recv, _ := serve(t, &Server{Tools: []Tool{tool, echoTool()}})
237+
send(`{"jsonrpc":"2.0","id":1,"method":"tools/list"}`)
238+
tools := recv()["result"].(map[string]any)["tools"].([]any)
239+
if _, ok := tools[0].(map[string]any)["outputSchema"]; !ok {
240+
t.Errorf("tools/list lacks the outputSchema: %v", tools[0])
241+
}
242+
if _, ok := tools[1].(map[string]any)["outputSchema"]; ok {
243+
t.Errorf("a tool without one lists an outputSchema: %v", tools[1])
244+
}
245+
send(`{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"data"}}`)
246+
r := recv()["result"].(map[string]any)
247+
if sc, ok := r["structuredContent"].(map[string]any); !ok || sc["n"] != float64(1) {
248+
t.Errorf("structuredContent = %v", r["structuredContent"])
249+
}
250+
send(`{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo"}}`)
251+
if r := recv()["result"].(map[string]any); r["structuredContent"] != nil {
252+
t.Errorf("a text-only result sent structuredContent: %v", r)
253+
}
254+
}
255+
225256
// TestMalformedToolCallParams: params that are not a tools/call object get
226257
// an invalid-params error, not a crash or a call (#258).
227258
func TestMalformedToolCallParams(t *testing.T) {

‎main_mcp.go‎

Lines changed: 57 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -308,11 +308,12 @@ func labScanTool(cfg mcpConfig) mcp.Tool {
308308
"additionalProperties": false
309309
}`, scenarios, labDomain, maxMCPWords, recordTypeSchema, cfg.maxQueries, remediationProps)
310310
return mcp.Tool{
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-
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},
316317
Call: func(ctx context.Context, raw json.RawMessage) mcp.Result {
317318
var args struct {
318319
Scenario string `json:"scenario"`
@@ -395,8 +396,9 @@ func scanTool(cfg mcpConfig) mcp.Tool {
395396
Title: "Enumerate subdomains",
396397
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.",
397398
cfg.rate, cfg.maxQueries, cfg.maxDuration, strings.Join(cfg.allow, ", ")),
398-
InputSchema: json.RawMessage(schema),
399-
Annotations: mcp.Annotations{ReadOnlyHint: true, OpenWorldHint: true},
399+
InputSchema: json.RawMessage(schema),
400+
OutputSchema: mcpReportSchema,
401+
Annotations: mcp.Annotations{ReadOnlyHint: true, OpenWorldHint: true},
400402
Call: func(ctx context.Context, raw json.RawMessage) mcp.Result {
401403
var args struct {
402404
Domain string `json:"domain"`
@@ -620,9 +622,56 @@ func (r *mcpReport) result() mcp.Result {
620622
if err != nil {
621623
return mcp.Errorf("encoding the report: %v", err)
622624
}
623-
return mcp.Result{Text: string(b), IsError: r.Error != ""}
625+
return mcp.Result{Text: string(b), IsError: r.Error != "", Structured: r}
624626
}
625627

628+
// mcpReportSchema is the outputSchema of scan and lab_scan: mcpReport as
629+
// JSON Schema (#270). TestMCPReportSchemaCoversTheReport keeps the two in
630+
// step.
631+
var mcpReportSchema = json.RawMessage(`{
632+
"type": "object",
633+
"properties": {
634+
"domain": {"type": "string"},
635+
"scenario": {"type": "string", "description": "lab_scan only"},
636+
"verdict": {"enum": ["complete", "degraded", "unreliable", "not_run"]},
637+
"reason": {"type": "string"},
638+
"error": {"type": "string"},
639+
"found": {"type": "integer"},
640+
"results": {"type": "array", "items": {
641+
"type": "object",
642+
"properties": {
643+
"name": {"type": "string"},
644+
"records": {"type": "array", "items": {"type": "string"}, "description": "\"TYPE value\", such as \"A 192.0.2.10\""},
645+
"takeover": {"type": "string"},
646+
"internal": {"type": "string"}
647+
},
648+
"required": ["name", "records"]
649+
}},
650+
"outcomes": {"type": "object", "properties": {
651+
"nxdomain": {"type": "integer"},
652+
"timeout": {"type": "integer"},
653+
"refused": {"type": "integer"},
654+
"other": {"type": "integer"},
655+
"wildcard_filtered": {"type": "integer"}
656+
}},
657+
"skipped_by_cap": {"type": "integer"},
658+
"excluded": {"type": "integer"},
659+
"retried": {"type": "integer"},
660+
"recovered": {"type": "integer"},
661+
"rate_backoffs": {"type": "integer"},
662+
"wildcard": {"type": "boolean"},
663+
"notices": {"type": "array", "items": {"type": "string"}},
664+
"sources": {"type": "array", "items": {
665+
"type": "object",
666+
"properties": {"name": {"type": "string"}, "names": {"type": "integer"}, "error": {"type": "string"}},
667+
"required": ["name", "names"]
668+
}},
669+
"max_queries": {"type": "integer"},
670+
"rate": {"type": "integer"}
671+
},
672+
"required": ["domain", "verdict", "reason", "found", "results", "outcomes", "max_queries"]
673+
}`)
674+
626675
func explainStatsTool() mcp.Tool {
627676
return mcp.Tool{
628677
Name: "explain_stats",

‎main_mcp_test.go‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import (
88
"fmt"
99
"os"
1010
"path/filepath"
11+
"reflect"
1112
"slices"
1213
"strings"
1314
"testing"
@@ -395,6 +396,57 @@ func TestMCPVerdictMatchesReport(t *testing.T) {
395396
}
396397
}
397398

399+
// TestMCPReportSchemaCoversTheReport is #270's drift guard: every JSON field
400+
// of the report, and of its nested results, outcomes and sources, is in
401+
// the outputSchema, and the schema names nothing the report lacks.
402+
func TestMCPReportSchemaCoversTheReport(t *testing.T) {
403+
var schema map[string]any
404+
if err := json.Unmarshal(mcpReportSchema, &schema); err != nil {
405+
t.Fatalf("outputSchema is not JSON: %v", err)
406+
}
407+
props := func(s map[string]any) map[string]any { return s["properties"].(map[string]any) }
408+
top := props(schema)
409+
check := func(where string, typ reflect.Type, schemaProps map[string]any) {
410+
t.Helper()
411+
fields := map[string]bool{}
412+
for i := range typ.NumField() {
413+
name, _, _ := strings.Cut(typ.Field(i).Tag.Get("json"), ",")
414+
fields[name] = true
415+
if _, ok := schemaProps[name]; !ok {
416+
t.Errorf("%s field %q is missing from the outputSchema", where, name)
417+
}
418+
}
419+
for name := range schemaProps {
420+
if !fields[name] {
421+
t.Errorf("outputSchema names %s.%s, which the report does not have", where, name)
422+
}
423+
}
424+
}
425+
check("report", reflect.TypeOf(mcpReport{}), top)
426+
check("results[]", reflect.TypeOf(mcpResult{}), props(top["results"].(map[string]any)["items"].(map[string]any)))
427+
check("outcomes", reflect.TypeOf(mcpOutcomes{}), props(top["outcomes"].(map[string]any)))
428+
check("sources[]", reflect.TypeOf(mcpSource{}), props(top["sources"].(map[string]any)["items"].(map[string]any)))
429+
}
430+
431+
// TestE2EMCPStructuredContent: a scan reply carries the report as
432+
// structuredContent too, equal to the JSON in its text (#270).
433+
func TestE2EMCPStructuredContent(t *testing.T) {
434+
_, replies := runMCPSession(t, nil, mcpCall{"lab_scan", `{"words": ["www", "nope"]}`})
435+
result := replies[0]["result"].(map[string]any)
436+
structured, ok := result["structuredContent"].(map[string]any)
437+
if !ok {
438+
t.Fatalf("no structuredContent in %v", result)
439+
}
440+
text, _ := toolText(t, replies[0])
441+
var fromText map[string]any
442+
if err := json.Unmarshal([]byte(text), &fromText); err != nil {
443+
t.Fatal(err)
444+
}
445+
if !reflect.DeepEqual(structured, fromText) {
446+
t.Errorf("structuredContent %v differs from the text report %v", structured, fromText)
447+
}
448+
}
449+
398450
// TestTypeAndFormatListsAgree is #264's drift guard: completion and the MCP
399451
// schema offer exactly the record types and formats the flags accept.
400452
func TestTypeAndFormatListsAgree(t *testing.T) {

0 commit comments

Comments
 (0)