Skip to content

Commit 4c7f317

Browse files
TMHSDigitalclaude
andcommitted
feat(mcp): subenum mcp serves budgeted scans to AI agents (#131)
subenum mcp is a Model Context Protocol server on stdio with three tools: lab_scan scans the compiled-in lab scenarios on a loopback DNS server, so it is always safe; scan is offered only with -allow and refuses any domain outside the allow-list; explain_stats reads a -stats report (or jsonl output) back in plain language. The operator sets the resolver, rate, timeout and budgets on the command line, and the caps cannot be turned off. A call can lower max_queries, never raise it, unknown arguments such as a resolver are refused, and calls run one at a time so parallel calls cannot multiply the budget. Each scan returns its results with a verdict (complete, degraded, unreliable or not_run). The JSON-RPC layer is a small hand-written internal/mcp package (initialize with version negotiation, ping, tools/list, tools/call, notifications/cancelled), so there is no new dependency. Fixes #131 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 0160819 commit 4c7f317

14 files changed

Lines changed: 1444 additions & 5 deletions

‎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` 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`). The JSON-RPC layer is a small hand-written `internal/mcp` package, so there is no new dependency (#131).
1112
- `-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).
1213
- `-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).
1314
- `-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).

‎README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -613,6 +613,16 @@ Every zero value in `Config` takes the same default as the CLI, so `Config{Domai
613613

614614
API reference and runnable examples: [pkg.go.dev/github.com/TMHSDigital/subenum/pkg/subenum](https://pkg.go.dev/github.com/TMHSDigital/subenum/pkg/subenum). The package follows semantic versioning from v1.0.0; until then it may change between minor releases, while the CLI stays stable.
615615

616+
### AI agents (MCP)
617+
618+
`subenum mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server on stdio, for AI agents and assistants:
619+
620+
```bash
621+
claude mcp add subenum -- subenum mcp -allow example.com
622+
```
623+
624+
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).
625+
616626
<br>
617627

618628
<details>

‎docs/ARCHITECTURE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ Every package under `internal/` and `pkg/`, summarized from its `// Package` com
3939
| `internal/ct` | Looks up subdomain names in Certificate Transparency logs through crt.sh |
4040
| `internal/passive` | The `Source` interface behind `-sources`, the source registry, and the Wayback Machine source |
4141
| `internal/labzone` | Parses `-simulate-zone` scenario files for lab mode |
42+
| `internal/mcp` | Minimal Model Context Protocol server (JSON-RPC over stdio, tools only) behind `subenum mcp` |
4243
| `internal/dnsserver` | Scriptable local DNS server backing lab mode and the hermetic tests |
4344
| `internal/dnstest` | Runs `internal/dnsserver` for tests: stopped on cleanup, listen failures fail or skip the test |
4445
| `internal/tui` | Bubble Tea terminal UI |
@@ -56,6 +57,7 @@ main_axfr.go - -axfr: zone transfer names as extra candidates
5657
main_diff.go - -diff / -diff-records: compare against a previous results file
5758
main_dryrun.go - -dry-run: print the scan plan and its cost without sending queries
5859
main_lab.go - -simulate-zone: serve a lab scenario on a loopback DNS server
60+
main_mcp.go - subenum mcp: the lab_scan, scan and explain_stats tools, the allow-list and caps
5961
main_permute.go - -permute / -seeds: the permutation pass
6062
main_resume.go - -resume / -state: save and replay an interrupted run
6163
main_summary.go - assemble the run-quality report (-stats, JSONL summary line)
@@ -90,6 +92,7 @@ internal/diff/diff.go - Name, RecordsChanged: the comparison behind -di
9092
internal/ct/ct.go - Client.Names: crt.sh lookup
9193
internal/passive/passive.go - Source, Known, ParseList, New: the -sources registry
9294
internal/passive/wayback.go - Wayback.Names: hostnames from the Wayback Machine's CDX index
95+
internal/mcp/mcp.go - Server.Serve: MCP over stdio (initialize, ping, tools/list, tools/call, cancellation)
9396
pkg/subenum/sources.go - Source, CertificateTransparency, WaybackMachine: Config.Sources
9497
internal/labzone/labzone.go - Load, Parse: lab scenario files
9598
internal/dnsserver/server.go - Listen: scriptable loopback DNS server

‎docs/DEVELOPER_GUIDE.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,7 @@ subenum/
123123
│ ├── dnsserver/ # Scriptable loopback DNS server (UDP, TCP, DoT, DoH)
124124
│ ├── dnstest/ # dnsserver for tests: stops on cleanup, fails the test on error
125125
│ ├── labzone/ # -simulate-zone scenario parser and answer logic
126+
│ ├── mcp/ # MCP server over stdio (JSON-RPC, tools only) for subenum mcp
126127
│ ├── output/
127128
│ │ ├── writer.go # Thread-safe output (results→stdout, rest→stderr)
128129
│ │ ├── file.go # File: atomically replaced -o results file
@@ -177,6 +178,7 @@ subenum/
177178
├── main_diff.go # -diff / -diff-records against a previous results file
178179
├── main_dryrun.go # -dry-run: the scan plan and its cost, no queries sent
179180
├── main_lab.go # -simulate-zone: serve a lab scenario locally
181+
├── main_mcp.go # subenum mcp: MCP tools, allow-list and caps
180182
├── main_permute.go # -permute / -seeds: the permutation pass
181183
├── main_resume.go # -resume / -state: save and replay an interrupted run
182184
├── main_summary.go # Run-quality report assembly (-stats, JSONL summary line)

‎docs/ROADMAP.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,7 @@ Planned features that make results more trustworthy and the tool easier to get.
3232
Ideas we want, with no date attached.
3333

3434
- Walk NSEC-signed zones (`-nsec-walk`). `-axfr` already tries zone transfers ([#85](https://github.com/TMHSDigital/subenum/issues/85)) and reports walkable zones ([#234](https://github.com/TMHSDigital/subenum/issues/234)).
35-
- Discoverability: demo GIF and launch posts ([#74](https://github.com/TMHSDigital/subenum/issues/74)).
36-
- An MCP server mode for budgeted scans by AI agents ([#131](https://github.com/TMHSDigital/subenum/issues/131)).
35+
- Discoverability: demo GIF and launch posts ([#74](https://github.com/TMHSDigital/subenum/issues/74)), and MCP registry listings for `subenum mcp`.
3736

3837
## What 1.0 means
3938

‎docs/_data/nav.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@
2222
url: /docker.html
2323
- title: Go library
2424
url: /library.html
25+
- title: AI agents (MCP)
26+
url: /mcp.html
2527

2628
- section: Internals
2729
pages:

‎docs/cli.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,12 @@ subenum [flags] <domain>
1111
subenum [flags] -dL domains.txt
1212
subenum completion bash|zsh|fish|powershell
1313
subenum man
14+
subenum mcp [-allow domains] [flags]
1415
```
1516

1617
Flags may appear before or after the domain. The domain is normalized to its host name before scanning: a URL's scheme and path, a `:port` and a leading `*.` are removed and an internationalized name becomes punycode, so `https://app.example.com/login` scans `app.example.com`, not `example.com`.
1718

18-
`completion` prints a shell completion script and `man` prints the man page, both generated from the same flags; release archives ship them under `completions/` and `man/`.
19+
`completion` prints a shell completion script and `man` prints the man page, both generated from the same flags; release archives ship them under `completions/` and `man/`. `mcp` serves subenum to AI agents over the Model Context Protocol, within the domains, resolver and budgets you give it; see [AI agents (MCP)](mcp.html) for its flags.
1920

2021
## Flags
2122

‎docs/mcp.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
layout: default
3+
title: AI agents (MCP)
4+
---
5+
6+
# AI agents (MCP)
7+
8+
`subenum mcp` serves subdomain enumeration to AI agents and assistants over the
9+
[Model Context Protocol](https://modelcontextprotocol.io), on standard input and
10+
output. The operator who starts the server decides everything that matters for
11+
safety. The model chooses only what to scan within those limits.
12+
13+
| You decide, on the command line | The model decides, per call |
14+
| :--- | :--- |
15+
| Which domains a live scan may target (`-allow`) | A domain within the allow-list |
16+
| The resolver (`-dns-server`) and the lookup timeout (`-timeout`) | The words to try, and the record types |
17+
| The query rate (`-rate`) | A smaller `max_queries`, never a larger one |
18+
| The most names one call may test (`-max-queries`) and its time budget (`-max-duration`) | For lab scans only: the scenario, a rate, and `force` |
19+
20+
Tool calls run one at a time, so a model cannot multiply the budget by calling
21+
in parallel, and arguments the tools do not define (a resolver, say) are
22+
refused rather than ignored.
23+
24+
## Tools
25+
26+
**`lab_scan`** scans `lab.example` in one of the [lab scenarios](labs.html),
27+
compiled into the binary and answered by a DNS server on the loopback
28+
interface. No traffic leaves the machine, so it is always offered and always
29+
safe. It is the place for an agent to learn what wildcards, rate limits and a
30+
failing resolver do to a scan.
31+
32+
**`scan`** enumerates a real domain through the operator's resolver. It is
33+
offered only when `-allow` names at least one domain, and it refuses any domain
34+
that is not an allowed one or a subdomain of one. Only allow domains you own or
35+
have permission to test.
36+
37+
**`explain_stats`** explains a run-quality report from the command line: pass
38+
the contents of a `-stats` file, or `-format jsonl` output, which ends with the
39+
same summary. It says how far the results can be trusted, why, and what to
40+
change next time.
41+
42+
`lab_scan` and `scan` return JSON with the names found and their records, how
43+
every lookup ended, any notices, and the scan's verdict:
44+
45+
| Verdict | Meaning for the agent |
46+
| :--- | :--- |
47+
| `complete` | A name missing from the results most likely does not exist. |
48+
| `degraded` | Some names were not tested or got no answer, so a missing name may still exist. |
49+
| `unreliable` | Too many lookups failed: a missing name means nothing. |
50+
| `not_run` | The scan stopped before testing any name, for example on a wildcard zone; `error` says why. |
51+
52+
## Running it
53+
54+
```bash
55+
subenum mcp # lab_scan and explain_stats only
56+
subenum mcp -allow example.com,example.org # adds scan, for these domains
57+
```
58+
59+
| Flag | Default | Meaning |
60+
| :--- | :--- | :--- |
61+
| `-allow` | none | Comma-separated domains `scan` may enumerate, each with its subdomains |
62+
| `-dns-server` | `8.8.8.8:53` | Resolver for live scans: `ip:port`, `tls://host` or `https://host/path` |
63+
| `-rate` | 20 | DNS queries per second for live scans |
64+
| `-max-queries` | 1000 | Most candidate names one call may test |
65+
| `-max-duration` | 2m | Longest one call may scan |
66+
| `-timeout` | 1000 | Live-scan lookup timeout in milliseconds |
67+
68+
The caps cannot be turned off: `-rate`, `-max-queries` and `-max-duration` must
69+
be positive.
70+
71+
Most MCP clients take a command and its arguments. For example, in a client
72+
configuration file:
73+
74+
```json
75+
{
76+
"mcpServers": {
77+
"subenum": {
78+
"command": "subenum",
79+
"args": ["mcp", "-allow", "example.com", "-rate", "20"]
80+
}
81+
}
82+
}
83+
```
84+
85+
With Claude Code: `claude mcp add subenum -- subenum mcp -allow example.com`.
86+
87+
The server speaks MCP revisions 2025-06-18, 2025-03-26 and 2024-11-05, offers
88+
tools only, and writes nothing but protocol messages to standard output.

0 commit comments

Comments
 (0)