knock 0.1.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2011-2026 Carter Cole
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,17 +1,195 @@
-NPM Knock
-=========
+# knock
 
-Knock, Knock whos there? Great for pen-testing or for doing an audit of a new client or getting competitive intellegince find the subdomains of a target domain
+> Knock, knock. Who's there?
 
-Installation
-------------
+Subdomain enumeration for Node.js. Pulls candidate names from **Certificate
+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.
+
+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)
+[![CI](https://github.com/neopunisher/node-knock/actions/workflows/ci.yml/badge.svg)](https://github.com/neopunisher/node-knock/actions/workflows/ci.yml)
+
+## Install
+
+```bash
+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
+
+```bash
+knock example.com
+```
+
+```
+www.example.com  93.184.216.34  [ct+list]
+api.example.com  203.0.113.10  [ct]
+mail.example.com  198.51.100.7  [list]
+# example.com: 3 found from 31307 candidates, 18 ct names (2 unresolved) in 41.3s
+```
+
+Useful flags:
+
+| Flag | Effect |
+| --- | --- |
+| `-p, --passive` | Certificate Transparency only — no brute force |
+| `--no-ct` | wordlist brute force only |
+| `--no-verify` | report CT names without resolving them |
+| `--full-host` | scan the exact host given (skip the registrable-domain reduction) |
+| `-l, --list <path\|subs\|org>` | custom wordlist, or a bundled one by name |
+| `-c, --concurrency <n>` | parallel DNS queries (default 64) |
+| `-s, --server <ip>` | DNS server to query (repeatable) |
+| `-6, --ipv6` | also resolve AAAA records |
+| `-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.
+
+## Library
+
+```js
+import { knock } from 'knock';
+
+const report = await knock('example.com', { concurrency: 128 });
+
+for (const { name, addresses, sources } of report.results) {
+  console.log(name, addresses, sources); // 'www.example.com', ['93.184.216.34'], ['ct', 'wordlist']
+}
+console.log(report.wildcard); // { detected: false, addresses: [] }
+console.log(report.ct);       // { enabled: true, names: 18, unresolved: [...], error: null }
+console.log(report.stats);    // { words, candidates, queried, found, errors, durationMs }
+```
+
+Stream results as they're discovered, or go passive-only:
+
+```js
+await knock('example.com', { onResult: (r) => console.log(r.name) });
+
+// Just the Certificate Transparency names, one HTTPS request, no DNS:
+import { certSubdomains } from 'knock';
+const names = await certSubdomains('example.com');
+```
+
+### Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `words` | — | array of labels to try (`[]` for passive-only) |
+| `wordlist` | bundled `subs` | path to a wordlist file |
+| `ct` | `true` | pull candidates from Certificate Transparency logs |
+| `ctTimeout` | `15000` | crt.sh request timeout (ms) |
+| `verify` | `true` | resolve CT names over DNS |
+| `concurrency` | `64` | parallel DNS queries |
+| `timeout` / `tries` | `5000` / `2` | per-query DNS timeout (ms) and retries |
+| `servers` | system | DNS servers to query |
+| `family` | `4` | `4`, `6`, or `'any'` for A + AAAA |
+| `wildcardTests` | `3` | random probes for wildcard detection (`0` disables) |
+| `web` / `webTimeout` | `false` / `5000` | probe http/https on found hosts |
+| `baseDomainOnly` | `true` | reduce the target to its registrable domain first |
+| `icannOnly` | `false` | ignore the PSL's PRIVATE section (github.io, …) |
+| `signal` | — | `AbortSignal` to cancel the run |
+| `onResult` | — | callback fired per discovery |
+| `resolver` / `fetch` / `psl` | built-in | injectable for testing |
+
+The bundled wordlists are exposed as `wordlists.subs` (~31k labels,
+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
-npm install knock
+claude mcp add knock -- npx -y knock --mcp
 ```
 
-Useage
-------
-```javascript
-var knock = require('knock');
+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
+   first reduced to its registrable domain (`example.co.uk`) using a vendored
+   [PSL](https://publicsuffix.org) snapshot (refresh with `npm run
+   update-psl`), so private suffixes like `github.io` are handled correctly.
+   `--full-host` / `baseDomainOnly: false` scans the host exactly as given,
+   and the PSL helpers (`getRegistrableDomain`, `getPublicSuffix`,
+   `loadPublicSuffixList`) are exported for standalone use.
+1. **Certificate Transparency** — every publicly trusted TLS certificate is
+   logged; querying the logs for `%.example.com` reveals names that were ever
+   certified, including ones DNS brute forcing would never guess. Names that
+   no longer resolve are reported in `ct.unresolved` — often the most
+   interesting ones.
+2. **Wildcard detection** — a few random labels are resolved first; if the
+   zone answers for anything, wordlist hits that merely echo the wildcard
+   answer are suppressed (CT-sourced names are kept: the certificate is
+   evidence on its own).
+3. **Brute force** — wordlist labels are resolved through a bounded worker
+   pool using `node:dns` directly against your system resolvers (or servers
+   you pick with `-s`).
+
+## Development
+
+TypeScript sources live in `src/` and run directly on Node's native type
+stripping — `npm test` executes the `.ts` tests with `node --test`, no build
+step needed. `npm run build` compiles `dist/` (what actually ships), and
+`npm run knock -- example.com` runs the CLI from source.
+
+## Responsible use
+
+DNS brute forcing generates thousands of queries and CT lookups are logged.
+Only scan domains you own or are explicitly authorized to assess.
+
+## Publishing
+
+Releases are published to npm from GitHub Actions via
+[trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC) — no
+long-lived npm tokens — with provenance attestations generated automatically.
+
+## License
+
+MIT © [Carter Cole](https://github.com/neopunisher)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { readFileSync } from 'node:fs';
+import process from 'node:process';
+import { knock, wordlists } from './index.js';
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const HELP = `knock ${version} — subdomain enumeration
+
+Usage
+  knock [options] <domain> [domain ...]
+
+Sources
+  Certificate Transparency logs (crt.sh, passive) and a wordlist DNS brute
+  force run by default; wildcard DNS answers are detected and filtered.
+
+Options
+  -l, --list <path|subs|org>  wordlist file, or a bundled list by name
+                              (default: "subs", ~31k entries)
+  -p, --passive               skip the wordlist brute force (CT lookup only)
+      --no-ct                 skip the Certificate Transparency lookup
+      --no-verify             report CT names without resolving them
+      --full-host             scan the exact host given, without reducing it
+                              to the registrable domain (Public Suffix List)
+  -c, --concurrency <n>       parallel DNS queries (default: 64)
+  -t, --timeout <ms>          per-query DNS timeout (default: 5000)
+  -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
+  -V, --version               print the version
+
+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) {
+    process.stderr.write(`knock: ${message}\n`);
+    process.exit(1);
+}
+function parseCliArgs() {
+    try {
+        return parseArgs({
+            allowPositionals: true,
+            options: {
+                list: { type: 'string', short: 'l' },
+                passive: { type: 'boolean', short: 'p', default: false },
+                'no-ct': { type: 'boolean', default: false },
+                'no-verify': { type: 'boolean', default: false },
+                'full-host': { type: 'boolean', default: false },
+                concurrency: { type: 'string', short: 'c', default: '64' },
+                timeout: { type: 'string', short: 't', default: '5000' },
+                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 },
+                version: { type: 'boolean', short: 'V', default: false },
+            },
+        });
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : String(error));
+    }
+}
+const { values: flags, positionals: domains } = parseCliArgs();
+if (flags.help) {
+    console.log(HELP);
+    process.exit(0);
+}
+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)');
+}
+const integer = (name, value) => {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0)
+        fail(`--${name} expects a positive integer, got "${value}"`);
+    return n;
+};
+const options = {
+    concurrency: integer('concurrency', flags.concurrency),
+    timeout: integer('timeout', flags.timeout),
+    servers: flags.server,
+    family: flags.ipv6 ? 'any' : 4,
+    ct: !flags['no-ct'],
+    verify: !flags['no-verify'],
+    baseDomainOnly: !flags['full-host'],
+    web: flags.web,
+};
+if (flags.passive)
+    options.words = [];
+if (flags.list === 'subs' || flags.list === 'org')
+    options.wordlist = wordlists[flags.list];
+else if (flags.list)
+    options.wordlist = flags.list;
+if (flags.passive && !options.ct)
+    fail('--passive together with --no-ct leaves nothing to do');
+const sourceTag = (sources) => sources.length > 1 ? 'ct+list' : sources[0] === 'ct' ? 'ct' : 'list';
+const printResult = (result) => {
+    if (flags.quiet) {
+        console.log(result.name);
+        return;
+    }
+    const addresses = result.addresses.length > 0 ? result.addresses.join(' ') : '-';
+    const web = result.web
+        ? `  https:${result.web.https ?? '-'} http:${result.web.http ?? '-'}`
+        : '';
+    console.log(`${result.name}  ${addresses}  [${sourceTag(result.sources)}]${web}`);
+};
+const reports = [];
+let failed = false;
+for (const domain of domains) {
+    try {
+        const report = await knock(domain, {
+            ...options,
+            onResult: flags.json ? undefined : printResult,
+        });
+        reports.push(report);
+        if (!flags.json && !flags.quiet) {
+            const { stats, wildcard, ct } = report;
+            if (wildcard.detected) {
+                process.stderr.write(`! wildcard DNS on ${report.domain} (${wildcard.addresses.join(', ')}) — matching wordlist hits suppressed\n`);
+            }
+            if (ct.error)
+                process.stderr.write(`! ct lookup failed: ${ct.error}\n`);
+            const ctNote = ct.enabled ? `, ${ct.names} ct names (${ct.unresolved.length} unresolved)` : '';
+            process.stderr.write(`# ${report.domain}: ${stats.found} found from ${stats.candidates} candidates${ctNote} in ${(stats.durationMs / 1000).toFixed(1)}s\n`);
+        }
+    }
+    catch (error) {
+        failed = true;
+        process.stderr.write(`knock: ${domain}: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+if (flags.json && reports.length > 0) {
+    console.log(JSON.stringify(reports.length === 1 ? reports[0] : reports, null, 2));
+}
+process.exitCode = failed ? 1 : 0;

package/dist/index.d.ts

@@ -0,0 +1,148 @@
+import type { PublicSuffixRules } from './psl.ts';
+export type KnockSource = 'wordlist' | 'ct';
+export interface KnockWebStatuses {
+    https: number | null;
+    http: number | null;
+}
+export interface KnockResult {
+    /** Fully qualified hostname, e.g. "www.example.com". */
+    name: string;
+    /** Addresses the name resolved to (empty for unverified CT names). */
+    addresses: string[];
+    /** Where the candidate came from. */
+    sources: KnockSource[];
+    /** HTTP status codes per protocol; only present when `web: true`. */
+    web?: KnockWebStatuses;
+}
+export interface KnockWildcard {
+    detected: boolean;
+    /** Addresses returned for random non-existent labels. */
+    addresses: string[];
+}
+export interface KnockCtReport {
+    enabled: boolean;
+    /** Unique in-scope names found in Certificate Transparency logs. */
+    names: number;
+    /** CT names that no longer resolve (stale or internal-only certificates). */
+    unresolved: string[];
+    /** Error message when the CT lookup failed; the run continues without it. */
+    error: string | null;
+}
+export interface KnockStats {
+    words: number;
+    candidates: number;
+    queried: number;
+    found: number;
+    errors: number;
+    durationMs: number;
+}
+export interface KnockReport {
+    domain: string;
+    wildcard: KnockWildcard;
+    ct: KnockCtReport;
+    results: KnockResult[];
+    stats: KnockStats;
+}
+/** Minimal resolver surface; satisfied by dns.promises.Resolver or a test double. */
+export interface KnockResolver {
+    resolve4(name: string): Promise<string[]>;
+    resolve6(name: string): Promise<string[]>;
+}
+/** Minimal fetch surface; satisfied by globalThis.fetch or a test double. */
+export type KnockFetch = (url: string, init: {
+    signal: AbortSignal;
+    headers: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+export interface CertSubdomainsOptions {
+    /** Request timeout in milliseconds. Default 15000. */
+    timeout?: number;
+    signal?: AbortSignal;
+    /** Injectable fetch implementation, mainly for testing. */
+    fetch?: KnockFetch;
+}
+export interface KnockOptions {
+    /** Labels to try. Takes precedence over `wordlist`. Pass [] for passive-only runs. */
+    words?: string[];
+    /** Path to a wordlist file. Defaults to the bundled `wordlists.subs`. */
+    wordlist?: string;
+    /** Parallel DNS queries. Default 64. */
+    concurrency?: number;
+    /** Per-query DNS timeout in milliseconds. Default 5000. */
+    timeout?: number;
+    /** DNS retry attempts per query. Default 2. */
+    tries?: number;
+    /** DNS servers to query instead of the system resolvers. */
+    servers?: string[];
+    /** Address family: 4 (A), 6 (AAAA) or 'any' for both. Default 4. */
+    family?: 4 | 6 | 'any';
+    /** Random probes used to detect wildcard DNS. 0 disables. Default 3. */
+    wildcardTests?: number;
+    /** Pull candidates from Certificate Transparency logs. Default true. */
+    ct?: boolean;
+    /** CT request timeout in milliseconds. Default 15000. */
+    ctTimeout?: number;
+    /** Resolve CT-discovered names over DNS. Default true. */
+    verify?: boolean;
+    /** Probe http/https on each found host. Default false. */
+    web?: boolean;
+    /** Per-request web probe timeout in milliseconds. Default 5000. */
+    webTimeout?: number;
+    /**
+     * Reduce the target to its registrable domain via the Public Suffix List
+     * before enumerating (so "dev.example.co.uk" is scanned as "example.co.uk").
+     * Default true; set false to enumerate under the exact host given.
+     */
+    baseDomainOnly?: boolean;
+    /**
+     * When reducing to the registrable domain, use only the ICANN section of the
+     * Public Suffix List, ignoring private suffixes like github.io. Default false.
+     */
+    icannOnly?: boolean;
+    /** Injectable Public Suffix List rules, mainly for testing. */
+    psl?: PublicSuffixRules;
+    /** Abort the run; knock() rejects with the abort reason. */
+    signal?: AbortSignal;
+    /** Injectable resolver, mainly for testing. */
+    resolver?: KnockResolver;
+    /** Injectable fetch implementation used for the CT lookup. */
+    fetch?: KnockFetch;
+    /** Called with each result as it is discovered. */
+    onResult?: (result: KnockResult) => void;
+}
+/** Absolute paths to the wordlists bundled with the package. */
+export declare const wordlists: {
+    subs: string;
+    org: string;
+};
+/**
+ * Reduce user input like "HTTPS://www.Example.com/path" to a bare hostname.
+ * Throws TypeError when no usable hostname can be extracted.
+ */
+export declare function normalizeDomain(input: string): string;
+/** Parse wordlist text into unique, lowercased labels. Blank lines and #comments are skipped. */
+export declare function parseWordlist(text: string): string[];
+/** Read and parse a wordlist file. */
+export declare function loadWordlist(path: string): Promise<string[]>;
+/**
+ * Query Certificate Transparency logs (via crt.sh) for names certified under
+ * `domain`. Purely passive: one HTTPS request, no DNS traffic to the target.
+ * Wildcard entries like "*.dev.example.com" are reported as "dev.example.com".
+ * Resolves to a sorted array of hostnames, the apex excluded.
+ */
+export declare function certSubdomains(domain: string, options?: CertSubdomainsOptions): Promise<string[]>;
+/**
+ * Enumerate subdomains of `domain`.
+ *
+ * Two sources feed the candidate set: Certificate Transparency logs
+ * (passive, `ct` option) and a wordlist brute force over DNS. Candidates
+ * are resolved concurrently; hosts that only echo a wildcard DNS answer are
+ * suppressed unless Certificate Transparency vouches for them.
+ */
+export declare function knock(domain: string, options?: KnockOptions): Promise<KnockReport>;
+export { publicSuffixListPath, parsePublicSuffixList, loadPublicSuffixList, getPublicSuffix, getRegistrableDomain, } from './psl.ts';
+export type { PublicSuffixRule, PublicSuffixRules, PublicSuffixOptions } from './psl.ts';
+export default knock;