Skip to content

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.json
index 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.json
index 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.ts
index 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.ts
index 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
+}