npm - @burtthecoder/mcp-dnstwist - Versions diffs - 1.0.7 → 1.1.0 - Mend

@burtthecoder/mcp-dnstwist 1.0.7 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,181 +1,123 @@
-# DNStwist MCP Server
-[![smithery badge](https://smithery.ai/badge/@burtthecoder/mcp-dnstwist)](https://smithery.ai/server/@burtthecoder/mcp-dnstwist)
-A Model Context Protocol (MCP) server for [dnstwist](https://github.com/elceef/dnstwist), a powerful DNS fuzzing tool that helps detect typosquatting, phishing, and corporate espionage. This server provides tools for analyzing domain permutations and identifying potentially malicious domains. It is designed to integrate seamlessly with MCP-compatible applications like [Claude Desktop](https://claude.ai).
-<a href="https://glama.ai/mcp/servers/it7izu3ufb"><img width="380" height="200" src="https://glama.ai/mcp/servers/it7izu3ufb/badge" alt="mcp-dnstwist MCP server" /></a>
-## ⚠️ Warning
-This tool is designed for legitimate security research purposes. Please:
-- Only analyze domains you own or have permission to test
-- Respect rate limits and DNS server policies
-- Use responsibly and ethically
-- Be aware that some DNS servers may rate-limit or block automated queries
-- Consider the impact on DNS infrastructure when running large scans
-## Requirements
-- Node.js (v20.3 or later)
-- Docker
-- macOS, Linux, or Windows with Docker Desktop installed
-## Quick Start
-### Installing via Smithery
-To install DNStwist for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@burtthecoder/mcp-dnstwist):
-```bash
-npx -y @smithery/cli install @burtthecoder/mcp-dnstwist --client claude
+<p align="center">
+  <img alt="MCP dnstwist: typosquatting detection for AI agents. Find lookalike, homoglyph and phishing domains with dnstwist over the Model Context Protocol." src="docs/assets/banner.webp" width="100%">
+</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@burtthecoder/mcp-dnstwist"><img alt="npm version" src="https://img.shields.io/npm/v/@burtthecoder/mcp-dnstwist"></a>
+  <a href="https://github.com/w0h1v/mcp-dnstwist/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/w0h1v/mcp-dnstwist/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <img alt="Node 20.3 or newer" src="https://img.shields.io/badge/node-%E2%89%A520.3-339933">
+  <a href="https://registry.modelcontextprotocol.io"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP-Registry-7c3aed"></a>
+  <a href="https://smithery.ai/server/@burtthecoder/mcp-dnstwist"><img alt="Smithery" src="https://img.shields.io/badge/Smithery-listed-ff5601"></a>
+</p>
+<p align="center">
+  <a href="#quickstart">Quickstart</a> ·
+  <a href="#the-tool">Tool</a> ·
+  <a href="#security">Security</a> ·
+  <a href="#troubleshooting">Troubleshooting</a> ·
+  <a href="https://w0h1v.github.io/mcp-dnstwist/">Docs</a>
+</p>
+**mcp-dnstwist** is an [MCP](https://modelcontextprotocol.io) server that lets AI agents run [dnstwist](https://github.com/elceef/dnstwist) to find domains that imitate yours: typos, homoglyphs, bit flips, swapped TLDs and more. For each registered lookalike it can report DNS records, whether its mail server could intercept your email, WHOIS registration details, and how closely its web page copies yours.
+> [!NOTE]
+> Independent project, not affiliated with dnstwist. Only scan domains you own or are authorized to assess.
+> [!IMPORTANT]
+> Versions up to 1.0.4 have a command injection vulnerability ([GHSA-p4jr-h3rj-2rw4](https://github.com/w0h1v/mcp-dnstwist/security/advisories/GHSA-p4jr-h3rj-2rw4)) and are deprecated. Use 1.0.5 or later; `npx -y @burtthecoder/mcp-dnstwist` always fetches the latest.
+## Highlights
+- **Lookalike discovery.** All of dnstwist's permutation algorithms, or only the ones you pick.
+- **Threat signals.** DNS records, open mail relays that could intercept email (`mxcheck`), WHOIS creation date and registrar, HTTP and SMTP banners, and web-page similarity (ssdeep or TLSH) to spot cloned phishing sites.
+- **Runs your way.** A local dnstwist install, the official dnstwist Docker image, or a self-contained mcp-dnstwist image.
+- **Hardened.** No shell, strict input validation, and time limits that stop and clean up long scans.
+- **Tested.** End-to-end tests with fake `docker` and `dnstwist` executables run in CI on Node 20, 22 and 24.
+## How it works
+```mermaid
+flowchart LR
+    A["AI agent<br/>(Claude, Codex, Gemini, VS Code)"] -->|"MCP over stdio"| S["mcp-dnstwist"]
+    S -->|"validated argv, no shell,<br/>time limit"| D["dnstwist<br/>(local or Docker)"]
+    D -->|"DNS, WHOIS, HTTP, SMTP"| I["Lookalike domains"]
+    D -->|"JSON"| S
+    S -->|"results"| A
 ```
-### Installing Manually
-1. Install Docker:
-   - macOS: Install [Docker Desktop](https://www.docker.com/products/docker-desktop)
-   - Linux: Follow the [Docker Engine installation guide](https://docs.docker.com/engine/install/)
+## Quickstart
-2. Install the server globally via npm:
-```bash
-npm install -g @burtthecoder/mcp-dnstwist
-```
-3. Add to your Claude Desktop configuration file:
-```json
-{
-  "mcpServers": {
-    "dnstwist": {
-      "command": "mcp-dnstwist"
-    }
-  }
-}
-```
+**Requirements:** Node.js 20.3 or newer, and either dnstwist (`pipx install "dnstwist[full]"`) or Docker. No API key.
-Configuration file location:
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+```sh
+# Claude Code
+claude mcp add --transport stdio dnstwist -- npx -y @burtthecoder/mcp-dnstwist
-4. Restart Claude Desktop
+# Codex CLI
+codex mcp add dnstwist -- npx -y @burtthecoder/mcp-dnstwist
-## Alternative Setup (From Source)
+# Gemini CLI
+gemini mcp add dnstwist npx -y @burtthecoder/mcp-dnstwist
+```
-If you prefer to run from source or need to modify the code:
+For Claude Desktop, VS Code, Docker, Smithery and running from source, see [Connect a client](docs/clients.md).
-1. Clone and build:
-```bash
-git clone <repository_url>
-cd mcp-dnstwist
-npm install
-npm run build
-```
+Then ask your agent: *"Which lookalike domains of example.com are registered, and could any of them intercept email?"* More prompts are in [example workflows](docs/examples.md).
-2. Add to your Claude Desktop configuration:
-```json
-{
-  "mcpServers": {
-    "dnstwist": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-dnstwist/build/index.js"]
-    }
-  }
-}
-```
+## The tool
-## Features
-- **Domain Fuzzing**: Generate domain permutations using various algorithms
-- **Registration Check**: Verify if permutated domains are registered
-- **DNS Analysis**: Check A, AAAA, MX, and NS records
-- **Web Presence**: Capture HTTP banner information
-- **WHOIS Data**: Retrieve registration dates and registrar information
-- **Phishing Detection**: Generate fuzzy hashes of web pages
-- **Configurable**: Custom DNS servers and parallel processing
-- **Multiple Formats**: Support for json, csv, and list output formats
-## Tools
-### Domain Fuzzing Tool
-- Name: `fuzz_domain`
-- 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 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
-  * `ssdeep` (optional, default: false): Generate fuzzy hashes of web pages
-  * `banners` (optional, default: true): Capture HTTP banner information
-Example:
-```json
-{
-  "domain": "example.com",
-  "nameservers": "1.1.1.1,8.8.8.8",
-  "threads": 50,
-  "format": "json",
-  "registered_only": true,
-  "mxcheck": true,
-  "banners": true
-}
-```
+One tool, `fuzz_domain`. Full parameters and real sample output are in the [tool reference](docs/tools.md).
-## Configuration
+| Parameter | Default | What it does |
+|---|---|---|
+| `domain` | *(required)* | The domain to imitate, for example `example.com` |
+| `registered_only` | `true` | Only return lookalikes that exist |
+| `fuzzers` | all | Limit to some algorithms, for example `["homoglyph", "bitsquatting"]` |
+| `mxcheck` | `true` | Flag mail servers that would accept email for any address |
+| `banners` | `true` | Capture HTTP and SMTP banners |
+| `whois` | `false` | Registration date and registrar |
+| `lsh` | off | Web-page similarity to the original: `ssdeep` or `tlsh` |
+| `all_records` | `false` | All DNS records, not only the first of each type |
+| `nameservers` | `1.1.1.1` | Up to 10 IPv4 addresses or `https://<host>/dns-query` URLs |
+| `threads` | `50` | Parallel lookups, 1 to 100 |
+| `format` | `json` | `json`, `csv` or `list` |
+### Settings
 | 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. |
+| `DNSTWIST_RUNNER` | `auto` | `local` (dnstwist on `PATH`), `docker` (the `elceef/dnstwist` image), or `auto` (local if available) |
+| `DNSTWIST_TIMEOUT_SECONDS` | `600` | Longest a scan may run. On timeout, cancellation or shutdown the scan is stopped and cleaned up |
-Set it in your client's `env` block, for example `"env": { "DNSTWIST_TIMEOUT_SECONDS": "900" }`.
+## Security
-## Troubleshooting
+The tool's arguments come from an AI model, which content it reads can steer, so the server treats them as hostile:
-### Docker Issues
+- **No shell.** dnstwist starts with `execFile` and an argument array; a test fails the build if a shell-based API appears.
+- **Strict validation.** Domains must be hostnames, nameservers IPv4 or DoH URLs, numbers and names from fixed sets. No value can start with `-`.
+- **Bounded runs.** Time limits, and cleanup of processes and containers on timeout, cancellation and shutdown.
-1. Verify Docker is installed and running:
-```bash
-docker --version
-docker ps
-```
+The Docker runner needs access to the Docker daemon (root-equivalent on most systems). The local runner or the self-contained image avoid that. Details in the [security model](docs/security.md). Report vulnerabilities privately; see [SECURITY.md](SECURITY.md).
-2. Check Docker permissions:
-   - Ensure your user has permissions to run Docker commands
-   - On Linux, add your user to the docker group: `sudo usermod -aG docker $USER`
-### Common Issues
-1. DNS resolution problems:
-   - Verify DNS servers are accessible
-   - Try alternative DNS servers (e.g., 8.8.8.8)
-   - Check for rate limiting or blocking
-2. Performance issues:
-   - Adjust thread count based on system capabilities
-   - Consider network bandwidth and latency
-   - Monitor DNS server response times
-3. After fixing any issues:
-   - Save the configuration file
-   - Restart Claude Desktop
+## Troubleshooting
-## Error Messages
+- **"Neither dnstwist nor Docker is available":** install dnstwist (`pipx install "dnstwist[full]"`) or start Docker. Desktop clients may not see your shell's `PATH`.
+- **Slow on Apple Silicon:** the dnstwist Docker image is amd64-only. Install dnstwist locally; it's used automatically.
+- **"did not finish within N seconds":** include an IPv4 nameserver (DNS-over-HTTPS is slow), turn off `whois`, `lsh` or `banners`, or raise `DNSTWIST_TIMEOUT_SECONDS`.
-- "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
+More in the [troubleshooting guide](docs/troubleshooting.md).
-- "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
-- "DNS server not responding": Verify DNS server accessibility and try alternative servers
+## Development
-## Contributing
+```sh
+git clone https://github.com/w0h1v/mcp-dnstwist && cd mcp-dnstwist
+npm ci
+npm test    # fake docker and dnstwist executables: no Docker or network needed
+```
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [changelog](CHANGELOG.md).
 ## License
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT. See [LICENSE](LICENSE).

package/build/index.js CHANGED Viewed

@@ -5,13 +5,13 @@ import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } f
 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,
+import { FUZZERS, LSH_ALGORITHMS, validateFuzzArgs } from './validate.js';
+// execFile runs docker (or dnstwist) 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.
+// Slow resolvers (DNS-over-HTTPS), LSH and banners can take many minutes.
 const DEFAULT_TIMEOUT_SECONDS = 600;
 function scanTimeoutSeconds() {
     const raw = process.env.DNSTWIST_TIMEOUT_SECONDS;
@@ -25,20 +25,36 @@ function scanTimeoutSeconds() {
     return seconds;
 }
 const TIMEOUT_SECONDS = scanTimeoutSeconds();
+const RUNNER_SETTINGS = ['docker', 'local', 'auto'];
+// docker: run the elceef/dnstwist image. local: run a dnstwist on PATH.
+// auto (default): local when a dnstwist executable works, otherwise docker.
+function runnerSetting() {
+    const raw = process.env.DNSTWIST_RUNNER;
+    if (raw === undefined || raw === '')
+        return 'auto';
+    if (!RUNNER_SETTINGS.includes(raw)) {
+        console.error(`DNSTWIST_RUNNER must be one of ${RUNNER_SETTINGS.join(', ')}, got ${JSON.stringify(raw)}`);
+        process.exit(1);
+    }
+    return raw;
+}
+const RUNNER_SETTING = runnerSetting();
 class DnstwistServer {
     constructor() {
-        // Scans in progress: container name -> controller that stops its docker run.
-        this.runningContainers = new Map();
+        // Scans in progress: id -> controller that stops the child process, plus the
+        // container name when the docker runner started one.
+        this.runningScans = 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);
         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)));
+                // in-flight child process first, then remove any docker container.
+                const scans = [...this.runningScans.values()];
+                for (const scan of scans)
+                    scan.stop.abort();
+                await Promise.all(scans.flatMap((scan) => (scan.container ? [this.removeContainer(scan.container)] : [])));
                 await this.server.close();
                 process.exit(0);
             });
@@ -52,10 +68,28 @@ class DnstwistServer {
     async execCommand(file, args, options = {}) {
         console.error('Executing:', file, JSON.stringify(args));
         try {
-            const result = await execFileAsync(file, args, {
+            const { killOnAbort, ...execOptions } = options;
+            const pending = execFileAsync(file, args, {
                 maxBuffer: 10 * 1024 * 1024,
-                ...options
+                ...execOptions,
+                // execFile's own `signal` support always sends SIGTERM; when the process
+                // must be killed outright, handle the abort here instead.
+                ...(killOnAbort ? { signal: undefined } : {})
             });
+            const abort = () => pending.child.kill('SIGKILL');
+            if (killOnAbort && options.signal) {
+                if (options.signal.aborted)
+                    abort();
+                else
+                    options.signal.addEventListener('abort', abort, { once: true });
+            }
+            let result;
+            try {
+                result = await pending;
+            }
+            finally {
+                options.signal?.removeEventListener('abort', abort);
+            }
             console.error('Command output:', result.stdout);
             if (result.stderr)
                 console.error('Command stderr:', result.stderr);
@@ -82,25 +116,67 @@ class DnstwistServer {
         }
         console.error(`Could not confirm removal of container ${name}`);
     }
+    // Decided once. A failed check is not cached, so a later call can retry.
+    getRunner() {
+        this.runnerPromise ?? (this.runnerPromise = this.selectRunner().catch((error) => {
+            this.runnerPromise = undefined;
+            throw error;
+        }));
+        return this.runnerPromise;
+    }
+    async checkLocal() {
+        try {
+            await this.execCommand('dnstwist', ['--version']);
+        }
+        catch (error) {
+            throw new Error('The dnstwist executable was not found or does not work (`dnstwist --version` failed). ' +
+                'Install it (for example `pipx install "dnstwist[full]"`) or set DNSTWIST_RUNNER=docker.');
+        }
+    }
+    async selectRunner() {
+        if (RUNNER_SETTING === 'docker')
+            return 'docker';
+        if (RUNNER_SETTING === 'local') {
+            await this.checkLocal();
+            console.error('Using the local dnstwist executable (DNSTWIST_RUNNER=local)');
+            return 'local';
+        }
+        try {
+            await this.checkLocal();
+            console.error('Using the local dnstwist executable (DNSTWIST_RUNNER=auto)');
+            return 'local';
+        }
+        catch {
+            console.error('No working dnstwist executable on PATH; using Docker (DNSTWIST_RUNNER=auto)');
+            return 'docker';
+        }
+    }
+    async checkDocker() {
+        console.error('Checking Docker...');
+        try {
+            await this.execCommand('docker', ['--version']);
+        }
+        catch (error) {
+            throw new Error('Docker is not installed or not running. Please install Docker and try again.');
+        }
+        console.error('Checking if dnstwist image exists...');
+        try {
+            await this.execCommand('docker', ['image', 'inspect', DOCKER_IMAGE]);
+            console.error('Dnstwist image found');
+        }
+        catch (error) {
+            console.error('Dnstwist image not found, pulling...');
+            await this.execCommand('docker', ['pull', DOCKER_IMAGE]);
+            console.error('Dnstwist image pulled successfully');
+        }
+    }
     async ensureSetup() {
         try {
-            console.error('Checking Docker...');
-            try {
-                await this.execCommand('docker', ['--version']);
-            }
-            catch (error) {
-                throw new Error('Docker is not installed or not running. Please install Docker and try again.');
-            }
-            console.error('Checking if dnstwist image exists...');
-            try {
-                await this.execCommand('docker', ['image', 'inspect', DOCKER_IMAGE]);
-                console.error('Dnstwist image found');
-            }
-            catch (error) {
-                console.error('Dnstwist image not found, pulling...');
-                await this.execCommand('docker', ['pull', DOCKER_IMAGE]);
-                console.error('Dnstwist image pulled successfully');
-            }
+            const runner = await this.getRunner();
+            // Docker is re-checked per call: the image or daemon can disappear.
+            if (runner === 'docker')
+                await this.checkDocker();
+            return runner;
         }
         catch (error) {
             console.error('Setup failed:', error);
@@ -127,7 +203,7 @@ class DnstwistServer {
                             },
                             threads: {
                                 type: 'number',
-                                description: 'Number of threads to use for parallel processing',
+                                description: 'Number of parallel lookups (1-100)',
                                 minimum: 1,
                                 maximum: 100,
                                 default: 50
@@ -145,17 +221,40 @@ class DnstwistServer {
                             },
                             mxcheck: {
                                 type: 'boolean',
-                                description: 'Check for MX records',
+                                description: 'Check whether each mail server would accept email for any address, so it could intercept mail sent to typos of your domain',
                                 default: true
                             },
                             ssdeep: {
                                 type: 'boolean',
-                                description: 'Generate fuzzy hashes of web pages to detect phishing',
+                                description: 'Deprecated alias for lsh: "ssdeep" (ignored when lsh is set)',
                                 default: false
                             },
+                            lsh: {
+                                type: 'string',
+                                enum: [...LSH_ALGORITHMS],
+                                description: 'Compare each permutation\'s web page with the original using a fuzzy hash (slow) to spot cloned phishing pages'
+                            },
+                            whois: {
+                                type: 'boolean',
+                                description: 'Look up WHOIS creation date and registrar for each domain (slower)',
+                                default: false
+                            },
+                            all_records: {
+                                type: 'boolean',
+                                description: 'Return all DNS records instead of only the first of each type',
+                                default: false
+                            },
+                            fuzzers: {
+                                type: 'array',
+                                items: { type: 'string', enum: [...FUZZERS] },
+                                minItems: 1,
+                                maxItems: FUZZERS.length,
+                                uniqueItems: true,
+                                description: 'Only use these fuzzing algorithms (default: all)'
+                            },
                             banners: {
                                 type: 'boolean',
-                                description: 'Capture HTTP banner information',
+                                description: 'Capture HTTP and SMTP server banners',
                                 default: true
                             }
                         },
@@ -166,11 +265,11 @@ class DnstwistServer {
         }));
         this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             try {
-                await this.ensureSetup();
+                const runner = await this.ensureSetup();
                 if (request.params.name !== 'fuzz_domain') {
                     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
                 }
-                const { domain, nameservers, threads, format, registered_only, mxcheck, ssdeep, banners } = validateFuzzArgs(request.params.arguments);
+                const { domain, nameservers, threads, format, registered_only, mxcheck, banners, whois, all_records, fuzzers, lsh } = validateFuzzArgs(request.params.arguments);
                 // Build command arguments
                 const args = [
                     domain,
@@ -184,34 +283,44 @@ class DnstwistServer {
                     args.push('-t', threads.toString());
                 if (mxcheck)
                     args.push('--mxcheck');
-                if (ssdeep)
-                    args.push('--ssdeep');
+                if (lsh)
+                    args.push('--lsh', lsh);
                 if (banners)
                     args.push('-b');
-                // Run dnstwist in Docker
-                const container = `mcp-dnstwist-${randomUUID()}`;
+                if (whois)
+                    args.push('-w');
+                if (all_records)
+                    args.push('-a');
+                if (fuzzers)
+                    args.push('--fuzzers', fuzzers.join(','));
+                const id = randomUUID();
+                const container = runner === 'docker' ? `mcp-dnstwist-${id}` : undefined;
                 const stop = new AbortController();
-                this.runningContainers.set(container, stop);
+                this.runningScans.set(id, { stop, container });
                 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]) }));
+                    const options = { timeout: TIMEOUT_SECONDS * 1000, signal: AbortSignal.any([extra.signal, stop.signal]) };
+                    ({ stdout } = container
+                        ? await this.execCommand('docker', ['run', '--rm', '--name', container, DOCKER_IMAGE, ...args], options)
+                        // dnstwist handles SIGTERM itself and may wind down slowly: kill it outright.
+                        : await this.execCommand('dnstwist', args, { ...options, killSignal: 'SIGKILL', killOnAbort: true }));
                 }
                 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)
+                    if (container && (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, ' +
+                            'Use an IPv4 nameserver (DNS-over-HTTPS is slow), turn off lsh, whois or banners, ' +
                             'or raise DNSTWIST_TIMEOUT_SECONDS.');
                     }
                     throw error;
                 }
                 finally {
-                    this.runningContainers.delete(container);
+                    this.runningScans.delete(id);
                 }
                 // csv and list output are returned as dnstwist printed them.
                 if (format !== 'json') {

package/build/validate.js CHANGED Viewed

@@ -6,6 +6,13 @@ import { domainToASCII } from 'url';
 // mistaken for a dnstwist option either.
 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'];
+// dnstwist's fuzzing algorithms, minus dictionary and tld-swap: those need a
+// word or TLD list file, which this tool doesn't take.
+export const FUZZERS = [
+    'addition', 'bitsquatting', 'cyrillic', 'homoglyph', 'hyphenation', 'insertion', 'omission',
+    'plural', 'repetition', 'replacement', 'subdomain', 'transposition', 'vowel-swap', 'various',
+];
+export const LSH_ALGORITHMS = ['ssdeep', 'tlsh'];
 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$/;
@@ -65,6 +72,22 @@ export function validateFuzzArgs(args) {
     if (!FORMATS.includes(format)) {
         invalid(`format must be one of ${FORMATS.join(', ')}`);
     }
+    let fuzzers;
+    if (a.fuzzers !== undefined) {
+        const list = a.fuzzers;
+        if (!Array.isArray(list) || list.length < 1 || list.length > FUZZERS.length ||
+            list.some((f) => typeof f !== 'string' || !FUZZERS.includes(f)) ||
+            new Set(list).size !== list.length) {
+            invalid(`fuzzers must be 1 to ${FUZZERS.length} unique names from: ${FUZZERS.join(', ')}`);
+        }
+        fuzzers = list;
+    }
+    if (a.lsh !== undefined && !LSH_ALGORITHMS.includes(a.lsh)) {
+        invalid(`lsh must be one of ${LSH_ALGORITHMS.join(', ')}`);
+    }
+    const ssdeep = optionalBoolean(a, 'ssdeep', false);
+    // `ssdeep: true` is the older spelling of `lsh: 'ssdeep'`; an explicit lsh wins.
+    const lsh = a.lsh ?? (ssdeep ? 'ssdeep' : undefined);
     return {
         domain: domain,
         nameservers: servers.join(','),
@@ -72,7 +95,11 @@ export function validateFuzzArgs(args) {
         format: format,
         registered_only: optionalBoolean(a, 'registered_only', true),
         mxcheck: optionalBoolean(a, 'mxcheck', true),
-        ssdeep: optionalBoolean(a, 'ssdeep', false),
+        ssdeep,
         banners: optionalBoolean(a, 'banners', true),
+        whois: optionalBoolean(a, 'whois', false),
+        all_records: optionalBoolean(a, 'all_records', false),
+        ...(fuzzers ? { fuzzers } : {}),
+        ...(lsh ? { lsh } : {}),
     };
 }

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@burtthecoder/mcp-dnstwist",
-  "version": "1.0.7",
-  "description": "MCP server for dnstwist - DNS fuzzing to detect typosquatting, phishing and corporate espionage",
+  "version": "1.1.0",
+  "description": "MCP server for dnstwist: find typosquatting, homoglyph and lookalike domains used for phishing and brand impersonation",
   "main": "build/index.js",
   "type": "module",
   "bin": {
@@ -14,6 +14,8 @@
   ],
   "scripts": {
     "build": "tsc && chmod +x build/index.js",
+    "start": "node build/index.js",
+    "dev": "tsc -w",
     "prepublishOnly": "npm run build",
     "test": "npm run build && node --test tests/*.test.mjs"
   },
@@ -37,11 +39,22 @@
     "typosquatting",
     "domain-security",
     "claude",
-    "claude-desktop"
+    "claude-desktop",
+    "mcp-server",
+    "model-context-protocol",
+    "brand-protection",
+    "threat-intelligence",
+    "dfir",
+    "phishing-detection"
   ],
-  "author": "burtmacklin",
+  "author": "w0h1v",
   "license": "MIT",
   "engines": {
     "node": ">=20.3"
-  }
+  },
+  "homepage": "https://w0h1v.github.io/mcp-dnstwist/",
+  "bugs": {
+    "url": "https://github.com/w0h1v/mcp-dnstwist/issues"
+  },
+  "mcpName": "io.github.w0h1v/dnstwist"
 }