knock 1.0.0 → 1.1.0

package/README.md

@@ -7,7 +7,8 @@ Transparency logs** (passive, via [crt.sh](https://crt.sh)) and a bundled
 **31k-entry wordlist** (active DNS brute force), detects wildcard DNS so you
 don't drown in false positives, and verifies everything with real lookups.
 
-Zero runtime dependencies. Great for attack-surface audits, pen-test recon,
+Use it as a CLI, a library, or an **MCP server** for AI agents. Zero
+runtime dependencies. Great for attack-surface audits, pen-test recon,
 or checking what a new client actually has exposed.
 
 [![npm version](https://img.shields.io/npm/v/knock.svg)](https://www.npmjs.com/package/knock)
@@ -20,6 +21,12 @@ npm install -g knock   # CLI
 npm install knock      # library
 ```
 
+Or run the CLI without installing:
+
+```bash
+npx knock example.com
+```
+
 Requires Node.js >= 22.
 
 ## CLI
@@ -50,6 +57,7 @@ Useful flags:
 | `-w, --web` | probe http/https on each found host |
 | `-j, --json` | full report as JSON |
 | `-q, --quiet` | hostnames only (pipe-friendly) |
+| `--mcp` | run as an MCP server on stdio (see below) |
 
 Found hosts stream to stdout as they resolve; diagnostics go to stderr, so
 `knock -q example.com | sort` does what you'd hope.
@@ -105,6 +113,43 @@ popularity-ordered) and `wordlists.org`, and helpers `loadWordlist(path)` /
 `parseWordlist(text)` / `normalizeDomain(input)` are exported too. Full
 TypeScript types ship with the package.
 
+## MCP server
+
+knock ships a [Model Context Protocol](https://modelcontextprotocol.io)
+server, so AI agents (Claude Code, Claude Desktop, Cursor, …) can enumerate
+subdomains directly. It runs over stdio:
+
+```bash
+claude mcp add knock -- npx -y knock --mcp
+```
+
+Or in any client's JSON config:
+
+```json
+{
+  "mcpServers": {
+    "knock": { "command": "npx", "args": ["-y", "knock", "--mcp"] }
+  }
+}
+```
+
+| Tool | Does |
+| --- | --- |
+| `knock_enumerate` | full run (CT + brute force, or `passive: true`), returns the report |
+| `knock_ct_lookup` | Certificate Transparency names only — one HTTPS request, no DNS |
+| `knock_registrable_domain` | offline Public Suffix List lookup |
+
+All tools are read-only, return structured JSON, stream progress per found
+host, and honor cancellation. The server is implemented without the MCP SDK,
+so the zero-dependency promise holds.
+
+## AI docs
+
+[`llms.txt`](llms.txt) is a compact, agent-oriented reference to the whole
+API (library, CLI and MCP tools) and ships in the npm package at
+`node_modules/knock/llms.txt`. Contributors' coding agents get repo
+conventions from [`AGENTS.md`](AGENTS.md).
+
 ## How it works
 
 0. **Public Suffix List** — input like `https://deep.www.example.co.uk/x` is

package/dist/cli.js

@@ -26,6 +26,7 @@ Options
   -s, --server <ip>           DNS server to use, repeatable
   -6, --ipv6                  also resolve AAAA records
   -w, --web                   probe http/https on found hosts
+      --mcp                   run as an MCP server on stdio (for AI agents)
   -j, --json                  print the full report as JSON
   -q, --quiet                 hostnames only, no summary
   -h, --help                  show this help
@@ -35,6 +36,7 @@ Examples
   knock example.com
   knock --passive --json example.com
   knock -l org -s 1.1.1.1 -c 128 example.com
+  claude mcp add knock -- npx -y knock --mcp
 
 Only scan domains you own or are authorized to assess.`;
 function fail(message) {
@@ -56,6 +58,7 @@ function parseCliArgs() {
                 server: { type: 'string', short: 's', multiple: true },
                 ipv6: { type: 'boolean', short: '6', default: false },
                 web: { type: 'boolean', short: 'w', default: false },
+                mcp: { type: 'boolean', default: false },
                 json: { type: 'boolean', short: 'j', default: false },
                 quiet: { type: 'boolean', short: 'q', default: false },
                 help: { type: 'boolean', short: 'h', default: false },
@@ -76,6 +79,11 @@ if (flags.version) {
     console.log(version);
     process.exit(0);
 }
+if (flags.mcp) {
+    const { serveMcp } = await import('./mcp.js');
+    await serveMcp();
+    process.exit(0);
+}
 if (domains.length === 0) {
     fail('no domain given (try: knock example.com, or --help)');
 }

package/dist/mcp.d.ts

@@ -0,0 +1,14 @@
+import type { Readable, Writable } from 'node:stream';
+import type { KnockOptions } from './index.ts';
+/** Protocol revisions this server speaks, newest first. */
+export declare const MCP_PROTOCOL_VERSIONS: string[];
+export interface McpServerOptions {
+    input?: Readable;
+    output?: Writable;
+    /** Merged into every knock() / certSubdomains() call, mainly for testing (resolver, fetch, psl). */
+    knockOptions?: Pick<KnockOptions, 'resolver' | 'fetch' | 'psl'>;
+}
+/**
+ * Serve MCP over stdio (or the given streams). Resolves when the input ends.
+ */
+export declare function serveMcp(options?: McpServerOptions): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,319 @@
+/**
+ * knock as a Model Context Protocol server over stdio — newline-delimited
+ * JSON-RPC 2.0, implemented directly so the package stays dependency-free.
+ */
+import { createInterface } from 'node:readline';
+import { readFileSync } from 'node:fs';
+import process from 'node:process';
+import { knock, certSubdomains, normalizeDomain, wordlists, loadPublicSuffixList, getPublicSuffix, getRegistrableDomain, } from './index.js';
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+/** Protocol revisions this server speaks, newest first. */
+export const MCP_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+class InvalidParams extends Error {
+}
+const INSTRUCTIONS = `knock enumerates subdomains of a domain using Certificate Transparency logs (passive, via crt.sh) and a wordlist DNS brute force with wildcard detection.
+Prefer knock_ct_lookup or knock_enumerate with passive: true for a quick, low-noise look; a full brute force sends ~31k DNS queries and takes roughly 30-90 seconds.
+Only enumerate domains the user owns or is authorized to assess.`;
+const domainProperty = {
+    type: 'string',
+    description: 'Domain, hostname or URL, e.g. "example.com" or "https://www.example.co.uk/path".',
+};
+const TOOLS = [
+    {
+        name: 'knock_enumerate',
+        title: 'Enumerate subdomains',
+        description: 'Find subdomains of a domain. Combines Certificate Transparency logs with a DNS brute force over a bundled wordlist, filters wildcard DNS, and verifies names with real lookups. Input is reduced to its registrable domain first (www.example.co.uk -> example.co.uk) unless fullHost is set. Returns the full report: results (name, addresses, sources), wildcard, ct (including unresolved CT names), and stats. A full run sends ~31k DNS queries; use passive: true for a CT-only lookup.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                domain: domainProperty,
+                passive: {
+                    type: 'boolean',
+                    description: 'Skip the wordlist brute force; Certificate Transparency only. Default false.',
+                },
+                ct: { type: 'boolean', description: 'Query Certificate Transparency logs. Default true.' },
+                verify: {
+                    type: 'boolean',
+                    description: 'Resolve CT-discovered names over DNS. Default true.',
+                },
+                fullHost: {
+                    type: 'boolean',
+                    description: 'Scan the exact host given instead of its registrable domain. Default false.',
+                },
+                wordlist: {
+                    type: 'string',
+                    enum: ['subs', 'org'],
+                    description: 'Bundled wordlist: "subs" (~31k labels, default) or "org".',
+                },
+                words: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Custom labels to try instead of a bundled wordlist, e.g. ["www", "api"].',
+                },
+                concurrency: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 512,
+                    description: 'Parallel DNS queries. Default 64.',
+                },
+                timeout: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Per-query DNS timeout in milliseconds. Default 5000.',
+                },
+                servers: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'DNS server IPs to query instead of the system resolvers.',
+                },
+                ipv6: { type: 'boolean', description: 'Also resolve AAAA records. Default false.' },
+                web: {
+                    type: 'boolean',
+                    description: 'Probe http/https on each found host and report status codes. Default false.',
+                },
+            },
+            required: ['domain'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    {
+        name: 'knock_ct_lookup',
+        title: 'Certificate Transparency lookup',
+        description: 'List hostnames under a domain that appear in Certificate Transparency logs (crt.sh). Passive: one HTTPS request to crt.sh, no DNS traffic to the target. Names are not verified and may be stale. The domain is used exactly as given (no registrable-domain reduction).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                domain: domainProperty,
+                timeout: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Request timeout in milliseconds. Default 15000.',
+                },
+            },
+            required: ['domain'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    {
+        name: 'knock_registrable_domain',
+        title: 'Registrable domain',
+        description: 'Reduce a hostname or URL to its public suffix and registrable domain using the bundled Public Suffix List, e.g. "a.b.example.co.uk" -> suffix "co.uk", registrable "example.co.uk". Offline; no network access.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                host: domainProperty,
+                icannOnly: {
+                    type: 'boolean',
+                    description: 'Ignore private suffixes like github.io. Default false.',
+                },
+            },
+            required: ['host'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+];
+function optional(args, key, check, expected) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (!check(value))
+        throw new InvalidParams(`"${key}" must be ${expected}`);
+    return value;
+}
+const isBoolean = (v) => typeof v === 'boolean';
+const isString = (v) => typeof v === 'string';
+const isPositiveInteger = (v) => Number.isInteger(v) && v > 0;
+const isStringArray = (v) => Array.isArray(v) && v.every(isString);
+function required(args, key) {
+    const value = optional(args, key, isString, 'a string');
+    if (!value)
+        throw new InvalidParams(`"${key}" is required`);
+    return value;
+}
+/**
+ * Serve MCP over stdio (or the given streams). Resolves when the input ends.
+ */
+export async function serveMcp(options = {}) {
+    const { input = process.stdin, output = process.stdout, knockOptions = {} } = options;
+    const inFlight = new Map();
+    const send = (message) => {
+        output.write(`${JSON.stringify({ jsonrpc: '2.0', ...message })}\n`);
+    };
+    const reply = (id, result) => send({ id, result });
+    const replyError = (id, code, message) => send({ id, error: { code, message } });
+    const toolResult = (data, summary) => ({
+        content: [
+            ...(summary ? [{ type: 'text', text: summary }] : []),
+            { type: 'text', text: JSON.stringify(data) },
+        ],
+        structuredContent: data,
+    });
+    async function callTool(name, args, signal, progress) {
+        switch (name) {
+            case 'knock_enumerate': {
+                const domain = required(args, 'domain');
+                const passive = optional(args, 'passive', isBoolean, 'a boolean') ?? false;
+                const list = optional(args, 'wordlist', isString, 'a string');
+                if (list !== undefined && list !== 'subs' && list !== 'org') {
+                    throw new InvalidParams('"wordlist" must be "subs" or "org"');
+                }
+                const run = {
+                    ...knockOptions,
+                    signal,
+                    ct: optional(args, 'ct', isBoolean, 'a boolean') ?? true,
+                    verify: optional(args, 'verify', isBoolean, 'a boolean') ?? true,
+                    baseDomainOnly: !(optional(args, 'fullHost', isBoolean, 'a boolean') ?? false),
+                    wordlist: wordlists[list ?? 'subs'],
+                    words: passive ? [] : optional(args, 'words', isStringArray, 'an array of strings'),
+                    concurrency: Math.min(optional(args, 'concurrency', isPositiveInteger, 'a positive integer') ?? 64, 512),
+                    timeout: optional(args, 'timeout', isPositiveInteger, 'a positive integer'),
+                    servers: optional(args, 'servers', isStringArray, 'an array of strings'),
+                    family: optional(args, 'ipv6', isBoolean, 'a boolean') ? 'any' : 4,
+                    web: optional(args, 'web', isBoolean, 'a boolean') ?? false,
+                };
+                if (passive && !run.ct)
+                    throw new InvalidParams('passive with ct: false leaves nothing to do');
+                if (run.timeout === undefined)
+                    delete run.timeout;
+                let found = 0;
+                run.onResult = (result) => {
+                    found += 1;
+                    progress(found, result.name);
+                };
+                const report = await knock(domain, run);
+                const { stats, wildcard, ct } = report;
+                const summary = `${report.domain}: ${stats.found} found from ${stats.candidates} candidates` +
+                    (ct.enabled ? `, ${ct.names} CT names (${ct.unresolved.length} unresolved)` : '') +
+                    (wildcard.detected ? `, wildcard DNS detected (${wildcard.addresses.join(', ')})` : '') +
+                    (ct.error ? `, CT lookup failed: ${ct.error}` : '') +
+                    ` in ${(stats.durationMs / 1000).toFixed(1)}s`;
+                return toolResult(report, summary);
+            }
+            case 'knock_ct_lookup': {
+                const domain = normalizeDomain(required(args, 'domain'));
+                const names = await certSubdomains(domain, {
+                    signal,
+                    fetch: knockOptions.fetch,
+                    timeout: optional(args, 'timeout', isPositiveInteger, 'a positive integer'),
+                });
+                return toolResult({ domain, names }, `${names.length} CT names under ${domain}`);
+            }
+            case 'knock_registrable_domain': {
+                const host = normalizeDomain(required(args, 'host'));
+                const icannOnly = optional(args, 'icannOnly', isBoolean, 'a boolean') ?? false;
+                const rules = knockOptions.psl ?? (await loadPublicSuffixList());
+                return toolResult({
+                    host,
+                    publicSuffix: getPublicSuffix(host, rules, { icannOnly }),
+                    registrableDomain: getRegistrableDomain(host, rules, { icannOnly }),
+                });
+            }
+            default:
+                throw new InvalidParams(`unknown tool: ${name}`);
+        }
+    }
+    async function handle(message) {
+        const { id, method } = message;
+        const params = (message.params ?? {});
+        const isRequest = typeof id === 'string' || typeof id === 'number';
+        if (typeof method !== 'string') {
+            // Responses to requests we never send; ignore. Malformed requests get an error.
+            if (isRequest && !('result' in message || 'error' in message)) {
+                replyError(id, -32600, 'invalid request');
+            }
+            return;
+        }
+        if (!isRequest) {
+            if (method === 'notifications/cancelled') {
+                inFlight.get(params.requestId)?.abort(new Error(String(params.reason ?? 'cancelled')));
+            }
+            return;
+        }
+        switch (method) {
+            case 'initialize': {
+                const requested = params.protocolVersion;
+                reply(id, {
+                    protocolVersion: typeof requested === 'string' && MCP_PROTOCOL_VERSIONS.includes(requested)
+                        ? requested
+                        : MCP_PROTOCOL_VERSIONS[0],
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: { name: 'knock', title: 'knock', version },
+                    instructions: INSTRUCTIONS,
+                });
+                return;
+            }
+            case 'ping':
+                reply(id, {});
+                return;
+            case 'tools/list':
+                reply(id, { tools: TOOLS });
+                return;
+            case 'tools/call': {
+                const name = String(params.name ?? '');
+                const args = (params.arguments ?? {});
+                const progressToken = params._meta?.progressToken;
+                const controller = new AbortController();
+                inFlight.set(id, controller);
+                const progress = (count, text) => {
+                    if (progressToken === undefined)
+                        return;
+                    send({
+                        method: 'notifications/progress',
+                        params: { progressToken, progress: count, message: `found ${text}` },
+                    });
+                };
+                try {
+                    reply(id, await callTool(name, args, controller.signal, progress));
+                }
+                catch (error) {
+                    // A cancelled request gets no response, per the spec.
+                    if (controller.signal.aborted)
+                        return;
+                    const text = error instanceof Error ? error.message : String(error);
+                    if (error instanceof InvalidParams && text.startsWith('unknown tool')) {
+                        replyError(id, -32602, text);
+                    }
+                    else {
+                        reply(id, { content: [{ type: 'text', text }], isError: true });
+                    }
+                }
+                finally {
+                    inFlight.delete(id);
+                }
+                return;
+            }
+            default:
+                replyError(id, -32601, `method not found: ${method}`);
+        }
+    }
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    const pending = new Set();
+    for await (const line of lines) {
+        if (line.trim() === '')
+            continue;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            replyError(null, -32700, 'parse error');
+            continue;
+        }
+        if (typeof message !== 'object' || message === null || Array.isArray(message)) {
+            replyError(null, -32600, 'invalid request');
+            continue;
+        }
+        // Requests run concurrently so pings and cancellations stay responsive during a scan.
+        const task = handle(message).catch((error) => {
+            process.stderr.write(`knock mcp: ${error instanceof Error ? error.stack : String(error)}\n`);
+        });
+        pending.add(task);
+        void task.finally(() => pending.delete(task));
+    }
+    for (const controller of inFlight.values())
+        controller.abort(new Error('input closed'));
+    await Promise.allSettled(pending);
+}

package/llms.txt

@@ -0,0 +1,70 @@
+# knock
+
+> Subdomain enumeration for Node.js (>= 22), as a library, a CLI, and an MCP server. Combines Certificate Transparency logs (passive, via crt.sh) with a wordlist DNS brute force (bundled ~31k labels), detects and filters wildcard DNS, and verifies names with real lookups. ESM-only, TypeScript types included, zero runtime dependencies. Only scan domains you own or are authorized to assess.
+
+Install with `npm install knock` (library) or run `npx knock example.com` (CLI). Targets are reduced to their registrable domain via a bundled Public Suffix List before scanning ("https://a.www.example.co.uk/x" -> "example.co.uk") unless told otherwise.
+
+## Library
+
+```js
+import { knock, certSubdomains } from 'knock';
+
+// Full run: CT + wordlist brute force. Takes ~30-90s with the default wordlist.
+const report = await knock('example.com', {
+  concurrency: 64,               // parallel DNS queries
+  onResult: (r) => console.log(r.name), // streamed as found
+});
+
+// Passive only: CT names, verified over DNS, no brute force.
+await knock('example.com', { words: [] });
+
+// Just the CT names, unverified: one HTTPS request, no DNS.
+const names = await certSubdomains('example.com'); // string[], sorted, apex excluded
+```
+
+`knock(domain, options?)` resolves to a `KnockReport`:
+
+```ts
+{
+  domain: string;                              // the domain actually scanned
+  results: { name: string; addresses: string[]; sources: ('wordlist' | 'ct')[];
+             web?: { https: number | null; http: number | null } }[];
+  wildcard: { detected: boolean; addresses: string[] };
+  ct: { enabled: boolean; names: number; unresolved: string[]; error: string | null };
+  stats: { words: number; candidates: number; queried: number; found: number;
+           errors: number; durationMs: number };
+}
+```
+
+Options (all optional): `words` (string[], overrides `wordlist`; `[]` = passive), `wordlist` (file path; default `wordlists.subs`), `ct` (true), `ctTimeout` (15000), `verify` (true; resolve CT names), `concurrency` (64), `timeout` (5000 ms per DNS query), `tries` (2), `servers` (DNS server IPs), `family` (4 | 6 | 'any'; default 4), `wildcardTests` (3; 0 disables), `web` (false; HEAD http/https on found hosts), `webTimeout` (5000), `baseDomainOnly` (true), `icannOnly` (false; ignore private PSL suffixes like github.io), `signal` (AbortSignal), `onResult` (callback), and test injectables `resolver`, `fetch`, `psl`.
+
+Behavior worth knowing:
+- A CT lookup failure does not reject; it is reported in `report.ct.error` and the run continues with the wordlist.
+- Wordlist hits that only return the wildcard DNS answer are dropped; CT-sourced names are kept even under a wildcard.
+- `report.ct.unresolved` lists CT names that no longer resolve (stale or internal hosts).
+- `knock()` rejects with the abort reason when `signal` aborts, and with a `TypeError` for unusable input.
+
+Other exports: `normalizeDomain(input)`, `parseWordlist(text)`, `loadWordlist(path)`, `wordlists` (`{ subs, org }` absolute paths), `getRegistrableDomain(host, rules, { icannOnly })`, `getPublicSuffix(host, rules, opts)`, `loadPublicSuffixList(path?)`, `parsePublicSuffixList(text)`, `publicSuffixListPath`, and all the types (`KnockOptions`, `KnockReport`, `KnockResult`, ...). Default export is `knock`.
+
+## CLI
+
+```
+knock [options] <domain> [domain ...]
+```
+
+`-p/--passive` (CT only), `--no-ct`, `--no-verify`, `--full-host` (skip registrable-domain reduction), `-l/--list <path|subs|org>`, `-c/--concurrency <n>`, `-t/--timeout <ms>`, `-s/--server <ip>` (repeatable), `-6/--ipv6`, `-w/--web`, `-j/--json` (full report), `-q/--quiet` (hostnames only), `--mcp`. Results go to stdout, diagnostics to stderr; exit code 1 if any domain failed.
+
+## MCP server
+
+`knock --mcp` serves the Model Context Protocol over stdio. Register it with, for example, `claude mcp add knock -- npx -y knock --mcp`, or in a JSON client config: `{"command": "npx", "args": ["-y", "knock", "--mcp"]}`.
+
+Tools (all read-only; results include `structuredContent` plus a JSON text block):
+- `knock_enumerate` — full `knock()` run. Args: `domain` (required), `passive`, `ct`, `verify`, `fullHost`, `wordlist` ("subs" | "org"), `words`, `concurrency`, `timeout`, `servers`, `ipv6`, `web`. Returns the `KnockReport`. Sends progress notifications per found host when the call carries a progress token, and supports cancellation.
+- `knock_ct_lookup` — `certSubdomains()`. Args: `domain`, `timeout`. Returns `{ domain, names }`.
+- `knock_registrable_domain` — offline PSL lookup. Args: `host`, `icannOnly`. Returns `{ host, publicSuffix, registrableDomain }`.
+
+## Links
+
+- [README](https://github.com/neopunisher/node-knock#readme): full documentation
+- [Changelog](https://github.com/neopunisher/node-knock/blob/main/CHANGELOG.md)
+- [npm](https://www.npmjs.com/package/knock)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "knock",
-  "version": "1.0.0",
-  "description": "Knock, knock. Who's there? Wordlist-based subdomain enumeration with wildcard DNS detection. Zero dependencies.",
+  "version": "1.1.0",
+  "description": "Knock, knock. Who's there? Subdomain enumeration via Certificate Transparency and wordlist DNS brute force, with wildcard detection. CLI, library and MCP server. Zero dependencies.",
   "keywords": [
     "domain",
     "subdomain",
@@ -12,7 +12,10 @@
     "pentest",
     "security",
     "util",
-    "utility"
+    "utility",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol"
   ],
   "author": "Carter Cole <node@cartercole.com>",
   "license": "MIT",
@@ -39,7 +42,8 @@
   },
   "files": [
     "dist/",
-    "lists/"
+    "lists/",
+    "llms.txt"
   ],
   "engines": {
     "node": ">=22"