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 27ccdeb
Browse filesBrowse the repository at this point in the historyBrowse files
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
Copy file name to clipboardExpand all lines: CHANGELOG.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,6 +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` 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).
11
12
-`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).
12
13
-`-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).
13
14
- 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).
Copy file name to clipboardExpand all lines: README.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
@@ -639,7 +639,7 @@ API reference and runnable examples: [pkg.go.dev/github.com/TMHSDigital/subenum/
639
639
claude mcp add subenum -- subenum mcp -allow example.com
640
640
```
641
641
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).
internal/cli/ct.go - -ct / -sources: passive source names as extra candidates
59
59
internal/cli/axfr.go - -axfr: zone transfer names as extra candidates, with resume and messages
60
60
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
62
62
internal/cli/dryrun.go - -dry-run: print the scan plan and its cost without sending queries
63
63
internal/cli/lab.go - -simulate-zone: serve a lab scenario on a loopback DNS server
64
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, scanand 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
67
67
internal/cli/permute.go - -permute / -seeds: the permutation pass
68
68
internal/cli/resume.go - -resume / -state: save and replay an interrupted run
69
69
internal/cli/results.go - resultLog: a target's results, kept for -permute seeds and -diff
fs.StringVar(&allow, "allow", "", "Comma-separated domains the scan tool may enumerate, each with its subdomains. Without it only lab_scanand 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")
122
122
fs.StringVar(&cfg.dnsServer, "dns-server", DefaultDNSServer, "Resolver for live scans: ip:port, tls://host or https://host/path")
123
123
fs.IntVar(&cfg.maxQueries, "max-queries", defaultMCPMaxQueries, "Most candidate names one tool call may test; a call can ask for fewer")
124
124
fs.IntVar(&cfg.rate, "rate", defaultMCPRate, "DNS queries per second for live scans")
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
+
returnr
189
+
}
190
+
191
+
func (r*mcpDiffReport) result() mcp.Result {
192
+
b, err:=json.MarshalIndent(r, "", " ")
193
+
iferr!=nil {
194
+
returnmcp.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
+
varmcpDiffSchema=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"},
0 commit comments