Merge pull request #3 from levz0r/develop

Fix SSRF vulnerability in URL fetching (CWE-918)

Author: levz0r

README.md

@@ -21,6 +21,9 @@ An MCP (Model Context Protocol) server that converts HTML content to Markdown fo
 - [Local Development](#local-development)
   - [Testing](#testing)
   - [Publishing a New Version](#publishing-a-new-version)
+- [Security](#security)
+  - [SSRF Protection](#ssrf-protection)
+  - [Allowing Local Network Access](#allowing-local-network-access)
 - [Technical Details](#technical-details)
 - [Related Projects](#related-projects)
 - [License](#license)
@@ -33,6 +36,7 @@ An MCP (Model Context Protocol) server that converts HTML content to Markdown fo
 - 🗑️ Automatically removes unwanted elements (scripts, styles, etc.)
 - 📊 Auto-extracts page titles and metadata
 - ⚡ Fast conversion using Turndown.js
+- 🔒 **SSRF protection** - Blocks requests to private/internal networks by default
 
 ## Installation
 
@@ -351,6 +355,7 @@ The test suite includes:
 - URL fetching tests
 - File saving tests
 - Truncation and large page handling tests
+- SSRF protection tests
 - Integration workflow tests
 
 ### Publishing a New Version
@@ -381,6 +386,47 @@ npm run release:minor --otp=<code>
 npm run release:major --otp=<code>
 ```
 
+## Security
+
+### SSRF Protection
+
+By default, the server blocks URL requests to private and internal network addresses to prevent [Server-Side Request Forgery (SSRF)](https://owasp.org/www-community/attacks/Server-Side_Request_Forgery) attacks. This includes:
+
+- Loopback addresses (`127.0.0.0/8`, `::1`)
+- Private networks (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`)
+- Link-local / cloud metadata endpoints (`169.254.0.0/16`)
+- Non-HTTP(S) schemes (`file://`, `ftp://`, etc.)
+
+DNS resolution is checked to prevent bypass via hostnames that resolve to private IPs.
+
+### Allowing Local Network Access
+
+If you need to convert HTML from local or internal servers (e.g., a local dev server), you can opt in with the `--allow-local` flag or the `ALLOW_LOCAL_NETWORK` environment variable:
+
+```bash
+# Via CLI flag
+npx html-to-markdown-mcp --allow-local
+```
+
+```bash
+# Via environment variable
+ALLOW_LOCAL_NETWORK=true npx html-to-markdown-mcp
+```
+
+**Claude Desktop / Cursor configuration with local access:**
+```json
+{
+  "mcpServers": {
+    "html-to-markdown": {
+      "command": "npx",
+      "args": ["html-to-markdown-mcp", "--allow-local"]
+    }
+  }
+}
+```
+
+> **Warning:** Only enable local network access if you trust the AI agent's URL inputs. With this flag enabled, the server can reach internal services, localhost ports, and cloud metadata endpoints.
+
 ## Technical Details
 
 - **Protocol:** Model Context Protocol (MCP)

index.js

@@ -10,6 +10,84 @@ import TurndownService from "turndown";
 import { writeFile, readFile } from "fs/promises";
 import { resolve, dirname } from "path";
 import { fileURLToPath } from "url";
+import { lookup } from "dns/promises";
+
+// SSRF protection: validate URLs before fetching (CWE-918)
+const BLOCKED_IP_RANGES = [
+  // Loopback
+  { prefix: "127.", mask: null },
+  // IPv6 loopback
+  { exact: "::1" },
+  // Link-local (cloud metadata endpoints like 169.254.169.254)
+  { prefix: "169.254.", mask: null },
+  // RFC 1918 private ranges
+  { prefix: "10.", mask: null },
+  { prefix: "172.", min: 16, max: 31 }, // 172.16.0.0 - 172.31.255.255
+  { prefix: "192.168.", mask: null },
+  // IPv6 private/link-local
+  { prefix: "fe80:", mask: null },
+  { prefix: "fc00:", mask: null },
+  { prefix: "fd", mask: null },
+  // Unspecified
+  { exact: "0.0.0.0" },
+  { exact: "::" },
+];
+
+function isPrivateIP(ip) {
+  for (const range of BLOCKED_IP_RANGES) {
+    if (range.exact && ip === range.exact) return true;
+    if (range.prefix && ip.startsWith(range.prefix)) {
+      if (range.min !== undefined) {
+        const secondOctet = parseInt(ip.split(".")[1], 10);
+        if (secondOctet >= range.min && secondOctet <= range.max) return true;
+      } else {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+// Allow private network access via --allow-local flag or ALLOW_LOCAL_NETWORK=true env var
+const allowLocalNetwork = process.argv.includes("--allow-local") ||
+  process.env.ALLOW_LOCAL_NETWORK === "true";
+
+async function validateUrl(urlString) {
+  let parsed;
+  try {
+    parsed = new URL(urlString);
+  } catch {
+    throw new Error("Invalid URL format");
+  }
+
+  // Only allow http and https schemes
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`URL scheme '${parsed.protocol.slice(0, -1)}' is not allowed. Only http and https are supported.`);
+  }
+
+  // Resolve hostname to IP and check against blocked ranges (unless opted out)
+  if (!allowLocalNetwork) {
+    const hostname = parsed.hostname;
+
+    // Check if hostname is already an IP literal
+    if (isPrivateIP(hostname)) {
+      throw new Error("URLs pointing to private or internal network addresses are not allowed. Use --allow-local flag to permit local network access.");
+    }
+
+    // DNS resolution check
+    try {
+      const { address } = await lookup(hostname);
+      if (isPrivateIP(address)) {
+        throw new Error("URLs pointing to private or internal network addresses are not allowed. Use --allow-local flag to permit local network access.");
+      }
+    } catch (err) {
+      if (err.message.includes("not allowed")) throw err;
+      throw new Error(`Could not resolve hostname: ${hostname}`);
+    }
+  }
+
+  return parsed;
+}
 
 // Get package version for user-agent
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -124,8 +202,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       let pageUrl = url;
       let pageTitle = null;
 
-      // If URL is provided, fetch the HTML
+      // If URL is provided, validate and fetch the HTML
       if (url) {
+        await validateUrl(url);
         console.error(`Fetching HTML from: ${url}`);
         const response = await fetch(url, {
           headers: {

test/html-to-markdown.test.js

@@ -4,16 +4,31 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { readFile, unlink } from "fs/promises";
 import { existsSync } from "fs";
+import { createServer } from "http";
 
 describe("HTML to Markdown MCP Server", () => {
   let client;
   let transport;
+  let httpServer;
+  let httpPort;
 
   before(async () => {
-    // Create client and connect
+    // Start a local HTTP server for URL fetch tests
+    httpServer = createServer((req, res) => {
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end("<html><head><title>Test Page</title></head><body><h1>Hello from local server</h1><p>Test content</p></body></html>");
+    });
+    await new Promise((resolve) => {
+      httpServer.listen(0, "127.0.0.1", () => {
+        httpPort = httpServer.address().port;
+        resolve();
+      });
+    });
+
+    // Create client and connect (--allow-local so URL fetch test can reach local server)
     transport = new StdioClientTransport({
       command: "node",
-      args: ["./index.js"],
+      args: ["./index.js", "--allow-local"],
     });
 
     client = new Client(
@@ -32,6 +47,7 @@ describe("HTML to Markdown MCP Server", () => {
   after(async () => {
     // Cleanup
     await client.close();
+    httpServer.close();
 
     // Remove test files
     const testFiles = [
@@ -87,17 +103,18 @@ describe("HTML to Markdown MCP Server", () => {
     });
 
     it("should fetch and convert URL", async () => {
+      const url = `http://127.0.0.1:${httpPort}/test-page`;
       const result = await client.callTool({
         name: "html_to_markdown",
         arguments: {
-          url: "https://example.com",
+          url,
           includeMetadata: true,
         },
       });
 
       assert.strictEqual(result.content[0].type, "text");
-      assert.ok(result.content[0].text.includes("Example Domain"));
-      assert.ok(result.content[0].text.includes("**Source:** https://example.com"));
+      assert.ok(result.content[0].text.includes("Hello from local server"));
+      assert.ok(result.content[0].text.includes(`**Source:** ${url}`));
     });
 
     it("should include metadata when requested", async () => {
@@ -231,6 +248,116 @@ describe("HTML to Markdown MCP Server", () => {
     });
   });
 
+  describe("SSRF protection", () => {
+    let ssrfClient;
+    let ssrfTransport;
+
+    before(async () => {
+      // Separate server instance WITHOUT --allow-local for SSRF tests
+      ssrfTransport = new StdioClientTransport({
+        command: "node",
+        args: ["./index.js"],
+      });
+      ssrfClient = new Client(
+        { name: "ssrf-test-client", version: "1.0.0" },
+        { capabilities: {} }
+      );
+      await ssrfClient.connect(ssrfTransport);
+    });
+
+    after(async () => {
+      await ssrfClient.close();
+    });
+
+    it("should block loopback URLs", async () => {
+      const result = await ssrfClient.callTool({
+        name: "html_to_markdown",
+        arguments: { url: "http://127.0.0.1:9999/ssrf" },
+      });
+      assert.strictEqual(result.isError, true);
+      assert.ok(result.content[0].text.includes("private or internal"));
+    });
+
+    it("should block localhost URLs", async () => {
+      const result = await ssrfClient.callTool({
+        name: "html_to_markdown",
+        arguments: { url: "http://localhost:9999/ssrf" },
+      });
+      assert.strictEqual(result.isError, true);
+      assert.ok(result.content[0].text.includes("private or internal"));
+    });
+
+    it("should block cloud metadata endpoint", async () => {
+      const result = await ssrfClient.callTool({
+        name: "html_to_markdown",
+        arguments: { url: "http://169.254.169.254/latest/meta-data/" },
+      });
+      assert.strictEqual(result.isError, true);
+      assert.ok(result.content[0].text.includes("private or internal"));
+    });
+
+    it("should block RFC 1918 private ranges (10.x)", async () => {
+      const result = await ssrfClient.callTool({
+        name: "html_to_markdown",
+        arguments: { url: "http://10.0.0.1/admin" },
+      });
+      assert.strictEqual(result.isError, true);
+      assert.ok(result.content[0].text.includes("private or internal"));
+    });
+
+    it("should block RFC 1918 private ranges (192.168.x)", async () => {
+      const result = await ssrfClient.callTool({
+        name: "html_to_markdown",
+        arguments: { url: "http://192.168.1.1/admin" },
+      });
+      assert.strictEqual(result.isError, true);
+      assert.ok(result.content[0].text.includes("private or internal"));
+    });
+
+    it("should block RFC 1918 private ranges (172.16-31.x)", async () => {
+      const result = await ssrfClient.callTool({
+        name: "html_to_markdown",
+        arguments: { url: "http://172.16.0.1/admin" },
+      });
+      assert.strictEqual(result.isError, true);
+      assert.ok(result.content[0].text.includes("private or internal"));
+    });
+
+    it("should block file:// scheme", async () => {
+      const result = await ssrfClient.callTool({
+        name: "html_to_markdown",
+        arguments: { url: "file:///etc/passwd" },
+      });
+      assert.strictEqual(result.isError, true);
+      assert.ok(result.content[0].text.includes("not allowed"));
+    });
+
+    it("should block ftp:// scheme", async () => {
+      const result = await ssrfClient.callTool({
+        name: "html_to_markdown",
+        arguments: { url: "ftp://internal.server/data" },
+      });
+      assert.strictEqual(result.isError, true);
+      assert.ok(result.content[0].text.includes("not allowed"));
+    });
+
+    it("should allow valid public URLs (not blocked by SSRF check)", async () => {
+      // We only verify the URL passes validation (no SSRF error).
+      // The fetch itself may fail due to network/TLS issues in CI,
+      // so we just confirm the error is NOT an SSRF block.
+      const result = await ssrfClient.callTool({
+        name: "html_to_markdown",
+        arguments: { url: "https://example.com", includeMetadata: false },
+      });
+      if (result.isError) {
+        assert.ok(!result.content[0].text.includes("private or internal"),
+          "Public URL should not be blocked by SSRF protection");
+        assert.ok(!result.content[0].text.includes("not allowed"),
+          "HTTPS scheme should be allowed");
+      }
+    });
+  });
+
   describe("Workflow Integration", () => {
     it("should convert HTML and save to file", async () => {
       // First, convert HTML to markdown