Merge pull request #888 from AikidoSec/ipv4-mapped-ipv6

hansott · web-flow · commit 5a97aab96919 · 2026-01-16T15:26:11.000+01:00
Improve support for IPv4 mapped IPv6 addresses
diff --git a/end2end/tests/hono-xml-allowlists.test.ts b/end2end/tests/hono-xml-allowlists.test.ts
@@ -185,6 +185,19 @@ t.test("it blocks non-allowed IP addresses", (t) => {
         signal: AbortSignal.timeout(5000),
       });
       t.same(resp8.status, 403);
+
+      // IPv4-mapped IPv6 address should also be allowed (matches 4.3.2.1/32)
+      const resp9 = await fetch("http://127.0.0.1:4002/add", {
+        method: "POST",
+        body: "<cat><name>Mapped</name></cat>",
+        headers: {
+          "Content-Type": "application/xml",
+          "X-Forwarded-For": "::ffff:4.3.2.1",
+        },
+        signal: AbortSignal.timeout(5000),
+      });
+      t.same(resp9.status, 200);
+      t.same(await resp9.text(), JSON.stringify({ success: true }));
     })
     .catch((error) => {
       t.fail(error);
diff --git a/end2end/tests/hono-xml-blocklists.test.js b/end2end/tests/hono-xml-blocklists.test.js
@@ -143,6 +143,22 @@ t.test("it blocks geo restricted IPs", (t) => {
       });
       t.same(resp3.status, 200);
       t.same(await resp3.text(), JSON.stringify({ success: true }));
+
+      // IPv4-mapped IPv6 address should also be blocked (matches 1.3.2.0/24)
+      const resp4 = await fetch("http://127.0.0.1:4002/add", {
+        method: "POST",
+        body: "<cat><name>Mapped</name></cat>",
+        headers: {
+          "Content-Type": "application/xml",
+          "X-Forwarded-For": "::ffff:1.3.2.4",
+        },
+        signal: AbortSignal.timeout(5000),
+      });
+      t.same(resp4.status, 403);
+      t.same(
+        await resp4.text(),
+        "Your IP address is blocked due to geo restrictions. (Your IP: ::ffff:1.3.2.4)"
+      );
     })
     .catch((error) => {
       t.fail(error);
@@ -305,6 +321,24 @@ t.test("it does not block bypass IP if in blocklist", (t) => {
         await resp3.text(),
         `Your IP address is not allowed to access this resource. (Your IP: 1.3.2.2)`
       );
+
+      // IPv4-mapped IPv6 address should also bypass (matches bypass list 1.3.2.1)
+      const resp4 = await fetch("http://127.0.0.1:4004/", {
+        headers: {
+          "X-Forwarded-For": "::ffff:1.3.2.1",
+        },
+        signal: AbortSignal.timeout(5000),
+      });
+      t.same(resp4.status, 200);
+
+      // IPv4-mapped IPv6 address should also access endpoint allowlist
+      const resp5 = await fetch("http://127.0.0.1:4004/admin", {
+        headers: {
+          "X-Forwarded-For": "::ffff:1.3.2.1",
+        },
+        signal: AbortSignal.timeout(5000),
+      });
+      t.same(resp5.status, 200);
     })
     .catch((error) => {
       t.fail(error);
diff --git a/library/agent/ServiceConfig.ts b/library/agent/ServiceConfig.ts
@@ -1,3 +1,4 @@
+import { addIPv4MappedAddresses } from "../helpers/addIPv4MappedAddresses";
 import { IPMatcher } from "../helpers/ip-matcher/IPMatcher";
 import { LimitedContext, matchEndpoints } from "../helpers/matchEndpoints";
 import { isPrivateIP } from "../vulnerabilities/ssrf/isPrivateIP";
@@ -50,12 +51,15 @@ export class ServiceConfig {
     this.graphqlFields = [];
 
     for (const endpoint of endpointConfigs) {
-      let allowedIPAddresses = undefined;
+      let allowedIPAddresses: IPMatcher | undefined = undefined;
       if (
         Array.isArray(endpoint.allowedIPAddresses) &&
         endpoint.allowedIPAddresses.length > 0
       ) {
-        allowedIPAddresses = new IPMatcher(endpoint.allowedIPAddresses);
+        // Small list, frequently accessed: add IPv4-mapped versions at creation time for fast lookups
+        allowedIPAddresses = new IPMatcher(
+          addIPv4MappedAddresses(endpoint.allowedIPAddresses)
+        );
       }
 
       const endpointConfig = { ...endpoint, allowedIPAddresses };
@@ -98,7 +102,10 @@ export class ServiceConfig {
       this.bypassedIPAddresses = undefined;
       return;
     }
-    this.bypassedIPAddresses = new IPMatcher(ipAddresses);
+    // Small list, frequently accessed: add IPv4-mapped versions at creation time for fast lookups
+    this.bypassedIPAddresses = new IPMatcher(
+      addIPv4MappedAddresses(ipAddresses)
+    );
   }
 
   isBypassedIP(ip: string) {
@@ -119,8 +126,8 @@ export class ServiceConfig {
   isIPAddressBlocked(
     ip: string
   ): { blocked: true; reason: string } | { blocked: false } {
-    const blocklist = this.blockedIPAddresses.find((blocklist) =>
-      blocklist.blocklist.has(ip)
+    const blocklist = this.blockedIPAddresses.find((list) =>
+      list.blocklist.hasWithMappedCheck(ip)
     );
 
     if (blocklist) {
@@ -136,6 +143,7 @@ export class ServiceConfig {
     for (const source of blockedIPAddresses) {
       this.blockedIPAddresses.push({
         key: source.key,
+        // Large list: IPv4-mapped checked at lookup time to save memory
         blocklist: new IPMatcher(source.ips),
         description: source.description,
       });
@@ -152,6 +160,7 @@ export class ServiceConfig {
     for (const source of monitoredIPAddresses) {
       this.monitoredIPAddresses.push({
         key: source.key,
+        // Large list: IPv4-mapped checked at lookup time to save memory
         list: new IPMatcher(source.ips),
       });
     }
@@ -213,13 +222,13 @@ export class ServiceConfig {
 
   getMatchingBlockedIPListKeys(ip: string): string[] {
     return this.blockedIPAddresses
-      .filter((list) => list.blocklist.has(ip))
+      .filter((list) => list.blocklist.hasWithMappedCheck(ip))
       .map((list) => list.key);
   }
 
   getMatchingMonitoredIPListKeys(ip: string): string[] {
     return this.monitoredIPAddresses
-      .filter((list) => list.list.has(ip))
+      .filter((list) => list.list.hasWithMappedCheck(ip))
       .map((list) => list.key);
   }
 
@@ -232,6 +241,7 @@ export class ServiceConfig {
         continue;
       }
       this.allowedIPAddresses.push({
+        // Large list: IPv4-mapped checked at lookup time to save memory
         allowlist: new IPMatcher(source.ips),
         description: source.description,
       });
@@ -253,7 +263,7 @@ export class ServiceConfig {
     }
 
     const allowlist = this.allowedIPAddresses.find((list) =>
-      list.allowlist.has(ip)
+      list.allowlist.hasWithMappedCheck(ip)
     );
 
     return { allowed: !!allowlist };
diff --git a/library/helpers/addIPv4MappedAddresses.test.ts b/library/helpers/addIPv4MappedAddresses.test.ts
@@ -0,0 +1,41 @@
+import * as t from "tap";
+import { addIPv4MappedAddresses } from "./addIPv4MappedAddresses";
+
+t.test("it adds IPv4-mapped IPv6 addresses", async (t) => {
+  t.same(
+    addIPv4MappedAddresses([
+      "1.2.3.4",
+      "23.45.67.89/24",
+      "2606:2800:220:1:248:1893:25c8:1946",
+      "2001:0db9:abcd:1234::/64",
+    ]),
+    [
+      "1.2.3.4",
+      "23.45.67.89/24",
+      "2606:2800:220:1:248:1893:25c8:1946",
+      "2001:0db9:abcd:1234::/64",
+      "::ffff:1.2.3.4/128",
+      "::ffff:23.45.67.89/120",
+    ]
+  );
+});
+
+t.test("it handles empty array", async (t) => {
+  t.same(addIPv4MappedAddresses([]), []);
+});
+
+t.test("it handles only IPv6 addresses", async (t) => {
+  t.same(addIPv4MappedAddresses(["2001:db8::1", "::1"]), [
+    "2001:db8::1",
+    "::1",
+  ]);
+});
+
+t.test("it handles only IPv4 addresses", async (t) => {
+  t.same(addIPv4MappedAddresses(["1.2.3.4", "5.6.7.8"]), [
+    "1.2.3.4",
+    "5.6.7.8",
+    "::ffff:1.2.3.4/128",
+    "::ffff:5.6.7.8/128",
+  ]);
+});
diff --git a/library/helpers/addIPv4MappedAddresses.ts b/library/helpers/addIPv4MappedAddresses.ts
@@ -0,0 +1,11 @@
+import mapIPv4ToIPv6 from "./mapIPv4ToIPv6";
+
+/**
+ * Adds IPv4-mapped IPv6 versions for all IPv4 addresses in the array.
+ * e.g. ["1.2.3.4", "2001:db8::/32"] -> ["1.2.3.4", "2001:db8::/32", "::ffff:1.2.3.4/128"]
+ */
+export function addIPv4MappedAddresses(ips: string[]): string[] {
+  const ipv4Addresses = ips.filter((ip) => !ip.includes(":"));
+
+  return ips.concat(ipv4Addresses.map(mapIPv4ToIPv6));
+}
diff --git a/library/helpers/ip-matcher/IPMatcher.test.ts b/library/helpers/ip-matcher/IPMatcher.test.ts
@@ -204,3 +204,53 @@ t.test("allow all ips", async (t) => {
   t.same(matcher.has("10.0.0.255"), true);
   t.same(matcher.has("192.168.1.1"), true);
 });
+
+t.test("adjacent /4 ranges at end of address space", async (t) => {
+  // Regression test for Network.contains() bug
+  // 224.0.0.0/4 and 240.0.0.0/4 are adjacent ranges that should merge to 224.0.0.0/3
+  // The bug was that contains() incorrectly returned true when the other network's
+  // "next" address overflowed (240.0.0.0/4 extends to 255.255.255.255)
+  const matcher = new IPMatcher(["224.0.0.0/4", "240.0.0.0/4"]);
+
+  t.same(matcher.has("224.0.0.1"), true);
+  t.same(matcher.has("240.0.0.1"), true);
+  t.same(matcher.has("255.255.255.255"), true);
+  t.same(matcher.has("223.255.255.255"), false);
+});
+
+t.test("hasWithMappedCheck matches direct IPv4", async (t) => {
+  const matcher = new IPMatcher(["192.0.2.1"]);
+  t.same(matcher.hasWithMappedCheck("192.0.2.1"), true);
+  t.same(matcher.hasWithMappedCheck("192.0.2.2"), false);
+});
+
+t.test(
+  "hasWithMappedCheck matches IPv4-mapped IPv6 against IPv4 in list",
+  async (t) => {
+    const matcher = new IPMatcher(["192.0.2.1"]);
+    t.same(matcher.hasWithMappedCheck("::ffff:192.0.2.1"), true);
+    t.same(matcher.hasWithMappedCheck("::ffff:c000:201"), true);
+    t.same(matcher.hasWithMappedCheck("::ffff:192.0.2.2"), false);
+  }
+);
+
+t.test(
+  "hasWithMappedCheck matches IPv4-mapped IPv6 against IPv4 CIDR range",
+  async (t) => {
+    const matcher = new IPMatcher(["192.0.2.0/24"]);
+    t.same(matcher.hasWithMappedCheck("::ffff:192.0.2.1"), true);
+    t.same(matcher.hasWithMappedCheck("::ffff:192.0.2.255"), true);
+    t.same(matcher.hasWithMappedCheck("::ffff:192.0.3.1"), false);
+  }
+);
+
+t.test("hasWithMappedCheck matches direct IPv6", async (t) => {
+  const matcher = new IPMatcher(["2001:db8::1"]);
+  t.same(matcher.hasWithMappedCheck("2001:db8::1"), true);
+  t.same(matcher.hasWithMappedCheck("2001:db8::2"), false);
+});
+
+t.test("hasWithMappedCheck matches explicit IPv4-mapped in list", async (t) => {
+  const matcher = new IPMatcher(["::ffff:192.0.2.1"]);
+  t.same(matcher.hasWithMappedCheck("::ffff:192.0.2.1"), true);
+});
diff --git a/library/helpers/ip-matcher/IPMatcher.ts b/library/helpers/ip-matcher/IPMatcher.ts
@@ -53,4 +53,43 @@ export class IPMatcher {
     this.sorted.splice(idx, 0, net);
     return this;
   }
+
+  // Checks if the given IP address is in the list of networks,
+  // also checking the IPv4 address if it's an IPv4-mapped IPv6 address.
+  public hasWithMappedCheck(ip: string): boolean {
+    if (this.has(ip)) {
+      return true;
+    }
+
+    const ipv4 = this.extractIPv4FromMapped(ip);
+    if (ipv4) {
+      return this.has(ipv4);
+    }
+
+    return false;
+  }
+
+  private extractIPv4FromMapped(ip: string): string | null {
+    const net = new Network(ip);
+    if (!net.isValid()) {
+      return null;
+    }
+
+    const bytes = net.addr.bytes();
+    if (bytes.length !== 16) {
+      return null;
+    }
+
+    // Check IPv4-mapped: first 10 bytes = 0, bytes 10-11 = 0xffff
+    for (let i = 0; i < 10; i++) {
+      if (bytes[i] !== 0) {
+        return null;
+      }
+    }
+    if (bytes[10] !== 255 || bytes[11] !== 255) {
+      return null;
+    }
+
+    return `${bytes[12]}.${bytes[13]}.${bytes[14]}.${bytes[15]}`;
+  }
 }
diff --git a/library/helpers/ip-matcher/Network.ts b/library/helpers/ip-matcher/Network.ts
@@ -106,6 +106,10 @@ export class Network {
     // handle edge case where our next network address overflows
     if (!next.isValid()) return true;
 
+    // handle edge case where other network's next address overflows
+    // (it extends to end of address space, but we don't, so we can't contain it)
+    if (!otherNext.isValid()) return false;
+
     // our address should be more than or equal to the other address
     if (next.addr.compare(otherNext.addr) === BEFORE) return false;
 
diff --git a/library/vulnerabilities/ssrf/imds.ts b/library/vulnerabilities/ssrf/imds.ts
@@ -1,16 +1,17 @@
+import { addIPv4MappedAddresses } from "../../helpers/addIPv4MappedAddresses";
 import { IPMatcher } from "../../helpers/ip-matcher/IPMatcher";
-import mapIPv4ToIPv6 from "../../helpers/mapIPv4ToIPv6";
 
-const IMDSAddresses = new IPMatcher();
-
-// This IP address is used by AWS EC2 instances to access the instance metadata service (IMDS)
+// These IP addresses are used to access the instance metadata service (IMDS)
 // We should block any requests to these IP addresses
 // This prevents STORED SSRF attacks that try to access the instance metadata service
-IMDSAddresses.add("169.254.169.254");
-IMDSAddresses.add(mapIPv4ToIPv6("169.254.169.254"));
-IMDSAddresses.add("fd00:ec2::254");
-IMDSAddresses.add("100.100.100.200"); // Alibaba Cloud
-IMDSAddresses.add(mapIPv4ToIPv6("100.100.100.200"));
+// Small list, frequently accessed: add IPv4-mapped versions at creation time for fast lookups
+const IMDSAddresses = new IPMatcher(
+  addIPv4MappedAddresses([
+    "169.254.169.254",
+    "fd00:ec2::254",
+    "100.100.100.200",
+  ])
+);
 
 export function isIMDSIPAddress(ip: string): boolean {
   return IMDSAddresses.has(ip);
diff --git a/library/vulnerabilities/ssrf/isPrivateIP.ts b/library/vulnerabilities/ssrf/isPrivateIP.ts
@@ -1,5 +1,5 @@
+import { addIPv4MappedAddresses } from "../../helpers/addIPv4MappedAddresses";
 import { IPMatcher } from "../../helpers/ip-matcher/IPMatcher";
-import mapIPv4ToIPv6 from "../../helpers/mapIPv4ToIPv6";
 
 const PRIVATE_IP_RANGES = [
   "0.0.0.0/8", // "This" network (RFC 1122)
@@ -31,20 +31,13 @@ const PRIVATE_IPV6_RANGES = [
   "100::/64", // Discard prefix (RFC 6666)
   "2001:db8::/32", // Documentation prefix (RFC 3849)
   "3fff::/20", // Documentation prefix (RFC 9637)
-].concat(
-  // Add the IPv4-mapped IPv6 addresses
-  PRIVATE_IP_RANGES.map(mapIPv4ToIPv6)
-);
-
-const privateIp = new IPMatcher();
-
-PRIVATE_IP_RANGES.forEach((range) => {
-  privateIp.add(range);
-});
+];
 
-PRIVATE_IPV6_RANGES.forEach((range) => {
-  privateIp.add(range);
-});
+// Small list, frequently accessed: add IPv4-mapped versions at creation time for fast lookups
+const privateIp = new IPMatcher([
+  ...addIPv4MappedAddresses(PRIVATE_IP_RANGES),
+  ...PRIVATE_IPV6_RANGES,
+]);
 
 export function isPrivateIP(ip: string): boolean {
   return privateIp.has(ip);
