|
| 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