Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
fix(ssrf): pin the validated DNS answer for guarded fetches
SeashoreShi337e0a7e2e4d
diff --git a/package-lock.json b/package-lock.jsonindex f1c6e53c..c8b3c1ca 100644--- a/package-lock.json+++ b/package-lock.json@@ -1,12 +1,12 @@{"name": "@cosmicstack/mercury-agent",- "version": "1.2.5",+ "version": "1.2.7","lockfileVersion": 2,"requires": true,"packages": {"": {"name": "@cosmicstack/mercury-agent",- "version": "1.2.5",+ "version": "1.2.7","hasInstallScript": true,"license": "MIT","dependencies": {@@ -34,6 +34,7 @@"qrcode-terminal": "^0.12.0","react": "^18.3.1","sql.js": "^1.14.1",+ "undici": "^6.24.1","ws": "^8.21.0","yaml": "^2.7.0","zod": "^3.25.76"diff --git a/package.json b/package.jsonindex 1dd922b7..d7230bc5 100644--- a/package.json+++ b/package.json@@ -86,6 +86,7 @@"qrcode-terminal": "^0.12.0","react": "^18.3.1","sql.js": "^1.14.1",+ "undici": "^6.24.1","ws": "^8.21.0","yaml": "^2.7.0","zod": "^3.25.76"diff --git a/src/utils/ssrf.test.ts b/src/utils/ssrf.test.tsindex eeec94ed..36a0ab16 100644--- a/src/utils/ssrf.test.ts+++ b/src/utils/ssrf.test.ts@@ -1,5 +1,17 @@-import { describe, expect, it } from 'vitest';-import { isPrivateAddress } from './ssrf.js';+import { describe, expect, it, vi, beforeEach } from 'vitest';++vi.mock('node:dns', () => ({ lookup: vi.fn() }));++import { lookup } from 'node:dns';+import { assertFetchableTarget, isPrivateAddress } from './ssrf.js';++const mockedLookup = vi.mocked(lookup);++function mockDns(addresses: Array<{ address: string; family: number }>) {+ mockedLookup.mockImplementation(((_hostname: string, _options: unknown, callback: unknown) => {+ (callback as (err: unknown, addrs: unknown) => void)(null, addresses);+ }) as never);+}describe('isPrivateAddress', () => {it('flags loopback, private, link-local and CGNAT blocks', () => {@@ -37,6 +49,22 @@ describe('isPrivateAddress', () => {}});+ it('flags IPv6 special-use blocks', () => {+ for (const ip of [+ 'fe80::1', // link-local fe80::/10+ 'febf::1',+ 'fec0::1', // site-local fec0::/10 (deprecated)+ 'feff::1',+ 'fc00::1', // unique local fc00::/7+ 'fd12:3456:789a::1',+ 'ff02::1', // multicast ff00::/8+ '2001:db8::1', // documentation 2001:db8::/32+ '::ffff:10.0.0.1', // v4-mapped private+ ]) {+ expect(isPrivateAddress(ip), ip).toBe(true);+ }+ });+it('allows ordinary public addresses', () => {for (const ip of ['8.8.8.8',@@ -45,8 +73,35 @@ describe('isPrivateAddress', () => {'172.32.0.1','198.20.0.1','203.0.114.1',+ '2606:4700:4700::1111',+ '2001:4860:4860::8888',]) {expect(isPrivateAddress(ip), ip).toBe(false);}});});++describe('assertFetchableTarget', () => {+ beforeEach(() => {+ mockedLookup.mockReset();+ });++ it('rejects a hostname whose DNS answers mix public and private records', async () => {+ mockDns([+ { address: '93.184.216.34', family: 4 },+ { address: '10.0.0.5', family: 4 },+ ]);+ await expect(assertFetchableTarget('http://mixed.example')).rejects.toThrow(/private\/internal/);+ });++ it('accepts an all-public hostname', async () => {+ mockDns([{ address: '93.184.216.34', family: 4 }]);+ await expect(assertFetchableTarget('http://public.example')).resolves.toBeInstanceOf(URL);+ });++ it('rejects literal private hosts and non-http(s) schemes', async () => {+ await expect(assertFetchableTarget('http://127.0.0.1/')).rejects.toThrow(/private\/internal/);+ await expect(assertFetchableTarget('http://198.18.0.1/')).rejects.toThrow(/private\/internal/);+ await expect(assertFetchableTarget('file:///etc/passwd')).rejects.toThrow(/Blocked scheme/);+ });+});diff --git a/src/utils/ssrf.ts b/src/utils/ssrf.tsindex 08a7ea5b..54246847 100644--- a/src/utils/ssrf.ts+++ b/src/utils/ssrf.ts@@ -5,17 +5,30 @@* be validated: scheme, literal hosts, DNS-resolved addresses, and every* redirect hop (redirect: 'manual' — a public URL must not be able to hop* into a private one).+ *+ * Validation and connection are kept on the same address: the hostname is+ * resolved here, any answer containing a non-global address is rejected+ * (fail closed on DNS mixed answers), and the connection is pinned to the+ * exact address that was validated so a hostile resolver cannot swap in a+ * private address between the check and the fetch (TOCTOU / DNS rebinding).*/import { lookup } from 'node:dns';import { isIP } from 'node:net';+import { Agent } from 'undici';-export function isPrivateAddress(ip: string): boolean {- if (isIP(ip) === 0) return false;- if (ip === '::1' || ip === '::') return true;- if (ip.startsWith('fe80:') || ip.startsWith('fc') || ip.startsWith('fd')) return true;+const DEFAULT_HEADERS = {+ 'User-Agent': 'Mercury-Agent/0.1.0',+ 'Accept': 'text/html,application/json,text/plain',+};++const ALLOW_PRIVATE_FETCH = process.env.MERCURY_ALLOW_PRIVATE_FETCH === '1';++export const MAX_REDIRECTS = 5;++function isPrivateIpv4(ip: string): boolean {const v4 = ip.split('.').map((p) => parseInt(p, 10));- if (v4.length !== 4 || v4.some((p) => Number.isNaN(p))) return Boolean(ip.startsWith('::ffff:'));+ if (v4.length !== 4 || v4.some((p) => Number.isNaN(p) || p < 0 || p > 255)) return false;const [a, b, c] = v4;if (a === 0 || a === 10 || a === 127) return true;if (a === 169 && b === 254) return true; // link-local incl. cloud metadata@@ -33,7 +46,28 @@ export function isPrivateAddress(ip: string): boolean {return false;}-const ALLOW_PRIVATE_FETCH = process.env.MERCURY_ALLOW_PRIVATE_FETCH === '1';+function isPrivateIpv6(ip: string): boolean {+ const lower = ip.toLowerCase();+ if (lower === '::' || lower === '::1') return true;+ if (lower.startsWith('::ffff:')) {+ const mapped = lower.slice('::ffff:'.length);+ return isIP(mapped) === 4 ? isPrivateIpv4(mapped) : true;+ }+ const head = lower.split(':')[0] ?? '';+ if (/^fe[89ab]/.test(head)) return true; // fe80::/10 link-local+ if (/^fe[c-f]/.test(head)) return true; // fec0::/10 site-local (deprecated)+ if (/^f[cd]/.test(head)) return true; // fc00::/7 unique local+ if (/^ff/.test(head)) return true; // ff00::/8 multicast+ if (lower.startsWith('2001:db8')) return true; // 2001:db8::/32 documentation+ return false;+}++export function isPrivateAddress(ip: string): boolean {+ const family = isIP(ip);+ if (family === 4) return isPrivateIpv4(ip);+ if (family === 6) return isPrivateIpv6(ip);+ return false;+}function urlHostIsPrivate(hostname: string): boolean {// Literal IP in the URL — no DNS needed.@@ -43,6 +77,13 @@ function urlHostIsPrivate(hostname: string): boolean {return false;}+function privateBlockReason(host: string): Error {+ return new Error(+ `Blocked: ${host} is a private/internal address (SSRF protection). ` ++ 'Set MERCURY_ALLOW_PRIVATE_FETCH=1 to allow fetching internal hosts.',+ );+}+function lookupHost(hostname: string): Promise<string[]> {return new Promise((resolve) => {lookup(hostname, { all: true }, (err, addresses) => {@@ -55,8 +96,10 @@ function lookupHost(hostname: string): Promise<string[]> {});}-/** Throws with a human-readable reason when the URL must not be fetched. */-export async function assertFetchableTarget(rawUrl: string): Promise<URL> {+type PinnedAddress = { address: string; family: number };+type ResolvedTarget = { url: URL; pinned?: PinnedAddress };++async function resolveAndValidate(rawUrl: string): Promise<ResolvedTarget> {let parsed: URL;try {parsed = new URL(rawUrl);@@ -69,48 +112,86 @@ export async function assertFetchableTarget(rawUrl: string): Promise<URL> {if (urlHostIsPrivate(parsed.hostname)) {throw privateBlockReason(parsed.hostname);}- if (!ALLOW_PRIVATE_FETCH) {- const addresses = await lookupHost(parsed.hostname);- if (addresses.length > 0 && addresses.every((ip) => isPrivateAddress(ip))) {- throw privateBlockReason(parsed.hostname);- }- // Mixed answers with at least one public address are allowed through- // (CDNs occasionally return internal-looking extras).+ if (ALLOW_PRIVATE_FETCH) {+ return { url: parsed };}- return parsed;+ const literalFamily = isIP(parsed.hostname);+ if (literalFamily !== 0) {+ return { url: parsed, pinned: { address: parsed.hostname, family: literalFamily } };+ }+ const addresses = await lookupHost(parsed.hostname);+ if (addresses.length === 0) {+ // Nothing resolved — let the fetch fail on its own rather than guessing.+ return { url: parsed };+ }+ // Fail closed on DNS mixed answers: one non-global record is enough to+ // refuse the target, because we cannot know which record a re-resolving+ // connection would have picked.+ const offending = addresses.find((ip) => isPrivateAddress(ip));+ if (offending) {+ throw privateBlockReason(parsed.hostname);+ }+ const chosen = addresses[0]!;+ return { url: parsed, pinned: { address: chosen, family: isIP(chosen) } };}-function privateBlockReason(host: string): Error {- return new Error(- `Blocked: ${host} is a private/internal address (SSRF protection). ` +- 'Set MERCURY_ALLOW_PRIVATE_FETCH=1 to allow fetching internal hosts.',- );+/** Throws with a human-readable reason when the URL must not be fetched. */+export async function assertFetchableTarget(rawUrl: string): Promise<URL> {+ return (await resolveAndValidate(rawUrl)).url;}-export const MAX_REDIRECTS = 5;+// Pinned lookups for the current in-flight requests, keyed by hostname. The+// guarded agent consults this table so its connection goes to the exact+// address that was validated instead of re-resolving.+const pinnedByHost = new Map<string, PinnedAddress>();++const guardedAgent = new Agent({+ connect: {+ // undici types this hook against its internal LookupFunction; the shape+ // below matches what it invokes at connect time.+ lookup: ((hostname: string, options: { all?: boolean } | undefined, callback: (...args: unknown[]) => void) => {+ const pinned = pinnedByHost.get(hostname);+ if (!pinned) {+ (lookup as unknown as (host: string, opts: unknown, cb: unknown) => void)(hostname, options, callback);+ return;+ }+ if (options?.all) callback(null, [{ address: pinned.address, family: pinned.family }]);+ else callback(null, pinned.address, pinned.family);+ }) as never,+ },+});++type FetchInitWithDispatcher = RequestInit & { dispatcher?: unknown };/** Fetch with SSRF validation on the initial URL AND every redirect hop. */export async function guardedFetch(rawUrl: string, signal: AbortSignal, headers?: Record<string, string>): Promise<Response> {let target = rawUrl;for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {- const validated = await assertFetchableTarget(target);- const resp = await fetch(validated, {- signal,- redirect: 'manual',- headers: headers ?? {- 'User-Agent': 'Mercury-Agent/0.1.0',- 'Accept': 'text/html,application/json,text/plain',- },- });- if (resp.status >= 300 && resp.status < 400) {- const location = resp.headers.get('location');- if (location) {- try { void resp.body?.cancel(); } catch { /* best effort */ }- target = new URL(location, validated).href;- continue;+ const { url, pinned } = await resolveAndValidate(target);+ const host = url.hostname;+ if (pinned) pinnedByHost.set(host, pinned);+ try {+ const init: FetchInitWithDispatcher = {+ signal,+ redirect: 'manual',+ headers: headers ?? DEFAULT_HEADERS,+ dispatcher: guardedAgent,+ };+ const resp = await fetch(url, init);+ if (resp.status >= 300 && resp.status < 400) {+ const location = resp.headers.get('location');+ if (location) {+ try { void resp.body?.cancel(); } catch { /* best effort */ }+ target = new URL(location, url).href;+ continue;+ }+ }+ return resp;+ } finally {+ if (pinned && pinnedByHost.get(host)?.address === pinned.address) {+ pinnedByHost.delete(host);}}- return resp;}throw new Error('Blocked: too many redirects');-}\ No newline at end of file+}