SSRF Explained: Server-Side Request Forgery
On this page
What is SSRF? Your server as the attacker's proxy
Features that fetch URLs on a user's behalf are common: link previews, "import image from URL", webhook targets, PDF generators. If the server fetches whatever URL it's given, the attacker can point it at places only the server can reach:
// VULNERABLE: fetches anything
app.post('/preview', async (req, res) => {
const response = await fetch(req.body.url);
res.send(await response.text());
});
// url = "http://169.254.169.254/latest/meta-data/iam/security-credentials/"169.254.169.254 is the cloud instance metadata service. On a cloud server it can return temporary credentials for the server's IAM role, and the preview feature hands them to the attacker. The 2019 Capital One breach, which exposed over 100 million customers' records, used SSRF against this service. Other targets: localhost admin panels, internal APIs, databases and Redis without authentication.
Building an SSRF URL guard in Node
Allow only HTTPS on the standard port, resolve the hostname, and reject internal addresses:
import dns from 'node:dns/promises';
import net from 'node:net';
const blocked = new net.BlockList();
for (const [range, bits] 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.168.0.0', 16], ['224.0.0.0', 4]])
blocked.addSubnet(range, bits, 'ipv4');
for (const [range, bits] of [['::', 128], ['::1', 128], ['fc00::', 7], ['fe80::', 10]])
blocked.addSubnet(range, bits, 'ipv6');
// IPv4-mapped IPv6 (::ffff:127.0.0.1) is checked against the IPv4 rules automatically
async function checkUrl(raw) {
let url;
try { url = new URL(raw); } catch { return 'rejected: not a URL'; }
if (url.protocol !== 'https:') return `rejected: scheme ${url.protocol}`;
if (url.port && url.port !== '443') return `rejected: port ${url.port}`;
const host = url.hostname.replace(/^\[|\]$/g, ''); // [::1] -> ::1
const addrs = await dns.lookup(host, { all: true }).catch(() => []);
if (!addrs.length) return 'rejected: does not resolve';
for (const { address, family } of addrs)
if (blocked.check(address, family === 6 ? 'ipv6' : 'ipv4')) return `rejected: ${host} -> ${address} is internal`;
return `allowed: ${host} -> ${addrs.map(a => a.address).join(', ')}`;
}Tested against tricky inputs:
https://example.com/logo.png allowed: example.com -> 2606:4700:10::ac42:93f3, ..., 104.20.23.154
http://169.254.169.254/latest/meta-data/ rejected: scheme http:
https://169.254.169.254/latest/meta-data/ rejected: 169.254.169.254 -> 169.254.169.254 is internal
https://localhost/admin rejected: localhost -> ::1 is internal
https://127.1/ rejected: 127.0.0.1 -> 127.0.0.1 is internal
https://[::ffff:127.0.0.1]/ rejected: ::ffff:7f00:1 -> ::ffff:7f00:1 is internal
https://0x7f000001/ rejected: 127.0.0.1 -> 127.0.0.1 is internal
file:///etc/passwd rejected: scheme file:
https://example.com:6379/ rejected: port 6379127.1 and 0x7f000001 are both 127.0.0.1 in disguise; new URL normalizes them, and checking the resolved address catches the rest.
Two SSRF filter bugs found while testing
The first version of this guard was wrong in two ways, and both are easy mistakes:
- It also blocked the IPv4-mapped range
::ffff:0:0/96. Node'sBlockListmaps IPv4 addresses into that range internally, so the rule matched every IPv4 address, andexample.comwas "internal". Mapped addresses are already checked against the IPv4 rules. - It passed
[::ffff:127.0.0.1]to DNS with brackets, which failed to resolve. It was rejected for the wrong reason, which hid the gap.
Test SSRF filters with real lists of bypass payloads, not just one example.
SSRF defense in depth: DNS rebinding, egress and IMDSv2
A pre-check has a gap: DNS can return a public address when you check and an internal one when you fetch (DNS rebinding). Complete the defense:
- Connect to the address you validated: pin it with a custom lookup or agent, and don't follow redirects without re-checking each hop.
- Network egress controls: run fetchers in a subnet that can't reach internal services or the metadata endpoint.
- IMDSv2 on AWS (a session token is required, which simple SSRF can't obtain) and equivalent protections elsewhere.
- Allow-lists of domains when you know which ones are legitimate.
- Don't return raw responses to the user when you only need, say, a title and an image.
Check yourself
On AWS, GCP and Azure, 169.254.169.254 can return temporary credentials for the server's role. An SSRF that reaches it gives the attacker cloud API access with the server's permissions. IMDSv2 and similar protections block simple SSRF from reading it.
Hostnames, decimal and hex forms, and IPv6 mappings can all point to internal addresses; only the resolved address shows where the request will go.
A domain resolves to a safe address during validation and to an internal one when the server connects, bypassing a check-then-fetch guard.
A URL that passes your check, pointing to an attacker's public server, can respond with a redirect to an internal address like the metadata service. If the HTTP client follows redirects, the check is bypassed, so disable redirects or validate every hop.
Egress filtering: the server can only connect to an allow-list of external destinations, often through a proxy, and internal ranges and metadata addresses are blocked at the network level. Even a bypassed application check then reaches nothing sensitive.