Skip to content

Commit 27ccdeb

Browse files
committed
MCP: add a diff tool that compares two sets of results (#333)
An agent could scan but not ask what changed since an earlier scan, although the CLI and library could. subenum mcp offers a read-only diff tool, always on like explain_stats. It takes the previous and current results as text (a results file in any format, a scan report, or its results array), never as paths, and returns added, missing and changed names with their records, sending no DNS query. It shares parseBaseline and compareBaselines with subenum diff, so both use the CNAME-aware record comparison. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Fixes #333
1 parent a8c869c commit 27ccdeb

10 files changed

Lines changed: 378 additions & 46 deletions

File tree

‎CHANGELOG.md‎

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

1010
### Added
11+
- `subenum mcp` offers a read-only `diff` tool that compares two result sets without sending a DNS query: `previous` and `current` each take a `scan` or `lab_scan` report (or its `results` array) or the contents of a results file in any format, and an optional `types` limits the record types compared. It returns `added`, `missing` and `changed` names with their records, as `structuredContent` too, compared as `subenum diff -records` does, so CDN address rotation behind an unchanged CNAME is not a change; missing names are marked unverified. Its input is bounded by the server's 16 MiB message limit, as `explain_stats`'s is (#333).
1112
- `subenum diff [-records] [-type A,AAAA,CNAME] [-format text|json|jsonl|csv] <previous> <current>` compares two saved results files, in any format subenum writes, without sending a DNS query: `+` for names only in the second file, `-` for names only in the first, and with `-records` `~` for names whose records differ, compared as `-diff-records` does. In JSON, JSONL and CSV the `change` is `added`, `missing` or `changed`; a name is `missing` rather than `removed` because nothing was looked up to show it is gone. It exits `4` when the files differ, and is in the shell completions and the man page (#310).
1213
- `-resume` accepts the pacing flags `-rate`, `-rate-per-resolver`, `-t`, `-timeout`, `-attempts`, `-auto-rate`, `-no-abort` and `-max-duration` next to the state file, so a scan stopped because timeouts piled up can continue at a gentler rate instead of the one that caused them. They apply over the saved command line, a changed value of one is no longer a reason to refuse the resume, and the next state file records them. Flags that change the candidates or the wildcard check stay refused (#309).
1314
- Library: a `KindError` event has `Fatal` set when it ends the scan (the reliability guard's warning under `NoAbort` is the one error without it), and `KindDone` has `Failed` set when the scan failed. The CLI, the TUI, `Scan` and `subenum mcp` now read these instead of each working it out from the errors seen and the no-abort setting; exit codes, `Scan` errors and verdicts are unchanged (#308).

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -639,7 +639,7 @@ API reference and runnable examples: [pkg.go.dev/github.com/TMHSDigital/subenum/
639639
claude mcp add subenum -- subenum mcp -allow example.com
640640
```
641641

642-
It offers `lab_scan` (the lab scenarios, on a local DNS server, always safe), `scan` (only for domains in `-allow` and their subdomains) and `explain_stats` (reads a `-stats` report back in plain language). The operator sets the resolver, rate and budgets; the model can ask for a smaller `max_queries`, never a larger one, and can never pick a resolver. Every scan returns a verdict that tells the agent whether a missing name can be trusted to be absent. See the [MCP page](https://tmhsdigital.github.io/subenum/mcp.html).
642+
It offers `lab_scan` (the lab scenarios, on a local DNS server, always safe), `scan` (only for domains in `-allow` and their subdomains) `explain_stats` (reads a `-stats` report back in plain language) and `diff` (compares two result sets without a DNS query). The operator sets the resolver, rate and budgets; the model can ask for a smaller `max_queries`, never a larger one, and can never pick a resolver. Every scan returns a verdict that tells the agent whether a missing name can be trusted to be absent. See the [MCP page](https://tmhsdigital.github.io/subenum/mcp.html).
643643

644644
<br>
645645

‎docs/ARCHITECTURE.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -58,12 +58,12 @@ internal/cli/config.go - config file and SUBENUM_* environment defaults,
5858
internal/cli/ct.go - -ct / -sources: passive source names as extra candidates
5959
internal/cli/axfr.go - -axfr: zone transfer names as extra candidates, with resume and messages
6060
internal/axfr/axfr.go - Try: AXFR from each name server and the denial probe (-axfr, subenum.ProbeZone)
61-
internal/cli/diff.go - -diff / -diff-records: compare against a previous results file; runDiff: the diff subcommand
61+
internal/cli/diff.go - -diff / -diff-records: compare against a previous results file; runDiff: the diff subcommand; compareBaselines, shared with the MCP diff tool
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
6464
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
65+
internal/cli/mcp_tools.go - the lab_scan, scan, explain_stats and diff tools: input schemas, argument checks, the allow-list and caps
66+
internal/cli/mcp_report.go - the scan and diff reports the tools return, the scan verdict and their outputSchemas
6767
internal/cli/permute.go - -permute / -seeds: the permutation pass
6868
internal/cli/resume.go - -resume / -state: save and replay an interrupted run
6969
internal/cli/results.go - resultLog: a target's results, kept for -permute seeds and -diff

‎docs/mcp.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,19 @@ the contents of a `-stats` file, or `-format jsonl` output, which ends with the
4747
same summary. It says how far the results can be trusted, why, and what to
4848
change next time.
4949

50+
**`diff`** compares two result sets without sending a DNS query, as
51+
[`subenum diff -records`](monitoring.html) does. `previous` and `current` each
52+
take a `scan` or `lab_scan` report (or its `results` array) or the contents of
53+
a results file in any output format; `types` limits which record types count
54+
for a change. It returns `added`, `missing` and `changed` names with their
55+
records (and `previous_records` for a changed name), as `structuredContent`
56+
too. When either side has a CNAME, only the CNAME targets are compared, so CDN
57+
address rotation is not reported as a change. Names in `previous` but not in
58+
`current` are called missing, not removed: nothing was looked up, so they are
59+
unverified. A text-format result set has no records, so `records_compared` is
60+
then false and `changed` is empty. Like `explain_stats`, it takes contents,
61+
not paths, and one call is bounded by the server's 16 MiB message limit.
62+
5063
`lab_scan` and `scan` return JSON with the names found and their records, how
5164
every lookup ended, any notices, and the scan's verdict. Both declare it as an
5265
`outputSchema`, and send it as `structuredContent` as well as text, so a client
@@ -70,7 +83,7 @@ these stays within `max_queries` and `-max-duration`.
7083
## Running it
7184

7285
```bash
73-
subenum mcp # lab_scan and explain_stats only
86+
subenum mcp # lab_scan, explain_stats and diff only
7487
subenum mcp -allow example.com,example.org # adds scan, for these domains
7588
```
7689

‎internal/cli/diff.go‎

Lines changed: 54 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,11 @@ func loadBaseline(path string) (baseline, error) {
5959
if err != nil {
6060
return baseline{}, err
6161
}
62+
return parseBaseline(data)
63+
}
64+
65+
// parseBaseline is loadBaseline on a results file's contents.
66+
func parseBaseline(data []byte) (baseline, error) {
6267
b := baseline{names: map[string]struct{}{}, records: map[string][]dns.Record{}}
6368
add := func(name string, records ...dns.Record) string {
6469
name = diff.Name(name)
@@ -187,63 +192,78 @@ func runDiff(args []string, stdout, stderr io.Writer) int {
187192
out.SetPlain(true)
188193
out.SetDiff(true)
189194
out.SetShowRecords(*records)
190-
compare := *records
191-
if compare && (!prev.hasRecords || !cur.hasRecords) {
195+
d := compareBaselines(prev, cur, *records, types)
196+
if *records && !d.compared {
192197
out.Info("Note: -records needs JSON, JSONL or CSV files; comparing names only")
193-
compare = false
194198
}
195199

196-
sorted := func(m map[string]struct{}) []string {
197-
names := make([]string, 0, len(m))
198-
for name := range m {
199-
names = append(names, name)
200-
}
201-
sort.Strings(names)
202-
return names
203-
}
204200
emit := func(name, change string, recs, previous []dns.Record) {
205201
if recs == nil {
206202
recs = []dns.Record{}
207203
}
208204
out.Emit(output.Result{Result: scan.Result{Subdomain: name, Records: recs}, Change: change, PreviousRecords: previous})
209205
}
210-
var added, missing, changed int
211-
for _, name := range sorted(cur.names) {
212-
if _, ok := prev.names[name]; !ok {
213-
added++
214-
emit(name, "added", cur.records[name], nil)
215-
}
206+
for _, name := range d.added {
207+
emit(name, "added", cur.records[name], nil)
216208
}
217-
if compare {
218-
for _, name := range sorted(cur.names) {
219-
old, ok := prev.records[name]
220-
if _, seen := prev.names[name]; seen && ok && diff.RecordsChanged(old, cur.records[name], types) {
221-
changed++
222-
emit(name, "changed", cur.records[name], old)
223-
}
224-
}
209+
for _, name := range d.changed {
210+
emit(name, "changed", cur.records[name], prev.records[name])
225211
}
226-
for _, name := range sorted(prev.names) {
227-
if _, ok := cur.names[name]; !ok {
228-
missing++
229-
emit(name, "missing", prev.records[name], nil)
230-
}
212+
for _, name := range d.missing {
213+
emit(name, "missing", prev.records[name], nil)
231214
}
232215
if err := out.Finish(); err != nil {
233216
out.Error("writing output: %v", err)
234217
return exitFailure
235218
}
236-
summary := fmt.Sprintf("%d added, %d missing", added, missing)
237-
if compare {
238-
summary += fmt.Sprintf(", %d changed", changed)
219+
summary := fmt.Sprintf("%d added, %d missing", len(d.added), len(d.missing))
220+
if d.compared {
221+
summary += fmt.Sprintf(", %d changed", len(d.changed))
239222
}
240223
out.Info("%s", summary)
241-
if added+missing+changed > 0 {
224+
if len(d.added)+len(d.missing)+len(d.changed) > 0 {
242225
return exitChanges
243226
}
244227
return exitOK
245228
}
246229

230+
// baselineDiff is how two results files differ, each list sorted: names only
231+
// in current, names only in previous, and names in both whose records differ.
232+
// compared says whether records were compared at all.
233+
type baselineDiff struct {
234+
added, missing, changed []string
235+
compared bool
236+
}
237+
238+
// compareBaselines compares two results files (subenum diff and the MCP diff
239+
// tool). With records, names in both are compared record by record over types
240+
// (every type when empty), as -diff-records does, when both files have
241+
// records.
242+
func compareBaselines(prev, cur baseline, records bool, types []string) baselineDiff {
243+
sorted := func(m map[string]struct{}) []string {
244+
names := make([]string, 0, len(m))
245+
for name := range m {
246+
names = append(names, name)
247+
}
248+
sort.Strings(names)
249+
return names
250+
}
251+
d := baselineDiff{compared: records && prev.hasRecords && cur.hasRecords}
252+
for _, name := range sorted(cur.names) {
253+
if _, seen := prev.names[name]; !seen {
254+
d.added = append(d.added, name)
255+
} else if old, ok := prev.records[name]; d.compared && ok && diff.RecordsChanged(old, cur.records[name], types) {
256+
d.changed = append(d.changed, name)
257+
}
258+
}
259+
for _, name := range sorted(prev.names) {
260+
if _, ok := cur.names[name]; !ok {
261+
d.missing = append(d.missing, name)
262+
}
263+
}
264+
return d
265+
}
266+
247267
// observe records a found name and says how it differs from the baseline:
248268
// "added", "changed" (with the baseline's records), or "" for unchanged.
249269
func (d *differ) observe(name string, records []dns.Record) (change string, previous []dns.Record) {

‎internal/cli/mcp.go‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ func parseMCPFlags(args []string, stderr io.Writer) (cfg mcpConfig, code int, ok
118118
fs.SetOutput(stderr)
119119
var allow, sources string
120120
var timeoutMs int
121-
fs.StringVar(&allow, "allow", "", "Comma-separated domains the scan tool may enumerate, each with its subdomains. Without it only lab_scan and explain_stats are offered")
121+
fs.StringVar(&allow, "allow", "", "Comma-separated domains the scan tool may enumerate, each with its subdomains. Without it only lab_scan, explain_stats and diff are offered")
122122
fs.StringVar(&cfg.dnsServer, "dns-server", DefaultDNSServer, "Resolver for live scans: ip:port, tls://host or https://host/path")
123123
fs.IntVar(&cfg.maxQueries, "max-queries", defaultMCPMaxQueries, "Most candidate names one tool call may test; a call can ask for fewer")
124124
fs.IntVar(&cfg.rate, "rate", defaultMCPRate, "DNS queries per second for live scans")
@@ -129,7 +129,7 @@ func parseMCPFlags(args []string, stderr io.Writer) (cfg mcpConfig, code int, ok
129129
fs.Usage = func() {
130130
_, _ = fmt.Fprintf(stderr, "Usage: %s mcp [flags]\n\n", ProgramName)
131131
_, _ = fmt.Fprintln(stderr, "Serves subenum to AI agents over the Model Context Protocol (stdio).")
132-
_, _ = fmt.Fprintln(stderr, "Tools: lab_scan (local lab zones only), scan (domains in -allow only), explain_stats.")
132+
_, _ = fmt.Fprintln(stderr, "Tools: lab_scan (local lab zones only), scan (domains in -allow only), explain_stats, diff.")
133133
_, _ = fmt.Fprintln(stderr, "Only allow domains you own or have permission to test.")
134134
_, _ = fmt.Fprintln(stderr)
135135
fs.PrintDefaults()
@@ -209,8 +209,9 @@ func mcpServer(cfg mcpConfig) *mcp.Server {
209209
instructions += "Live scanning is off: the operator allowed no domains. "
210210
}
211211
instructions += "Every scan returns a verdict: when it is not \"complete\", a name missing from the results may still exist. " +
212-
"explain_stats explains a run-quality report from the subenum command line (-stats)."
213-
tools = append(tools, explainStatsTool())
212+
"explain_stats explains a run-quality report from the subenum command line (-stats). " +
213+
"diff compares two result sets (a scan report or a results file) without a DNS query: use it to say what changed since an earlier scan."
214+
tools = append(tools, explainStatsTool(), diffTool())
214215
return &mcp.Server{Name: ProgramName, Version: resolveVersion(), Instructions: instructions, Tools: tools}
215216
}
216217

‎internal/cli/mcp_report.go‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import (
66
"fmt"
77
"strings"
88

9+
"github.com/TMHSDigital/subenum/internal/dns"
910
"github.com/TMHSDigital/subenum/internal/mcp"
1011
"github.com/TMHSDigital/subenum/pkg/subenum"
1112
)
@@ -134,6 +135,92 @@ func (r *mcpReport) result() mcp.Result {
134135
return mcp.Result{Text: string(b), IsError: r.Error != "", Structured: r}
135136
}
136137

138+
// mcpDiffReport is what diff returns, as JSON (#333).
139+
type mcpDiffReport struct {
140+
Added []mcpDiffName `json:"added"`
141+
Missing []mcpDiffName `json:"missing"`
142+
Changed []mcpDiffName `json:"changed"`
143+
RecordsCompared bool `json:"records_compared"`
144+
Notes []string `json:"notes"`
145+
}
146+
147+
// mcpDiffName is one name diff reports, with its records in mcpResult's
148+
// "TYPE value" form: current records for added and changed names, previous
149+
// records for missing ones.
150+
type mcpDiffName struct {
151+
Name string `json:"name"`
152+
Records []string `json:"records"`
153+
PreviousRecords []string `json:"previous_records,omitempty"`
154+
}
155+
156+
// mcpDiff compares two result sets for the diff tool.
157+
func mcpDiff(prev, cur baseline, types []string) *mcpDiffReport {
158+
d := compareBaselines(prev, cur, true, types)
159+
strs := func(recs []dns.Record) []string {
160+
out := []string{}
161+
for _, r := range recs {
162+
out = append(out, r.Type+" "+r.Value)
163+
}
164+
return out
165+
}
166+
list := func(names []string, records map[string][]dns.Record, previous map[string][]dns.Record) []mcpDiffName {
167+
out := []mcpDiffName{}
168+
for _, name := range names {
169+
n := mcpDiffName{Name: name, Records: strs(records[name])}
170+
if previous != nil {
171+
n.PreviousRecords = strs(previous[name])
172+
}
173+
out = append(out, n)
174+
}
175+
return out
176+
}
177+
r := &mcpDiffReport{
178+
Added: list(d.added, cur.records, nil),
179+
Missing: list(d.missing, prev.records, nil),
180+
Changed: list(d.changed, cur.records, prev.records),
181+
RecordsCompared: d.compared,
182+
Notes: []string{"Missing names were in previous but not in current. Nothing was looked up, so they are unverified: " +
183+
"a name may be missing because the later scan did not try it or did not complete, not because it is gone."},
184+
}
185+
if !d.compared {
186+
r.Notes = append(r.Notes, "Records were not compared because a result set has none (text format): changed is empty.")
187+
}
188+
return r
189+
}
190+
191+
func (r *mcpDiffReport) result() mcp.Result {
192+
b, err := json.MarshalIndent(r, "", " ")
193+
if err != nil {
194+
return mcp.Errorf("encoding the report: %v", err)
195+
}
196+
return mcp.Result{Text: string(b), Structured: r}
197+
}
198+
199+
// mcpDiffSchema is diff's outputSchema: mcpDiffReport as JSON Schema.
200+
// TestMCPDiffSchemaCoversTheReport keeps the two in step.
201+
var mcpDiffSchema = json.RawMessage(`{
202+
"type": "object",
203+
"properties": {
204+
"added": {"type": "array", "items": ` + mcpDiffNameSchema + `, "description": "names in current but not in previous"},
205+
"missing": {"type": "array", "items": ` + mcpDiffNameSchema + `, "description": "names in previous but not in current; unverified, since nothing was looked up"},
206+
"changed": {"type": "array", "items": ` + mcpDiffNameSchema + `, "description": "names in both whose records differ"},
207+
"records_compared": {"type": "boolean", "description": "false when a result set has no records, so changed is empty"},
208+
"notes": {"type": "array", "items": {"type": "string"}}
209+
},
210+
"required": ["added", "missing", "changed", "records_compared", "notes"]
211+
}`)
212+
213+
// mcpDiffNameSchema is mcpDiffName as JSON Schema.
214+
const mcpDiffNameSchema = `{
215+
"type": "object",
216+
"properties": {
217+
"name": {"type": "string"},
218+
"records": {"type": "array", "items": {"type": "string"}, "description": "\"TYPE value\": current records, or previous ones for a missing name"},
219+
"previous_records": {"type": "array", "items": {"type": "string"}, "description": "changed names only"}
220+
},
221+
"required": ["name", "records"]
222+
}`
223+
137224
// mcpReportSchema is the outputSchema of scan and lab_scan: mcpReport as
138225
// JSON Schema (#270). TestMCPReportSchemaCoversTheReport keeps the two in
139226
// step.

0 commit comments

Comments
 (0)