Skip to content

Commit cc44385

Browse files
committed
MCP: guard the input schemas against their argument structs (#330)
The MCP tools' input schemas were written beside anonymous argument structs, so a field added to one and not the other went unnoticed, and lab_scan's rate bound was written three times. The argument structs are now named types (labScanArgs, scanArgs, explainStatsArgs), lab_scan's rate bound is one constant (maxMCPRate), and a test checks that each schema's properties match its struct's JSON fields. internal/cli/mcp.go is split into mcp.go (flags and server), mcp_tools.go (schemas and tools), mcp_report.go (reports and verdicts) and explain.go (explain_stats text); the code moved unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Fixes #330
1 parent d0d06c9 commit cc44385

6 files changed

Lines changed: 808 additions & 695 deletions

File tree

‎docs/ARCHITECTURE.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,11 +61,14 @@ internal/axfr/axfr.go - Try: AXFR from each name server and the denial
6161
internal/cli/diff.go - -diff / -diff-records: compare against a previous results file; runDiff: the diff subcommand
6262
internal/cli/dryrun.go - -dry-run: print the scan plan and its cost without sending queries
6363
internal/cli/lab.go - -simulate-zone: serve a lab scenario on a loopback DNS server
64-
internal/cli/mcp.go - subenum mcp: the lab_scan, scan and explain_stats tools, the allow-list and caps
64+
internal/cli/mcp.go - subenum mcp: its flags, the server, and the lab scenarios lab_scan serves
65+
internal/cli/mcp_tools.go - the lab_scan, scan and explain_stats tools: input schemas, argument checks, the allow-list and caps
66+
internal/cli/mcp_report.go - the scan report the tools return, its verdict and its outputSchema
6567
internal/cli/permute.go - -permute / -seeds: the permutation pass
6668
internal/cli/resume.go - -resume / -state: save and replay an interrupted run
6769
internal/cli/results.go - resultLog: a target's results, kept for -permute seeds and -diff
6870
internal/cli/summary.go - assemble the run-quality report (-stats, JSONL summary line)
71+
internal/cli/explain.go - parseSummary, explainSummary: a run-quality report in plain language (explain_stats)
6972
internal/cli/wordlist.go - prepareWordlist: the -w file, or the bundled list when -w is not given
7073
internal/scan/options.go - Options: user-facing settings shared by CLI and TUI (Validate, Config)
7174
internal/scan/runner.go - Scan engine: Config, Event/EventKind/NoticeKind, Stats, Run

‎internal/cli/explain.go‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
package cli
2+
3+
import (
4+
"encoding/json"
5+
"errors"
6+
"fmt"
7+
"strings"
8+
9+
"github.com/TMHSDigital/subenum/internal/output"
10+
"github.com/TMHSDigital/subenum/internal/scan"
11+
)
12+
13+
// parseSummary reads a -stats file, or finds the summary line at the end
14+
// of jsonl output.
15+
func parseSummary(text string) (output.Summary, error) {
16+
var s output.Summary
17+
if json.Unmarshal([]byte(text), &s) == nil && s.Type == "summary" {
18+
return s, nil
19+
}
20+
lines := strings.Split(strings.TrimSpace(text), "\n")
21+
for i := len(lines) - 1; i >= 0; i-- {
22+
s = output.Summary{}
23+
if json.Unmarshal([]byte(strings.TrimSpace(lines[i])), &s) == nil && s.Type == "summary" {
24+
return s, nil
25+
}
26+
}
27+
return s, errors.New(`stats is not a subenum run-quality report: expected JSON with "type": "summary", as -stats writes`)
28+
}
29+
30+
// verdictMeaning says what each verdict lets the reader conclude.
31+
var verdictMeaning = map[string]string{
32+
scan.VerdictComplete: "the results can be trusted, and a name missing from them most likely does not exist",
33+
scan.VerdictDegraded: "the results are usable, but some names were not tested or got no answer, so a missing name may still exist",
34+
scan.VerdictUnreliable: "too many lookups failed: a missing name means nothing, and the scan should be repeated",
35+
}
36+
37+
func explainSummary(s output.Summary) string {
38+
var b strings.Builder
39+
p := func(format string, a ...any) { _, _ = fmt.Fprintf(&b, format+"\n", a...) }
40+
p("Overall verdict: %s (%s).", s.Verdict, s.Reason)
41+
if m := verdictMeaning[s.Verdict]; m != "" {
42+
p("That means %s.", m)
43+
}
44+
switch {
45+
case s.Simulated:
46+
p("This was a simulated run (-simulate): the results are invented and no DNS query was sent.")
47+
case s.Zone != "":
48+
p("This was a lab run: answers came from the scenario %s on a local DNS server.", s.Zone)
49+
}
50+
if !s.Simulated {
51+
rate := "no rate limit"
52+
if s.RateLimit > 0 {
53+
rate = fmt.Sprintf("a limit of %d per second", s.RateLimit)
54+
}
55+
p("%d DNS queries went to %s in %.1fs, %.0f per second against %s.", s.QueriesSent, s.Resolver, float64(s.DurationMs)/1000, s.AchievedQPS, rate)
56+
}
57+
for _, t := range s.Targets {
58+
p("")
59+
explainTarget(p, t)
60+
}
61+
if s.Diff != nil {
62+
p("")
63+
p("Compared with %s: %d added, %d removed, %d changed.", s.Diff.Previous, s.Diff.Added, s.Diff.Removed, s.Diff.Changed)
64+
if s.Diff.Unverified > 0 {
65+
p("%d earlier names could not be checked, so they are not counted as removed.", s.Diff.Unverified)
66+
}
67+
}
68+
return strings.TrimRight(b.String(), "\n")
69+
}
70+
71+
func explainTarget(p func(string, ...any), t output.TargetSummary) {
72+
o := t.Outcomes
73+
p("%s: %s, verdict %s (%s).", t.Domain, t.Status, t.Verdict, t.Reason)
74+
if t.Error != "" {
75+
p(" Error: %s", t.Error)
76+
}
77+
p(" %d of %d candidate names tested, %d found. Outcomes: %d resolved, %d do not exist, %d timed out, %d refused, %d other failures, %d matched the wildcard.",
78+
t.Processed, t.Total, t.Found, o.Resolved, o.NXDomain, o.Timeout, o.Refused, o.Other, o.WildcardFiltered)
79+
failed := o.Timeout + o.Refused + o.Other
80+
switch {
81+
case t.Verdict == scan.VerdictUnreliable:
82+
p(" Next time: lower -rate or add -auto-rate, try another -dns-server, and rerun; -retry-inconclusive retries the %d names without an answer.", failed)
83+
case failed > 0:
84+
p(" %d names got no answer; -retry-inconclusive looks them up again at the end of the scan.", failed)
85+
}
86+
if t.SkippedCap > 0 {
87+
// A run that ends on -max-queries writes no resume state, so -resume
88+
// is not offered for it (#320). The command line saves one when
89+
// -max-duration runs out (#294); this server's scans never do.
90+
if t.StoppedBy == "duration" {
91+
p(" %d names were not tested because -max-duration ran out; raise it and run the scan again, or continue a command-line run with subenum -resume and the state file it saved.", t.SkippedCap)
92+
} else {
93+
p(" %d names were not tested because -max-queries ran out; raise it and run the scan again.", t.SkippedCap)
94+
}
95+
}
96+
if t.Wildcard {
97+
p(" The domain answers every name (a wildcard), so subenum dropped %d answers matching the wildcard; a real name that answers the same way is dropped too.", o.WildcardFiltered)
98+
}
99+
if t.Takeover > 0 {
100+
p(" %d results have a subdomain-takeover hint: leads to verify by hand, not findings.", t.Takeover)
101+
}
102+
if t.Internal > 0 {
103+
p(" %d public names answer with internal (private, loopback or similar) addresses.", t.Internal)
104+
}
105+
if len(t.AXFRAllowed) > 0 {
106+
p(" Zone transfer (AXFR) was allowed by %s: anyone can list the zone, a misconfiguration to fix.", strings.Join(t.AXFRAllowed, ", "))
107+
}
108+
if t.ZoneDenial == "nsec" {
109+
p(" The zone is signed with plain NSEC, so every name in it can be listed by walking the chain.")
110+
}
111+
for _, src := range t.Sources {
112+
if src.Error != "" {
113+
p(" Passive source %s failed (%s); the scan went on without it.", src.Name, src.Error)
114+
}
115+
if src.Truncated {
116+
p(" Passive source %s stopped at one of its limits: its %d names were scanned, but some hosts may be missing.", src.Name, src.Names)
117+
}
118+
}
119+
if t.Permutation != nil {
120+
p(" Permutation pass: %d candidates from %d seeds, %d found.", t.Permutation.Candidates, t.Permutation.Seeds, t.Permutation.Found)
121+
}
122+
}

0 commit comments

Comments
 (0)