@burtthecoder/mcp-dnstwist 1.0.5 → 1.0.7

package/README.md

@@ -17,7 +17,7 @@ This tool is designed for legitimate security research purposes. Please:
 
 ## Requirements
 
-- Node.js (v18 or later)
+- Node.js (v20.3 or later)
 - Docker
 - macOS, Linux, or Windows with Docker Desktop installed
 
@@ -100,8 +100,8 @@ npm run build
 - Description: Generate and analyze domain permutations to detect potential typosquatting, phishing, and brand impersonation
 - Parameters:
   * `domain` (required): Domain name to analyze (e.g., example.com)
-  * `nameservers` (optional, default: "1.1.1.1"): Comma-separated list of DNS servers
-  * `threads` (optional, default: 50): Number of threads for parallel processing
+  * `nameservers` (optional, default: "1.1.1.1"): Comma-separated DNS servers, up to 10. Each must be an IPv4 address or a DNS-over-HTTPS URL such as `https://cloudflare-dns.com/dns-query` (the forms dnstwist accepts). DNS-over-HTTPS is much slower: a DoH-only scan can take over 10 minutes, so include an IPv4 resolver unless you need DoH
+  * `threads` (optional, default: 50): Number of threads for parallel processing (1-100)
   * `format` (optional, default: "json"): Output format (json, csv, list)
   * `registered_only` (optional, default: true): Show only registered domains
   * `mxcheck` (optional, default: true): Check for MX records
@@ -121,6 +121,14 @@ Example:
 }
 ```
 
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `DNSTWIST_TIMEOUT_SECONDS` | `600` | Longest a scan may run. When it's reached, or when the client cancels the call, the scan's container is stopped and removed. |
+
+Set it in your client's `env` block, for example `"env": { "DNSTWIST_TIMEOUT_SECONDS": "900" }`.
+
 ## Troubleshooting
 
 ### Docker Issues
@@ -153,6 +161,8 @@ docker ps
 
 ## Error Messages
 
+- "dnstwist did not finish within N seconds": the scan hit `DNSTWIST_TIMEOUT_SECONDS`. Use an IPv4 nameserver (DNS-over-HTTPS is slow), turn off `ssdeep` or `banners`, or raise the limit
+
 - "Docker is not installed or not running": Install Docker and start the Docker daemon
 - "Failed to parse dnstwist output": Check if the domain is valid and the format is correct
 - "Error executing dnstwist": Check Docker logs and ensure proper permissions

package/build/index.js

@@ -3,32 +3,58 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { execFile } from 'child_process';
+import { randomUUID } from 'crypto';
 import { promisify } from 'util';
 import { validateFuzzArgs } from './validate.js';
 // execFile runs docker directly with an argument array. No shell is involved,
 // so tool input can never be interpreted as shell syntax (CWE-78, issue #13).
 const execFileAsync = promisify(execFile);
 const DOCKER_IMAGE = 'elceef/dnstwist';
+// A scan that runs longer than this is stopped and its container removed.
+// Slow resolvers (DNS-over-HTTPS) and --ssdeep/--banners can take many minutes.
+const DEFAULT_TIMEOUT_SECONDS = 600;
+function scanTimeoutSeconds() {
+    const raw = process.env.DNSTWIST_TIMEOUT_SECONDS;
+    if (raw === undefined || raw === '')
+        return DEFAULT_TIMEOUT_SECONDS;
+    const seconds = Number(raw);
+    if (!Number.isInteger(seconds) || seconds < 1 || seconds > 86400) {
+        console.error(`DNSTWIST_TIMEOUT_SECONDS must be an integer from 1 to 86400, got ${JSON.stringify(raw)}`);
+        process.exit(1);
+    }
+    return seconds;
+}
+const TIMEOUT_SECONDS = scanTimeoutSeconds();
 class DnstwistServer {
     constructor() {
+        // Scans in progress: container name -> controller that stops its docker run.
+        this.runningContainers = new Map();
         this.server = new Server({ name: 'dnstwist-server', version: '0.1.0' }, { capabilities: { tools: {} } });
         this.setupToolHandlers();
         this.server.onerror = (error) => console.error('[MCP Error]', error);
-        process.on('SIGINT', async () => {
-            await this.server.close();
-            process.exit(0);
-        });
+        for (const signal of ['SIGINT', 'SIGTERM']) {
+            process.on(signal, async () => {
+                // Don't leave scans running after the server is gone: stop each
+                // in-flight docker run first, then remove its container.
+                for (const controller of this.runningContainers.values())
+                    controller.abort();
+                await Promise.all([...this.runningContainers.keys()].map((name) => this.removeContainer(name)));
+                await this.server.close();
+                process.exit(0);
+            });
+        }
         // Trigger setup immediately
         this.ensureSetup().catch(error => {
             console.error('Failed to setup dnstwist:', error);
             process.exit(1);
         });
     }
-    async execCommand(file, args) {
+    async execCommand(file, args, options = {}) {
         console.error('Executing:', file, JSON.stringify(args));
         try {
             const result = await execFileAsync(file, args, {
-                maxBuffer: 10 * 1024 * 1024
+                maxBuffer: 10 * 1024 * 1024,
+                ...options
             });
             console.error('Command output:', result.stdout);
             if (result.stderr)
@@ -40,6 +66,22 @@ class DnstwistServer {
             throw error;
         }
     }
+    // Killing the docker CLI doesn't stop the container it started, so a scan
+    // that times out or is cancelled is removed by name. Right after the CLI
+    // starts, the daemon may not have created the container yet ("No such
+    // container"), so keep trying for a few seconds until a removal succeeds.
+    async removeContainer(name, attempts = 10, delayMs = 500) {
+        for (let i = 0; i < attempts; i++) {
+            try {
+                await execFileAsync('docker', ['rm', '-f', name]);
+                return;
+            }
+            catch {
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+            }
+        }
+        console.error(`Could not confirm removal of container ${name}`);
+    }
     async ensureSetup() {
         try {
             console.error('Checking Docker...');
@@ -80,7 +122,7 @@ class DnstwistServer {
                             },
                             nameservers: {
                                 type: 'string',
-                                description: 'Comma-separated list of DNS servers to use (default: 1.1.1.1)',
+                                description: 'Comma-separated DNS servers: IPv4 addresses or DNS-over-HTTPS URLs such as https://cloudflare-dns.com/dns-query (default: 1.1.1.1)',
                                 default: '1.1.1.1'
                             },
                             threads: {
@@ -122,7 +164,7 @@ class DnstwistServer {
                 }
             ]
         }));
-        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             try {
                 await this.ensureSetup();
                 if (request.params.name !== 'fuzz_domain') {
@@ -147,7 +189,30 @@ class DnstwistServer {
                 if (banners)
                     args.push('-b');
                 // Run dnstwist in Docker
-                const { stdout } = await this.execCommand('docker', ['run', '--rm', DOCKER_IMAGE, ...args]);
+                const container = `mcp-dnstwist-${randomUUID()}`;
+                const stop = new AbortController();
+                this.runningContainers.set(container, stop);
+                let stdout;
+                try {
+                    ({ stdout } = await this.execCommand('docker', ['run', '--rm', '--name', container, DOCKER_IMAGE, ...args], { timeout: TIMEOUT_SECONDS * 1000, signal: AbortSignal.any([extra.signal, stop.signal]) }));
+                }
+                catch (error) {
+                    const stopped = extra.signal.aborted || stop.signal.aborted;
+                    const timedOut = Boolean(error.killed) && !stopped;
+                    // If dnstwist exited on its own, --rm already removed the container.
+                    if (timedOut || stopped)
+                        await this.removeContainer(container);
+                    if (timedOut) {
+                        const unit = TIMEOUT_SECONDS === 1 ? 'second' : 'seconds';
+                        throw new Error(`dnstwist did not finish within ${TIMEOUT_SECONDS} ${unit} and was stopped. ` +
+                            'Use an IPv4 nameserver (DNS-over-HTTPS is slow), turn off ssdeep or banners, ' +
+                            'or raise DNSTWIST_TIMEOUT_SECONDS.');
+                    }
+                    throw error;
+                }
+                finally {
+                    this.runningContainers.delete(container);
+                }
                 // csv and list output are returned as dnstwist printed them.
                 if (format !== 'json') {
                     return { content: [{ type: 'text', text: stdout }] };

package/build/validate.js

@@ -7,6 +7,8 @@ import { domainToASCII } from 'url';
 const HOSTNAME = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+(?:[a-z]{2,63}|xn--[a-z0-9-]{1,59})$/i;
 const FORMATS = ['json', 'csv', 'list'];
 const MAX_NAMESERVERS = 10;
+// The DNS-over-HTTPS form dnstwist accepts (dnstwist.py --nameservers parsing).
+const DOH = /^https:\/\/([a-z0-9.-]{4,253})\/dns-query$/;
 function invalid(message) {
     throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for fuzz_domain: ${message}`);
 }
@@ -42,12 +44,18 @@ export function validateFuzzArgs(args) {
     const rawNameservers = a.nameservers === undefined ? '1.1.1.1' : a.nameservers;
     if (typeof rawNameservers !== 'string')
         invalid('nameservers must be a string');
+    // dnstwist only accepts IPv4 addresses and https://<host>/dns-query URLs, so
+    // anything else would fail inside the container anyway.
     const servers = rawNameservers.split(',').map((ns) => {
         const trimmed = ns.trim();
-        return isIP(trimmed) !== 0 ? trimmed : asciiHostname(trimmed);
+        if (isIP(trimmed) === 4)
+            return trimmed;
+        const doh = trimmed.match(DOH);
+        return doh && (isIP(doh[1]) === 4 || HOSTNAME.test(doh[1])) ? trimmed : null;
     });
     if (servers.length > MAX_NAMESERVERS || servers.some((ns) => !ns)) {
-        invalid(`nameservers must be up to ${MAX_NAMESERVERS} comma-separated IP addresses or hostnames`);
+        invalid(`nameservers must be up to ${MAX_NAMESERVERS} comma-separated IPv4 addresses ` +
+            'or DNS-over-HTTPS URLs like https://cloudflare-dns.com/dns-query');
     }
     const threads = a.threads === undefined ? 50 : a.threads;
     if (typeof threads !== 'number' || !Number.isInteger(threads) || threads < 1 || threads > 100) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burtthecoder/mcp-dnstwist",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "MCP server for dnstwist - DNS fuzzing to detect typosquatting, phishing and corporate espionage",
   "main": "build/index.js",
   "type": "module",
@@ -42,6 +42,6 @@
   "author": "burtmacklin",
   "license": "MIT",
   "engines": {
-    "node": ">=20"
+    "node": ">=20.3"
   }
 }