Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(mcp-host): harden SSRF classifier for special-purpose ranges

Alfredo Lopez0978c12942ea
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index fa85fc3a0..9feb4321f 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.471",
+ "version": "0.1.472",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.471",
+ "version": "0.1.472",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 2313280cd..07681f4d1 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.471",
+ "version": "0.1.472",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/core/net/__tests__/ssrf.test.ts b/mcp-host/src/core/net/__tests__/ssrf.test.ts
index d29d21a22..b0a77abad 100644
--- a/mcp-host/src/core/net/__tests__/ssrf.test.ts
+++ b/mcp-host/src/core/net/__tests__/ssrf.test.ts
@@ -19,22 +19,50 @@ const resolve6 = vi.mocked(dns.resolve6)
afterEach(() => vi.clearAllMocks())
+function literalUrl(ip: string): URL {
+ return ip.includes(':') ? new URL(`http://[${ip}]/`) : new URL(`http://${ip}/`)
+}
+
+const BLOCKED_SPECIAL_PURPOSE_ADDRESSES: readonly (readonly [string, string])[] = [
+ ['100.64.0.1', 'CGNAT (RFC 6598)'],
+ ['198.18.0.1', 'benchmarking (RFC 2544)'],
+ ['224.0.0.1', 'IPv4 multicast'],
+ ['240.0.0.1', 'IPv4 reserved'],
+ ['255.255.255.255', 'IPv4 broadcast'],
+ ['64:ff9b::a9fe:a9fe', 'NAT64-wrapped cloud metadata'],
+ ['2002:a00:1::', '6to4-wrapped private IPv4'],
+ ['ff02::1', 'IPv6 multicast'],
+]
+
describe('resolvePinnedPublicIp', () => {
it('returns a public IP literal unchanged (no DNS)', async () => {
await expect(resolvePinnedPublicIp(new URL('https://8.8.8.8/x'))).resolves.toBe('8.8.8.8')
expect(resolve4).not.toHaveBeenCalled()
+ expect(resolve6).not.toHaveBeenCalled()
})
it('rejects a private IP literal', async () => {
await expect(resolvePinnedPublicIp(new URL('http://10.0.0.5/'))).rejects.toBeInstanceOf(
SsrfBlockedError
)
+ expect(resolve4).not.toHaveBeenCalled()
+ expect(resolve6).not.toHaveBeenCalled()
})
it('rejects the cloud-metadata IP literal', async () => {
await expect(
resolvePinnedPublicIp(new URL('http://169.254.169.254/latest/meta-data/'))
).rejects.toThrow(/private IP/)
+ expect(resolve4).not.toHaveBeenCalled()
+ expect(resolve6).not.toHaveBeenCalled()
+ })
+
+ it('returns a public IPv6 literal unchanged (no DNS)', async () => {
+ await expect(resolvePinnedPublicIp(new URL('https://[2606:4700:4700::1111]/'))).resolves.toBe(
+ '2606:4700:4700::1111'
+ )
+ expect(resolve4).not.toHaveBeenCalled()
+ expect(resolve6).not.toHaveBeenCalled()
})
it('resolves a hostname to a public IP and pins it', async () => {
@@ -60,6 +88,51 @@ describe('resolvePinnedPublicIp', () => {
/DNS resolution failed/
)
})
+
+ it.each(BLOCKED_SPECIAL_PURPOSE_ADDRESSES)(
+ 'rejects the %s IP literal (%s)',
+ async (ip: string) => {
+ const outcome = resolvePinnedPublicIp(literalUrl(ip))
+ await expect(outcome).rejects.toBeInstanceOf(SsrfBlockedError)
+ await expect(outcome).rejects.toThrow(`Target is a private IP (${ip})`)
+ expect(resolve4).not.toHaveBeenCalled()
+ expect(resolve6).not.toHaveBeenCalled()
+ }
+ )
+
+ it.each(BLOCKED_SPECIAL_PURPOSE_ADDRESSES)(
+ 'rejects a hostname resolving to %s (%s)',
+ async (ip: string) => {
+ const isV6 = ip.includes(':')
+ resolve4.mockResolvedValue(isV6 ? [] : [ip])
+ resolve6.mockResolvedValue(isV6 ? [ip] : [])
+ const outcome = resolvePinnedPublicIp(new URL('https://blocked.example.com/'))
+ await expect(outcome).rejects.toBeInstanceOf(SsrfBlockedError)
+ await expect(outcome).rejects.toThrow(`Domain resolves to private IP (${ip})`)
+ }
+ )
+
+ it.each([
+ ['64:ff9b::808:808', 'NAT64 form of public 8.8.8.8'],
+ ['2002:808:808::', '6to4 form of public 8.8.8.8'],
+ ])(
+ 'rejects the %s literal outright (%s): prefix policy without embedded-IPv4 extraction',
+ async (ip: string) => {
+ const outcome = resolvePinnedPublicIp(literalUrl(ip))
+ await expect(outcome).rejects.toBeInstanceOf(SsrfBlockedError)
+ await expect(outcome).rejects.toThrow(`Target is a private IP (${ip})`)
+ expect(resolve4).not.toHaveBeenCalled()
+ expect(resolve6).not.toHaveBeenCalled()
+ }
+ )
+
+ it('rejects a hostname with a public A record and a NAT64 AAAA record (DNS64 policy)', async () => {
+ resolve4.mockResolvedValue(['93.184.216.34'])
+ resolve6.mockResolvedValue(['64:ff9b::808:808'])
+ const outcome = resolvePinnedPublicIp(new URL('https://dns64.example.com/'))
+ await expect(outcome).rejects.toBeInstanceOf(SsrfBlockedError)
+ await expect(outcome).rejects.toThrow('Domain resolves to private IP (64:ff9b::808:808)')
+ })
})
describe('requestPinned — bounded in time and bytes', () => {
diff --git a/mcp-host/src/core/net/ssrf.ts b/mcp-host/src/core/net/ssrf.ts
index f2312cdec..16a6542b5 100644
--- a/mcp-host/src/core/net/ssrf.ts
+++ b/mcp-host/src/core/net/ssrf.ts
@@ -4,8 +4,8 @@
*
* The guarantees:
* - `isPrivateIp` classifies an IP (v4/v6, incl. IPv4-mapped/compatible forms)
- * as private/loopback/link-local/metadata/reserved — fail-closed on
- * unparseable-but-v6-looking literals.
+ * as private/loopback/link-local/metadata/reserved/special-purpose —
+ * fail-closed on unparseable-but-v6-looking literals.
* - `resolvePinnedPublicIp` validates a URL's host resolves ONLY to public
* addresses and returns a single pinned IP, so the caller connects to the
* exact address that was validated (closing the DNS-rebinding window).
@@ -120,30 +120,86 @@ function isIpv4MappedBytes(bytes: Uint8Array): boolean {
return bytes[10] === 0xff && bytes[11] === 0xff
}
+function formatIpv6Bytes(bytes: Uint8Array): string {
+ const groups: string[] = []
+ for (let i = 0; i < 16; i += 2) {
+ groups.push((((bytes[i]! << 8) | bytes[i + 1]!) & 0xffff).toString(16))
+ }
+ return groups.join(':')
+}
+
function isPrivateIpv4Octets(octets: readonly number[]): boolean {
if (octets.length !== 4) return false
- const [a = 0, b = 0] = octets
- return (
- a === 10 ||
- a === 127 ||
- (a === 172 && b >= 16 && b <= 31) ||
- (a === 192 && b === 168) ||
- (a === 169 && b === 254) ||
- a === 0
- )
+ return nonPublicAddresses.check(`${octets[0]}.${octets[1]}.${octets[2]}.${octets[3]}`, 'ipv4')
+}
+
+/**
+ * Canonical non-public IPv4 prefixes. Mirrors the IPv4 exclusions in
+ * deploy/base/public-egress-exceptions.yaml (rule-level egress exceptions) and
+ * the IANA range list used by mcp-servers/web-search's fetch destination
+ * validator; keep the lists aligned when one changes.
+ */
+const NON_PUBLIC_IPV4_PREFIXES: readonly (readonly [address: string, prefix: number])[] = [
+ ['0.0.0.0', 8], // "This network"
+ ['10.0.0.0', 8], // RFC 1918 private
+ ['100.64.0.0', 10], // CGNAT (RFC 6598)
+ ['127.0.0.0', 8], // Loopback
+ ['169.254.0.0', 16], // Link-local / cloud metadata
+ ['172.16.0.0', 12], // RFC 1918 private
+ ['192.0.0.0', 24], // IANA special purpose
+ ['192.0.2.0', 24], // TEST-NET-1 (RFC 5737)
+ ['192.168.0.0', 16], // RFC 1918 private
+ ['198.18.0.0', 15], // Benchmarking (RFC 2544)
+ ['198.51.100.0', 24], // TEST-NET-2 (RFC 5737)
+ ['203.0.113.0', 24], // TEST-NET-3 (RFC 5737)
+ ['224.0.0.0', 4], // Multicast
+ ['240.0.0.0', 4], // Reserved, including broadcast
+]
+
+/**
+ * Canonical non-public IPv6 prefixes. ::/128 and ::1/128 are covered by the
+ * IPv4-compatible delegation (their tails fall inside 0.0.0.0/8).
+ */
+const NON_PUBLIC_IPV6_PREFIXES: readonly (readonly [address: string, prefix: number])[] = [
+ ['64:ff9b::', 96], // NAT64 (RFC 6052)
+ ['64:ff9b:1::', 48], // Local-use NAT64 (RFC 8215)
+ ['2001::', 32], // Teredo
+ ['2001:db8::', 32], // Documentation (RFC 3849)
+ ['2002::', 16], // 6to4 (RFC 3056)
+ ['fc00::', 7], // Unique local
+ ['fe80::', 10], // Link-local
+ ['fec0::', 10], // Deprecated site-local
+ ['ff00::', 8], // Multicast
+]
+
+const nonPublicAddresses = new net.BlockList()
+for (const [address, prefix] of NON_PUBLIC_IPV4_PREFIXES) {
+ nonPublicAddresses.addSubnet(address, prefix, 'ipv4')
+}
+for (const [address, prefix] of NON_PUBLIC_IPV6_PREFIXES) {
+ nonPublicAddresses.addSubnet(address, prefix, 'ipv6')
}
/**
- * Block private and metadata IP ranges (SSRF defense).
+ * Block private, metadata, multicast, reserved, and other special-purpose
+ * non-public IP ranges (SSRF defense).
*
- * IPv4 ranges: 10/8, 127/8, 172.16/12, 192.168/16, 169.254/16 (metadata), 0/8.
- * IPv6 ranges: ::/128, ::1/128, fc00::/7, fe80::/10, fec0::/10, plus
- * IPv4-mapped/compatible forms delegated to the IPv4 rules.
+ * Policy notes:
+ * - NAT64 (RFC 6052; local-use RFC 8215) and 6to4 (RFC 3056) prefixes are
+ * blocked outright instead of extracting the embedded IPv4: translation
+ * depends on the local gateway, and RFC 8215 embeds are not universally
+ * IPv4 tails. Consequence: a hostname with a public A record plus a NAT64
+ * AAAA record is still rejected (DNS64 environments may be affected).
+ * - IPv4-mapped (::ffff:0:0/96) and IPv4-compatible (::/96) forms delegate
+ * the embedded IPv4 tail to the IPv4 rules.
+ * - Ordinary hostnames and non-IP strings return false; DNS verification
+ * lives in resolvePinnedPublicIp. Only unparseable-but-IPv6-looking
+ * literals fail closed.
*/
export function isPrivateIp(ip: string): boolean {
if (typeof ip !== 'string' || ip.length === 0) return false
- // IPv6 path — normalize and test against known private prefixes bit-for-bit.
+ // IPv6 path — normalize and evaluate the parsed bytes against the prefix table.
if (ip.includes(':')) {
const bytes = parseIpv6ToBytes(ip)
if (!bytes) {
@@ -151,23 +207,6 @@ export function isPrivateIp(ip: string): boolean {
return true
}
- // ::/128 unspecified and ::1/128 loopback
- let allZero = true
- for (let i = 0; i < 15; i++) {
- if (bytes[i] !== 0) {
- allZero = false
- break
- }
- }
- if (allZero && (bytes[15] === 0 || bytes[15] === 1)) return true
-
- // fc00::/7 (unique local)
- if ((bytes[0]! & 0xfe) === 0xfc) return true
-
- // fe80::/10 (link-local) and fec0::/10 (deprecated site-local)
- if (bytes[0] === 0xfe && (bytes[1]! & 0xc0) === 0x80) return true
- if (bytes[0] === 0xfe && (bytes[1]! & 0xc0) === 0xc0) return true
-
// ::ffff:0:0/96 IPv4-mapped — delegate to IPv4 rules.
if (isIpv4MappedBytes(bytes)) {
return isPrivateIpv4Octets([bytes[12]!, bytes[13]!, bytes[14]!, bytes[15]!])
@@ -176,9 +215,8 @@ export function isPrivateIp(ip: string): boolean {
// IPv4-compatible ::x.x.x.x (bytes[0..11]==0, bytes[10..11] NOT 0xffff).
// Form is deprecated but still parseable; attackers use it to wrap a
// private v4 target inside a literal that survives naive v6 checks.
- // `::` (all-zero) and `::1` were already matched by the unspecified
- // + loopback block above, so any surviving first-12-zero address here
- // is a genuine embedded IPv4.
+ // `::` (all-zero) and `::1` also land here; their tails (0.0.0.0/0.0.0.1)
+ // fall inside 0.0.0.0/8, preserving the unspecified + loopback block.
let first12AllZero = true
for (let i = 0; i < 12; i++) {
if (bytes[i] !== 0) {
@@ -190,15 +228,16 @@ export function isPrivateIp(ip: string): boolean {
return isPrivateIpv4Octets([bytes[12]!, bytes[13]!, bytes[14]!, bytes[15]!])
}
- return false
+ return nonPublicAddresses.check(formatIpv6Bytes(bytes), 'ipv6')
}
- // IPv4 path
+ // IPv4 path. A full dotted quad is required; hostnames and other strings
+ // fall through as non-IP (false).
const parts = ip.split('.').map(p => Number(p))
if (parts.length !== 4 || parts.some(n => !Number.isInteger(n) || n < 0 || n > 255)) {
return false
}
- return isPrivateIpv4Octets(parts)
+ return nonPublicAddresses.check(`${parts[0]}.${parts[1]}.${parts[2]}.${parts[3]}`, 'ipv4')
}
/**
diff --git a/mcp-host/src/core/tools/__tests__/shellAndHttp.test.ts b/mcp-host/src/core/tools/__tests__/shellAndHttp.test.ts
index 1c053d898..3217b8664 100644
--- a/mcp-host/src/core/tools/__tests__/shellAndHttp.test.ts
+++ b/mcp-host/src/core/tools/__tests__/shellAndHttp.test.ts
@@ -132,7 +132,7 @@ describe('HttpRequestTool', () => {
expect(isPrivateIp('fe80::1')).toBe(true) // Link-local
expect(isPrivateIp('::ffff:10.0.0.1')).toBe(true) // IPv4-mapped private
expect(isPrivateIp('::ffff:192.168.1.1')).toBe(true) // IPv4-mapped private
- expect(isPrivateIp('2001:db8::1')).toBe(false) // Documentation (public-ish)
+ expect(isPrivateIp('2001:db8::1')).toBe(true) // Documentation (non-public)
expect(isPrivateIp('2607:f8b0::1')).toBe(false) // Google public
})
@@ -184,4 +184,85 @@ describe('HttpRequestTool', () => {
expect(isPrivateIp('::8.8.8.8')).toBe(false)
expect(isPrivateIp('::1.1.1.1')).toBe(false)
})
+
+ it('should classify special-purpose IPv4 ranges as private', () => {
+ // CGNAT (RFC 6598) with range boundaries and public neighbors.
+ expect(isPrivateIp('100.64.0.0')).toBe(true)
+ expect(isPrivateIp('100.64.0.1')).toBe(true)
+ expect(isPrivateIp('100.127.255.255')).toBe(true)
+ expect(isPrivateIp('100.63.255.255')).toBe(false) // Public neighbor
+ expect(isPrivateIp('100.128.0.0')).toBe(false) // Public neighbor
+ // Benchmarking (RFC 2544) with range boundaries and public neighbors.
+ expect(isPrivateIp('198.18.0.0')).toBe(true)
+ expect(isPrivateIp('198.18.0.1')).toBe(true)
+ expect(isPrivateIp('198.19.255.255')).toBe(true)
+ expect(isPrivateIp('198.17.255.255')).toBe(false) // Public neighbor
+ expect(isPrivateIp('198.20.0.0')).toBe(false) // Public neighbor
+ // Multicast and reserved, including the broadcast address.
+ expect(isPrivateIp('224.0.0.1')).toBe(true)
+ expect(isPrivateIp('239.255.255.255')).toBe(true)
+ expect(isPrivateIp('240.0.0.1')).toBe(true)
+ expect(isPrivateIp('255.255.255.255')).toBe(true)
+ // IANA special-purpose /24 blocks.
+ expect(isPrivateIp('192.0.0.1')).toBe(true)
+ expect(isPrivateIp('192.0.2.1')).toBe(true)
+ expect(isPrivateIp('198.51.100.1')).toBe(true)
+ expect(isPrivateIp('203.0.113.1')).toBe(true)
+ // Public controls.
+ expect(isPrivateIp('8.8.8.8')).toBe(false)
+ expect(isPrivateIp('1.1.1.1')).toBe(false)
+ })
+
+ it('should classify special-purpose IPv6 ranges as private', () => {
+ // NAT64 (RFC 6052) and local-use (RFC 8215).
+ expect(isPrivateIp('64:ff9b::a9fe:a9fe')).toBe(true)
+ expect(isPrivateIp('64:ff9b:1::1')).toBe(true)
+ // 6to4 (RFC 3056).
+ expect(isPrivateIp('2002:a00:1::')).toBe(true)
+ expect(isPrivateIp('2002::1')).toBe(true)
+ // Multicast.
+ expect(isPrivateIp('ff02::1')).toBe(true)
+ expect(isPrivateIp('ff0e::1')).toBe(true)
+ // Teredo.
+ expect(isPrivateIp('2001::1')).toBe(true)
+ // Documentation (RFC 3849).
+ expect(isPrivateIp('2001:db8::1')).toBe(true)
+ expect(isPrivateIp('2001:db8:ffff:ffff:ffff:ffff:ffff:ffff')).toBe(true)
+ // Public controls.
+ expect(isPrivateIp('2607:f8b0::1')).toBe(false)
+ expect(isPrivateIp('2606:4700:4700::1111')).toBe(false)
+ })
+
+ it('should block NAT64/6to4 prefixes outright, even with public IPv4 payloads', () => {
+ // Policy choice: block the prefix rather than extract the embedded IPv4.
+ // Translation depends on the local gateway, and RFC 8215 local-use embeds
+ // are not universally IPv4 tails. A public A record plus a NAT64 AAAA is
+ // therefore rejected too (DNS64 environments may be affected).
+ expect(isPrivateIp('64:ff9b::808:808')).toBe(true) // NAT64 form of 8.8.8.8
+ expect(isPrivateIp('2002:808:808::')).toBe(true) // 6to4 form of 8.8.8.8
+ })
+
+ it('should block new special-purpose IPv4 through mapped/compatible IPv6 forms', () => {
+ // IPv4-mapped, dotted quad.
+ expect(isPrivateIp('::ffff:100.64.0.1')).toBe(true)
+ expect(isPrivateIp('::ffff:198.18.0.1')).toBe(true)
+ expect(isPrivateIp('::ffff:224.0.0.1')).toBe(true)
+ expect(isPrivateIp('::ffff:240.0.0.1')).toBe(true)
+ expect(isPrivateIp('::ffff:192.0.2.1')).toBe(true)
+ expect(isPrivateIp('::ffff:203.0.113.1')).toBe(true)
+ // IPv4-mapped, hexadecimal.
+ expect(isPrivateIp('::ffff:6440:1')).toBe(true) // 100.64.0.1
+ expect(isPrivateIp('::ffff:c612:1')).toBe(true) // 198.18.0.1
+ expect(isPrivateIp('::ffff:808:808')).toBe(false) // Public 8.8.8.8
+ // IPv4-compatible, dotted quad.
+ expect(isPrivateIp('::100.64.0.1')).toBe(true)
+ expect(isPrivateIp('::198.18.0.1')).toBe(true)
+ expect(isPrivateIp('::8.8.8.8')).toBe(false) // Public control
+ })
+
+ it('should keep hostnames and non-IP strings outside the private classifier', () => {
+ expect(isPrivateIp('example.com')).toBe(false)
+ expect(isPrivateIp('sub.domain.example.com')).toBe(false)
+ expect(isPrivateIp('not-an-ip')).toBe(false)
+ })
})