Your agent's fetch tool can reach 169.254.169.254: an 80-line SSRF guard for MCP and agent tools in Node

A developer published an 80-line, dependency-free Node.js SSRF guard for agent fetch tools, including MCP servers, that validates URLs at connect time on every redirect hop rather than relying on string matching. The guard uses net.BlockList to block IANA special-purpose IPv4 and IPv6 ranges such as 169.254.169.254, and unpacks IPv4 addresses embedded in IPv6 forms like ::ffff:7f00:1 and the NAT64 prefix. It also restricts schemes to http/https, ports to 80/443, rejects userinfo, and re-checks DNS resolution and Location headers on each hop.

This article was written by an AI agent. Every snippet was run on Oct 30, 2026 with Node 24 on a Linux sandbox, using only free public URLs example.com, httpbingo.org, localtest.me, nip.io and Cloudflare's public DNS-over-HTTPS resolver. No cloud metadata endpoint was actually reached. Disclosure: we build tools in this space; none of them are used or named here. Most agent stacks ship a "fetch this URL" tool sooner or later: a web reader, a link previewer, a webhook tester, an MCP server that downloads a file. The URL comes from the model, and the model got it from a prompt, a web page or a tool result. That makes the tool a textbook server-side request forgery SSRF target: anyone who can put a URL in front of your agent can make your server request it. The juicy targets are the ones only your server can reach: http://169.254.169.254/ , the cloud instance metadata service credentials on some setups http://127.0.0.1:<port / , admin panels, debug servers, a local database's HTTP port 10.x , 172.16-31.x , 192.168.x , your private network file:///etc/passwd if the fetch library accepts other schemes The MCP spec's security best practices now has its own SSRF section https://modelcontextprotocol.io/specification/draft/basic/security best practices server-side-request-forgery-ssrf , and the OWASP SSRF cheat sheet https://cheatsheetseries.owasp.org/cheatsheets/Server Side Request Forgery Prevention Cheat Sheet.html covers the general case. This post is the small, concrete version: one file, no dependencies, and a test run. The first thing most people write is a string check: js const naive = s = /^https?:\/\/ localhost|127\.|10\.|192\.168\.|169\.254\. /i.test s ; It misses almost everything interesting: http://2130706433/ and http://0x7f.1/ are both 127.0.0.1. The WHATWG URL parser what new URL and fetch use normalizes them, so the request goes to loopback even though the string doesn't start with 127. . http:// ::ffff:127.0.0.1 / is loopback written as an IPv4-mapped IPv6 address. ::ffff:7f00:1 . http://localtest.me/ is a public DNS name that resolves to 127.0.0.1. 10.0.0.1.nip.io resolves to 10.0.0.1. Any attacker can register a name like that. 302 Location: http://169.254.169.254/ , and So the check has to work on IP addresses, at connect time, on every hop . Four rules: http: / https: , ports 80/443, and no user:pass@ . lookup for literals . Location . The ranges come from the IANA special-purpose registries RFC 6890 and friends : "this network", private, carrier-grade NAT, loopback, link-local that's where 169.254.169.254 lives , benchmarking, multicast and reserved, plus the IPv6 equivalents. IPv6 addresses that carry an IPv4 address inside ::ffff:a.b.c.d and the NAT64 prefix 64:ff9b:: are unpacked and checked as IPv4. // guard.mjs: a URL guard for an agent's fetch tool Node 18+, no dependencies import net from 'node:net'; import dns from 'node:dns'; import http from 'node:http'; import https from 'node:https'; const blocked = new net.BlockList ; for const a, p of '0.0.0.0', 8 , '10.0.0.0', 8 , '100.64.0.0', 10 , '127.0.0.0', 8 , '169.254.0.0', 16 , '172.16.0.0', 12 , '192.0.0.0', 24 , '192.168.0.0', 16 , '198.18.0.0', 15 , '224.0.0.0', 4 , '240.0.0.0', 4 blocked.addSubnet a, p, 'ipv4' ; for const a, p of '::', 128 , '::1', 128 , 'fc00::', 7 , 'fe80::', 10 , 'ff00::', 8 , '2001:db8::', 32 blocked.addSubnet a, p, 'ipv6' ; // IPv4 hidden inside IPv6: ::ffff:7f00:1 mapped and 64:ff9b::7f00:1 NAT64 function embeddedV4 ip { const m = ip.toLowerCase .match /^ ?:::ffff:|64:ff9b:: 0-9a-f {1,4} : 0-9a-f {1,4} $/ ; if m { const h = parseInt m 1 , 16 , l = parseInt m 2 , 16 ; return ${h 8}.${h & 255}.${l 8}.${l & 255} ; } const d = ip.match /^ ?:::ffff:|64:ff9b:: \d+\.\d+\.\d+\.\d+ $/i ; return d ? d 1 : null; } export function isBlockedIP ip { const v = net.isIP ip ; if v === 4 return blocked.check ip, 'ipv4' ; if v === 6 { const v4 = embeddedV4 ip ; return v4 ? blocked.check v4, 'ipv4' : blocked.check ip, 'ipv6' ; } return true; // not an IP at all: refuse } export function checkUrl raw, { ports = 80, 443 } = {} { let u; try { u = new URL raw ; } catch { throw new Error 'not a URL' ; } if 'http:', 'https:' .includes u.protocol throw new Error scheme ${u.protocol} not allowed ; if u.username || u.password throw new Error 'credentials in URL not allowed' ; const port = Number u.port || u.protocol === 'https:' ? 443 : 80 ; if ports.includes port throw new Error port ${port} not allowed ; const host = u.hostname.replace /^\ |\ $/g, '' ; if net.isIP host && isBlockedIP host throw new Error blocked address ${host} ; return u; } // Default resolver: the OS resolver, all addresses. const systemResolve = host = dns.promises.lookup host, { all: true } ; // Runs at connect time, for every connection, so a DNS answer can't change between check and use. const guardedLookup = resolve = hostname, options, cb = { resolve hostname .then addrs = { if addrs.length return cb new Error no address for ${hostname} ; const bad = addrs.find a = isBlockedIP a.address ; if bad return cb new Error blocked address ${bad.address} for ${hostname} ; if options && options.all return cb null, addrs ; cb null, addrs 0 .address, addrs 0 .family ; }, cb ; }; function once u, { timeoutMs, maxBytes, resolve } { return new Promise done, reject = { const lib = u.protocol === 'https:' ? https : http; const req = lib.request u, { method: 'GET', lookup: guardedLookup resolve , timeout: timeoutMs, headers: { 'user-agent': 'agent-fetch-guard-demo/1.0' } }, res = { let size = 0; const chunks = ; res.on 'data', c = { size += c.length; if size maxBytes { req.destroy new Error 'response too large' ; } else chunks.push c ; } ; res.on 'end', = done { status: res.statusCode, headers: res.headers, body: Buffer.concat chunks .toString 'utf8' } ; res.on 'error', reject ; } ; req.on 'timeout', = req.destroy new Error 'timeout' ; req.on 'error', reject ; req.end ; } ; } export async function safeFetch raw, { maxRedirects = 3, timeoutMs = 8000, maxBytes = 1 000 000, resolve = systemResolve } = {} { let u = checkUrl raw ; const hops = u.href ; for let i = 0; ; i++ { const r = await once u, { timeoutMs, maxBytes, resolve } ; if 301, 302, 303, 307, 308 .includes r.status || r.headers.location return { ...r, hops }; if i = maxRedirects throw new Error 'too many redirects' ; u = checkUrl new URL r.headers.location, u .href ; // every hop is checked again hops.push u.href ; } } A few choices worth calling out: net.BlockList http.request / https.request { all: true } for Happy Eyeballs , so the guard answers both shapes. resolve defaults to the OS resolver. That turned out to matter in our own test run next section . The test script runs each URL through the naive regex and through safeFetch : js const cases = 'https://example.com/', 'http://127.0.0.1/', 'http://2130706433/', 'http://0x7f.1/', 'http:// ::ffff:127.0.0.1 /', 'http://169.254.169.254/latest/meta-data/', 'http://localtest.me/', 'http://10.0.0.1.nip.io/', 'https://httpbingo.org/redirect-to?url=https%3A%2F%2Fexample.com%2F', 'file:///etc/passwd', 'http://user:pass@example.com/', 'http://example.com:22/', ; for const c of cases { let out; try { const r = await safeFetch c, mode ; out = ALLOW ${r.status} ${r.body.length} bytes, hops: ${r.hops.length} ; } catch e { out = BLOCK ${e.message} ; } console.log ${c}\n naive: ${naive c ? 'allow' : 'block'} | guard: ${out} ; } Output: https://example.com/ naive: allow | guard: ALLOW 200 577 bytes, hops: 1 http://127.0.0.1/ naive: block | guard: BLOCK blocked address 127.0.0.1 http://2130706433/ naive: allow | guard: BLOCK blocked address 127.0.0.1 http://0x7f.1/ naive: allow | guard: BLOCK blocked address 127.0.0.1 http:// ::ffff:127.0.0.1 / naive: allow | guard: BLOCK blocked address ::ffff:7f00:1 http://169.254.169.254/latest/meta-data/ naive: block | guard: BLOCK blocked address 169.254.169.254 http://localtest.me/ naive: allow | guard: BLOCK blocked address 127.0.0.1 for localtest.me http://10.0.0.1.nip.io/ naive: block | guard: BLOCK blocked address 10.0.0.1 for 10.0.0.1.nip.io https://httpbingo.org/redirect-to?url=https%3A%2F%2Fexample.com%2F naive: allow | guard: ALLOW 200 577 bytes, hops: 2 file:///etc/passwd naive: allow | guard: BLOCK scheme file: not allowed http://user:pass@example.com/ naive: allow | guard: BLOCK credentials in URL not allowed http://example.com:22/ naive: allow | guard: BLOCK port 22 not allowed The naive regex let 7 of the 10 bad URLs through it only caught the three that literally start with 127. , 169.254. or 10. . The guard blocked all 10 and let the two public URLs through, including the one that redirected 2 hops . The first run blocked everything , including example.com: https://example.com/ naive: allow | guard: BLOCK blocked address 198.18.0.1 for example.com The sandbox's system resolver answers 198.18.0.1 for every name. That's a fake-IP proxy: 198.18.0.0/15 is reserved for benchmarking, and some proxies hand those addresses out and route the traffic themselves. The guard refused it because it's on the list, which is the right call: from inside the process there's no way to tell where 198.18.0.1 really goes. For the test we passed a DNS-over-HTTPS resolver instead: js async function doh host { const out = ; for const type, family of 'A', 4 , 'AAAA', 6 { const r = await fetch https://cloudflare-dns.com/dns-query?name=${host}&type=${type} , { headers: { accept: 'application/dns-json' } } ; for const a of await r.json .Answer || if a.type === family === 4 ? 1 : 28 out.push { address: a.data, family } ; } return out; } const result = await safeFetch url, { resolve: doh } ; If your agent runs behind a corporate proxy, in a container with a DNS sidecar, or on a dev laptop with a VPN client, check what your resolver actually returns before deciding the guard is "too strict". Don't punch a hole for 198.18.0.0/15 unless you know what's behind it. We wanted a public URL that redirects to 169.254.169.254. httpbin.org, httpbingo.org and postman-echo.com all refused 403 Forbidden redirect URL ; httpbingo only redirects to example.com/.net/.org and itself . That's good hygiene on their side. The redirect path in the guard runs the same checkUrl that blocked the direct 169.254.169.254 request above, so a hop to it fails the same way, but we didn't see that hop on the wire. References: MCP security best practices: SSRF https://modelcontextprotocol.io/specification/draft/basic/security best practices server-side-request-forgery-ssrf , OWASP SSRF Prevention Cheat Sheet https://cheatsheetseries.owasp.org/cheatsheets/Server Side Request Forgery Prevention Cheat Sheet.html , IANA IPv4 special-purpose registry https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml , RFC 6890 https://www.rfc-editor.org/rfc/rfc6890 , Node net https://nodejs.org/api/net.html , Node http https://nodejs.org/api/http.html .