security(url-security): block CGNAT + IANA special-purpose IPv4 ranges in SSRF guard (SEC-024)

isPrivateIpv4 blocked only RFC1918/loopback/link-local/0.0.0.0-8, so with private
URLs blocked by default a web_url_read (and the DNS-rebinding lookup hook that
validates every resolved answer) let CGNAT 100.64.0.0/10 — Tailscale's default
range, plus container overlays and ISP CGNAT — as well as TEST-NETs, benchmarking,
IETF protocol assignments, multicast, and reserved/broadcast ranges through. Add a
uint32 CIDR table covering the IANA special-purpose ranges (RFC 6890) and OR it into
the shared predicate, closing both the literal-hostname (assertUrlAllowed) and
DNS-resolved (proxy lookup hook) enforcement paths in one point. IPv4-mapped IPv6
(::ffff:) already delegates here, so it is covered too.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Codex <noreply@openai.com>

Author: 3 people

CONFIGURATION.md

@@ -164,7 +164,7 @@ Opt-in security layer for when you expose the HTTP transport on a network. Defau
 
 ## URL Reader Security
 
-`web_url_read` blocks private/internal URLs by default in all transport modes. This includes localhost, loopback addresses, private IPv4 ranges, link-local addresses, `0.0.0.0/8`, IPv6 loopback/ULA/link-local addresses, and IPv4-mapped IPv6 private addresses.
+`web_url_read` blocks private/internal URLs by default in all transport modes. This includes localhost, loopback addresses, private IPv4 ranges, link-local addresses, `0.0.0.0/8`, CGNAT (`100.64.0.0/10`), IANA special-purpose IPv4 ranges, IPv6 loopback/ULA/link-local addresses, and IPv4-mapped IPv6 private addresses.
 
 Redirects are also checked before they are followed. A public URL that redirects to a private/internal URL is blocked.
 

SECURITY.md

@@ -45,7 +45,7 @@ The primary security surface areas are:
 Private and internal URLs are **blocked by default** in all transport modes. The following are rejected:
 
 - `localhost` and `*.localhost`
-- IPv4 loopback (`127.0.0.0/8`), private (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), link-local (`169.254.0.0/16`), and unspecified (`0.0.0.0/8`) ranges
+- IPv4 loopback (`127.0.0.0/8`), private (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), link-local (`169.254.0.0/16`), unspecified (`0.0.0.0/8`), CGNAT (`100.64.0.0/10`), IETF protocol assignments (`192.0.0.0/24`), documentation/test ranges (`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`), benchmarking (`198.18.0.0/15`), multicast (`224.0.0.0/4`), and reserved/broadcast (`240.0.0.0/4`) ranges
 - IPv6 loopback (`::1`), unspecified (`::`), ULA (`fc00::/7`), link-local (`fe80::/10`)
 - IPv4-mapped IPv6 addresses that resolve to any of the above (e.g. `::ffff:127.0.0.1`)
 - Redirects are validated **before** they are followed — a public URL that redirects to a private address is also blocked

__tests__/run-all.ts

@@ -20,6 +20,7 @@ import { runTests as runSearchTests } from './unit/search.test.js';
 import { runTests as runSuggestionsTests } from './unit/suggestions.test.js';
 import { runTests as runInstanceInfoTests } from './unit/instance-info.test.js';
 import { runTests as runUrlReaderTests } from './unit/url-reader.test.js';
+import { runTests as runUrlSecurityTests } from './unit/url-security.test.js';
 import { runTests as runTlsConfigTests } from './unit/tls-config.test.js';
 import { runTests as runHttpServerUnitTests } from './unit/http-server.test.js';
 import { runTests as runVersionTests } from './unit/version.test.js';
@@ -49,6 +50,7 @@ const testSuites: TestSuite[] = [
   { name: 'Suggestions', category: 'unit', run: runSuggestionsTests },
   { name: 'Instance Info', category: 'unit', run: runInstanceInfoTests },
   { name: 'URL Reader', category: 'unit', run: runUrlReaderTests },
+  { name: 'URL Security', category: 'unit', run: runUrlSecurityTests },
   { name: 'TLS Config', category: 'unit', run: runTlsConfigTests },
   { name: 'HTTP Server', category: 'unit', run: runHttpServerUnitTests },
   { name: 'Version', category: 'unit', run: runVersionTests },

__tests__/unit/url-reader.test.ts

@@ -27,7 +27,7 @@ const results = createTestResults();
 const envManager = new EnvManager();
 const require = createRequire(import.meta.url);
 const dnsModule = require('node:dns') as typeof import('node:dns');
-const TEST_PUBLIC_IP = '203.0.113.10';
+const TEST_PUBLIC_IP = '93.184.216.34';
 
 // ─── local test-server helpers ───────────────────────────────────────────────
 
@@ -1321,6 +1321,7 @@ async function runTests() {
       'lan.example': [{ address: '192.168.1.20', family: 4 }],
       'rfc1918.example': [{ address: '172.16.0.9', family: 4 }],
       'metadata.example': [{ address: '169.254.169.254', family: 4 }],
+      'cgnat.example': [{ address: '100.64.0.1', family: 4 }],
     };
     const restoreDns = installDnsLookupMock(privateCases);
 

__tests__/unit/url-security.test.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env tsx
+
+import { strict as assert } from 'node:assert';
+import { fileURLToPath } from 'node:url';
+import {
+  assertUrlAllowed,
+  isPrivateIPv6,
+  isPrivateIpv4,
+} from '../../src/url-security.js';
+import { testFunction, createTestResults, printTestSummary } from '../helpers/test-utils.js';
+import { EnvManager } from '../helpers/env-utils.js';
+
+const results = createTestResults();
+const envManager = new EnvManager();
+
+async function runTests() {
+  console.log('🧪 Testing: url-security.ts\n');
+
+  await testFunction('isPrivateIpv4 blocks CGNAT boundaries', () => {
+    assert.equal(isPrivateIpv4('100.64.0.1'), true);
+    assert.equal(isPrivateIpv4('100.127.255.255'), true);
+    assert.equal(isPrivateIpv4('100.63.255.255'), false);
+    assert.equal(isPrivateIpv4('100.128.0.0'), false);
+  }, results);
+
+  await testFunction('isPrivateIpv4 blocks benchmarking boundaries', () => {
+    assert.equal(isPrivateIpv4('198.18.0.1'), true);
+    assert.equal(isPrivateIpv4('198.19.255.255'), true);
+    assert.equal(isPrivateIpv4('198.20.0.0'), false);
+  }, results);
+
+  await testFunction('isPrivateIpv4 blocks multicast and reserved ranges', () => {
+    assert.equal(isPrivateIpv4('224.0.0.1'), true);
+    assert.equal(isPrivateIpv4('239.255.255.255'), true);
+    assert.equal(isPrivateIpv4('240.0.0.1'), true);
+    assert.equal(isPrivateIpv4('255.255.255.255'), true);
+  }, results);
+
+  await testFunction('isPrivateIpv4 blocks IANA special-purpose documentation ranges', () => {
+    assert.equal(isPrivateIpv4('192.0.0.1'), true);
+    assert.equal(isPrivateIpv4('192.0.2.5'), true);
+    assert.equal(isPrivateIpv4('198.51.100.5'), true);
+    assert.equal(isPrivateIpv4('203.0.113.5'), true);
+  }, results);
+
+  await testFunction('isPrivateIpv4 allows public control addresses', () => {
+    assert.equal(isPrivateIpv4('8.8.8.8'), false);
+    assert.equal(isPrivateIpv4('1.1.1.1'), false);
+    assert.equal(isPrivateIpv4('100.128.0.5'), false);
+  }, results);
+
+  await testFunction('isPrivateIPv6 delegates IPv4-mapped CGNAT addresses to IPv4 check', () => {
+    assert.equal(isPrivateIPv6('::ffff:100.64.0.1'), true);
+  }, results);
+
+  await testFunction('assertUrlAllowed blocks CGNAT by default and honors private URL override', () => {
+    envManager.delete('MCP_HTTP_HARDEN');
+    envManager.delete('MCP_HTTP_ALLOW_PRIVATE_URLS');
+
+    try {
+      assert.throws(
+        () => assertUrlAllowed(new URL('http://100.64.0.1/')),
+        /blocked by security policy/,
+      );
+
+      envManager.set('MCP_HTTP_ALLOW_PRIVATE_URLS', 'true');
+      assert.doesNotThrow(() => assertUrlAllowed(new URL('http://100.64.0.1/')));
+    } finally {
+      envManager.restore();
+    }
+  }, results);
+
+  printTestSummary(results, 'URL Security Module');
+  return results;
+}
+
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+  runTests().then(results => {
+    process.exit(results.failed > 0 ? 1 : 0);
+  }).catch(console.error);
+}
+
+export { runTests };

src/url-security.ts

@@ -9,19 +9,40 @@ export function isPrivateHostname(hostname: string): boolean {
   return lower === "localhost" || lower.endsWith(".localhost");
 }
 
+function ipv4ToInt(ip: string): number {
+  return ip.split(".").reduce((acc, octet) => (acc << 8) + Number(octet), 0) >>> 0;
+}
+
+// IANA special-purpose IPv4 ranges beyond the existing RFC1918/link-local checks.
+const BLOCKED_V4_CIDRS: [number, number][] = [
+  [ipv4ToInt("100.64.0.0"), 10],   // CGNAT (RFC 6598) - Tailscale default, overlays
+  [ipv4ToInt("192.0.0.0"), 24],    // IETF protocol assignments
+  [ipv4ToInt("192.0.2.0"), 24],    // TEST-NET-1
+  [ipv4ToInt("198.18.0.0"), 15],   // benchmarking (RFC 2544)
+  [ipv4ToInt("198.51.100.0"), 24], // TEST-NET-2
+  [ipv4ToInt("203.0.113.0"), 24],  // TEST-NET-3
+  [ipv4ToInt("224.0.0.0"), 4],     // multicast
+  [ipv4ToInt("240.0.0.0"), 4],     // reserved / 255.255.255.255 broadcast
+];
+
 export function isPrivateIpv4(hostname: string): boolean {
   if (isIP(hostname) !== 4) {
     return false;
   }
 
-  return (
+  if (
     hostname.startsWith("0.") ||
     hostname.startsWith("10.") ||
     hostname.startsWith("127.") ||
     hostname.startsWith("192.168.") ||
     /^172\.(1[6-9]|2\d|3[0-1])\./.test(hostname) ||
     hostname.startsWith("169.254.")
-  );
+  ) {
+    return true;
+  }
+
+  const ip = ipv4ToInt(hostname);
+  return BLOCKED_V4_CIDRS.some(([net, bits]) => ((ip ^ net) >>> (32 - bits)) === 0);
 }
 
 export function isPrivateIPv6(hostname: string): boolean {