Hartmut/Nexus
1
0
Fork 0
Code Issues 11 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

security: SSRF guard covers IPv6 + DNS-rebind defence via pinned IP (#49)

Browse Source 
Expand the SSRF blocklist from IPv4-only to IPv6 loopback/ULA (fc00::/7)/
link-local (fe80::/10)/multicast/IPv4-mapped, plus the missing IPv4 ranges
0.0.0.0/8, 100.64.0.0/10 CGNAT, and TEST-NET/benchmark ranges. Replace the
single-lookup SSRF guard with resolveAndValidate(): resolves all DNS records
(lookup { all: true }) so a hostname returning "public + private" is
rejected, and returns the first validated address for connection pinning.

The webhook dispatcher now switches from plain fetch() to https.request()
with a custom Agent.lookup that returns the pre-validated IP. A DNS rebind
between the guard check and the TCP connect() can no longer redirect the
dial to an internal address. Hostname still flows through for SNI and
certificate validation.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Hartmut Nörenberg
2026-04-17 09:19:07 +02:00
parent 3222bec8a5
commit 4ff7bc90c3
7 changed files with 467 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/api/src/__tests__/ssrf-guard.test.ts
+125 -42
View File
@@ -1,16 +1,17 @@
import { describe, expect, it, vi } from "vitest";
import { assertWebhookUrlAllowed } from "../lib/ssrf-guard.js";
import { __test__, assertWebhookUrlAllowed, resolveAndValidate } from "../lib/ssrf-guard.js";
// Mock dns.lookup so tests do not require real DNS resolution.
// The guard now calls lookup(host, { all: true }) and receives an array.
vi.mock("node:dns/promises", () => ({
lookup: vi.fn(async (hostname: string) => {
const mapping: Record<string, string> = {
"example.com": "93.184.216.34",
"hooks.external.io": "52.1.2.3",
const mapping: Record<string, Array<{ address: string; family: number }>> = {
"example.com": [{ address: "93.184.216.34", family: 4 }],
"hooks.external.io": [{ address: "52.1.2.3", family: 4 }],
};
const ip = mapping[hostname];
if (!ip) throw new Error(`ENOTFOUND ${hostname}`);
return { address: ip, family: 4 };
const addrs = mapping[hostname];
if (!addrs) throw new Error(`ENOTFOUND ${hostname}`);
return addrs;
}),
}));
@@ -18,9 +19,7 @@ describe("assertWebhookUrlAllowed — SSRF guard", () => {
// ── Allowed targets ─────────────────────────────────────────────────────────
it("allows a valid HTTPS URL that resolves to a public IP", async () => {
await expect(
assertWebhookUrlAllowed("https://example.com/webhook"),
).resolves.toBeUndefined();
await expect(assertWebhookUrlAllowed("https://example.com/webhook")).resolves.toBeUndefined();
});
it("allows an HTTPS URL with a path and query string", async () => {
@@ -32,29 +31,29 @@ describe("assertWebhookUrlAllowed — SSRF guard", () => {
// ── Rejected schemes ─────────────────────────────────────────────────────────
it("rejects an HTTP URL (only HTTPS allowed)", async () => {
await expect(
assertWebhookUrlAllowed("http://example.com/webhook"),
).rejects.toMatchObject({ code: "BAD_REQUEST" });
await expect(assertWebhookUrlAllowed("http://example.com/webhook")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects an FTP URL", async () => {
await expect(
assertWebhookUrlAllowed("ftp://example.com/file"),
).rejects.toMatchObject({ code: "BAD_REQUEST" });
await expect(assertWebhookUrlAllowed("ftp://example.com/file")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects a completely invalid URL", async () => {
await expect(
assertWebhookUrlAllowed("not-a-url"),
).rejects.toMatchObject({ code: "BAD_REQUEST" });
await expect(assertWebhookUrlAllowed("not-a-url")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
// ── Blocked hostnames ────────────────────────────────────────────────────────
it("rejects localhost by hostname", async () => {
await expect(
assertWebhookUrlAllowed("https://localhost/callback"),
).rejects.toMatchObject({ code: "BAD_REQUEST" });
await expect(assertWebhookUrlAllowed("https://localhost/callback")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects the AWS cloud metadata endpoint by hostname", async () => {
@@ -72,39 +71,39 @@ describe("assertWebhookUrlAllowed — SSRF guard", () => {
// ── Blocked IP ranges (direct IP addresses as hostname) ─────────────────────
it("rejects IPv4 loopback 127.0.0.1", async () => {
await expect(
assertWebhookUrlAllowed("https://127.0.0.1/callback"),
).rejects.toMatchObject({ code: "BAD_REQUEST" });
await expect(assertWebhookUrlAllowed("https://127.0.0.1/callback")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects IPv4 loopback 127.1.2.3 (full /8 block)", async () => {
await expect(
assertWebhookUrlAllowed("https://127.1.2.3/callback"),
).rejects.toMatchObject({ code: "BAD_REQUEST" });
await expect(assertWebhookUrlAllowed("https://127.1.2.3/callback")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects RFC 1918 private address 10.0.0.1", async () => {
await expect(
assertWebhookUrlAllowed("https://10.0.0.1/callback"),
).rejects.toMatchObject({ code: "BAD_REQUEST" });
await expect(assertWebhookUrlAllowed("https://10.0.0.1/callback")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects RFC 1918 private address 172.16.0.1", async () => {
await expect(
assertWebhookUrlAllowed("https://172.16.0.1/callback"),
).rejects.toMatchObject({ code: "BAD_REQUEST" });
await expect(assertWebhookUrlAllowed("https://172.16.0.1/callback")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects RFC 1918 private address 192.168.1.100", async () => {
await expect(
assertWebhookUrlAllowed("https://192.168.1.100/callback"),
).rejects.toMatchObject({ code: "BAD_REQUEST" });
await expect(assertWebhookUrlAllowed("https://192.168.1.100/callback")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects link-local address 169.254.1.1", async () => {
await expect(
assertWebhookUrlAllowed("https://169.254.1.1/callback"),
).rejects.toMatchObject({ code: "BAD_REQUEST" });
await expect(assertWebhookUrlAllowed("https://169.254.1.1/callback")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
// ── DNS fail-closed behaviour ────────────────────────────────────────────────
@@ -120,10 +119,94 @@ describe("assertWebhookUrlAllowed — SSRF guard", () => {
it("rejects a public hostname that resolves to a private IP (DNS rebinding)", async () => {
const { lookup } = await import("node:dns/promises");
vi.mocked(lookup).mockResolvedValueOnce({ address: "192.168.0.1", family: 4 });
vi.mocked(lookup).mockResolvedValueOnce([{ address: "192.168.0.1", family: 4 }]);
await expect(assertWebhookUrlAllowed("https://rebind.example.com/hook")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects if ANY of the resolved addresses is private (multi-record attack)", async () => {
const { lookup } = await import("node:dns/promises");
vi.mocked(lookup).mockResolvedValueOnce([
{ address: "93.184.216.34", family: 4 },
{ address: "10.0.0.5", family: 4 },
]);
await expect(assertWebhookUrlAllowed("https://multi.example.com/hook")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("resolveAndValidate returns the first validated address for connection pinning", async () => {
const resolved = await resolveAndValidate("https://example.com/hook");
expect(resolved.address).toBe("93.184.216.34");
expect(resolved.family).toBe(4);
expect(resolved.hostname).toBe("example.com");
});
// ── IPv6 blocklist ───────────────────────────────────────────────────────────
it("rejects IPv6 loopback ::1", async () => {
await expect(assertWebhookUrlAllowed("https://[::1]/hook")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects IPv6 unique-local fc00::/7 (fc00::1)", async () => {
await expect(assertWebhookUrlAllowed("https://[fc00::1]/hook")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects IPv6 link-local fe80::/10 (fe80::1)", async () => {
await expect(assertWebhookUrlAllowed("https://[fe80::1]/hook")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects IPv4-mapped IPv6 (::ffff:192.168.1.1) pointing into private v4", async () => {
await expect(
assertWebhookUrlAllowed("https://rebind.example.com/hook"),
assertWebhookUrlAllowed("https://[::ffff:192.168.1.1]/hook"),
).rejects.toMatchObject({ code: "BAD_REQUEST" });
});
it("rejects IPv6 multicast (ff02::1)", async () => {
await expect(assertWebhookUrlAllowed("https://[ff02::1]/hook")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects 0.0.0.0/8", async () => {
await expect(assertWebhookUrlAllowed("https://0.0.0.0/hook")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("rejects 100.64.0.0/10 CGNAT", async () => {
await expect(assertWebhookUrlAllowed("https://100.64.1.1/hook")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
await expect(assertWebhookUrlAllowed("https://100.127.254.254/hook")).rejects.toMatchObject({
code: "BAD_REQUEST",
});
});
it("accepts a 100.x address outside the CGNAT /10 (100.63.x is public)", async () => {
// 100.63.x is not in 100.64.0.0/10 — it is part of the public IANA pool.
expect(__test__.isBlockedIpv4("100.63.1.1")).toBe(false);
});
it("rejects 198.18.0.0/15 benchmark and TEST-NET ranges", async () => {
expect(__test__.isBlockedIpv4("198.18.0.1")).toBe(true);
expect(__test__.isBlockedIpv4("192.0.2.1")).toBe(true);
expect(__test__.isBlockedIpv4("203.0.113.1")).toBe(true);
});
it("expandIpv6 normalises short-form addresses to full 8-group form", () => {
expect(__test__.expandIpv6("::1")).toBe("0000:0000:0000:0000:0000:0000:0000:0001");
expect(__test__.expandIpv6("fe80::1")).toBe("fe80:0000:0000:0000:0000:0000:0000:0001");
expect(__test__.expandIpv6("::ffff:192.168.1.1")).toBe(
"0000:0000:0000:0000:0000:ffff:c0a8:0101",
);
});
});