SSRF: Server-Side Request Forgery, Attacks and Defenses

When your own server becomes the weapon

Server-Side Request Forgery (SSRF) is a vulnerability where an attacker tricks *your* server into making an HTTP request *on their behalf*. They cannot reach your internal network, but your server can. So they make your server do the reaching. The request now carries your server's identity, its network position, and crucially in the cloud, its credentials.

SSRF sits at A10 in the OWASP API Security Top 10 and is widely considered one of the most dangerous modern API risks, precisely because the blast radius in cloud environments is enormous. The 2019 Capital One breach, over 100 million customer records, was, at its core, an SSRF that reached an AWS metadata endpoint and walked out with IAM credentials.

The mental model: tricking the mailroom clerk

SSRF is convincing a trusted insider to fetch something for you that you were never allowed to touch yourself.

Picture a corporate mailroom. You, an outsider, are not allowed past the lobby. But the mailroom clerk can walk anywhere in the building. So you hand the clerk a note: "Please go to office 169 and bring me whatever is on the desk." The clerk, trusting the request came through normal channels, fetches the confidential file from a room you could never enter, and hands it to you in the lobby.

The picture: SSRF reaching cloud metadata

Every cloud VM has a magic IP, 169.254.169.254, that only it can reach. Ask that address the right path and it returns the temporary IAM credentials attached to the instance. It is meant for the workload itself. An SSRF lets an outsider borrow that privilege.

1. 1

   Find the sink

   The attacker spots a feature that fetches a URL they control, a link-preview, avatar import, or webhook tester.

2. 2

   Point it inward

   Instead of a normal URL, they submit `http://169.254.169.254/latest/meta-data/iam/security-credentials/`.

3. 3

   Server obeys

   Your app server, sitting on the cloud VM, happily makes that request, it is the only thing that can.

4. 4

   Read the role name

   The metadata API returns the IAM role name attached to the instance.

5. 5

   Grab the keys

   A second fetch to `.../security-credentials/<role>` returns an AccessKeyId, SecretAccessKey, and SessionToken.

6. 6

   Walk out the front door

   Those keys are valid AWS credentials. The attacker now calls S3, RDS, or whatever the role permits, from their own laptop.

Where SSRF hides

SSRF is not one feature, it is a *shape*. Anywhere your server dereferences a value that ultimately came from a user, you have a candidate. The usual suspects:

The vulnerable endpoint

Here is a link-preview endpoint that looks completely reasonable. It is wide open. The user hands us a URL, we fetch it, we return the title. Nothing stops that URL from pointing inward.

import express from "express";

const app = express();

// DO NOT SHIP THIS. Textbook SSRF.
app.get("/preview", async (req, res) => {
  const target = String(req.query.url);

  // We blindly fetch whatever the user gave us.
  const upstream = await fetch(target);
  const body = await upstream.text();

  // ...and echo it straight back (non-blind SSRF).
  res.json({ url: target, body });
});

An attacker calls /preview?url=http://169.254.169.254/latest/meta-data/iam/security-credentials/ and reads your role name out of the JSON. One more request and they have live credentials. The fix is not a single line, SSRF defense is layered.

The hardened endpoint

The non-negotiable rule: allow-list, never deny-list. A deny-list tries to enumerate every bad address and always loses to an encoding you did not think of. An allow-list says "only these hosts, only these schemes" and rejects everything else by default. We also have to defend against DNS rebinding: validating a hostname and *then* fetching it lets an attacker return a safe IP for the validation lookup and a private IP for the real fetch. The defense is resolve-then-validate-then-connect to the resolved IP.

import express from "express";
import dns from "node:dns/promises";
import net from "node:net";
import ipaddr from "ipaddr.js";

const app = express();

// 1. Allow-list of hosts you actually intend to reach.
const ALLOWED_HOSTS = new Set(["images.example.com", "cdn.example.com"]);

// 2. Reject any IP that is private, loopback, or link-local.
function isForbiddenIp(ip: string): boolean {
  const addr = ipaddr.parse(ip);
  const range = addr.range(); // "private" | "loopback" | "linkLocal" | ...
  return [
    "private",
    "loopback",
    "linkLocal",     // 169.254.0.0/16 -> the metadata IP lives here
    "uniqueLocal",
    "unspecified",
    "reserved",
    "carrierGradeNat",
  ].includes(range);
}

app.get("/preview", async (req, res) => {
  const raw = String(req.query.url);

  // 3. Parse and pin the scheme. No file://, gopher://, etc.
  let url: URL;
  try {
    url = new URL(raw);
  } catch {
    return res.status(400).json({ error: "malformed url" });
  }
  if (url.protocol !== "https:") {
    return res.status(400).json({ error: "only https allowed" });
  }

  // 4. Allow-list the host.
  if (!ALLOWED_HOSTS.has(url.hostname)) {
    return res.status(400).json({ error: "host not allowed" });
  }

  // 5. Resolve DNS ourselves, then validate the RESOLVED ip.
  //    This defeats DNS rebinding: we connect to the ip we checked.
  const { address } = await dns.lookup(url.hostname);
  if (isForbiddenIp(address)) {
    return res.status(400).json({ error: "resolves to a private range" });
  }

  // 6. Pin the connection to the validated ip and DISABLE redirects.
  //    A 302 to 169.254.169.254 would otherwise sneak past every check.
  const upstream = await fetch(url.toString(), {
    redirect: "error",
    headers: { host: url.hostname },
    // @ts-expect-error undici dispatcher pins the resolved address
    dispatcher: pinnedDispatcher(address),
  });

  const body = (await upstream.text()).slice(0, 50_000);
  res.json({ url: url.toString(), body });
});

// Pin every socket to the pre-validated ip so the runtime
// cannot re-resolve to a different (private) address.
function pinnedDispatcher(ip: string) {
  const { Agent } = require("undici");
  return new Agent({
    connect: { lookup: (_h: string, _o: unknown, cb: Function) =>
      cb(null, ip, net.isIPv6(ip) ? 6 : 4) },
  });
}

Defend at the network layer too: IMDSv2 and egress

Application code is one layer. The cloud platform gives you two more, and you should use both, because the next SSRF bug you ship will be in a dependency, not your own handler.

# Force IMDSv2 only and cap the hop limit to 1 so containers
# on the host cannot reach the metadata endpoint indirectly.
aws ec2 modify-instance-metadata-options \
  --instance-id i-0abc123 \
  --http-tokens required \
  --http-put-response-hop-limit 1 \
  --http-endpoint enabled

# Belt and braces: block the link-local metadata IP at the host
# firewall for any process that is not the cloud agent.
iptables -A OUTPUT -d 169.254.169.254 -m owner ! --uid-owner 0 -j DROP

Then add an egress firewall: by default, application servers should not be allowed to make arbitrary outbound connections at all. Route outbound traffic through a proxy or NAT that only permits the handful of external endpoints you actually need. If your image-fetcher can only reach cdn.example.com, an SSRF pointed at 169.254.169.254 simply never connects. This is where SSRF defense meets cloud IAM from first principles: least privilege on the network *and* on the role means a stolen credential opens very few doors.

Common mistakes that cost hours

1. Using a regex deny-list. Blocking 169.254.169.254 misses the decimal form 2852039166, the octal form 0250.0376.0251.0376, IPv6-mapped addresses, and [::ffff:169.254.169.254]. Allow-list hosts instead, deny-lists always leak.
2. Validating the hostname, then fetching it. Between your DNS check and the actual request, an attacker-controlled domain can return a private IP (DNS rebinding). Resolve once, validate the IP, and connect to *that* IP.
3. Forgetting redirects. Your allow-listed, public URL returns a 302 to http://169.254.169.254/.... If your client follows redirects, every upstream check is bypassed. Set redirect: "error".
4. Only blocking the metadata IP. SSRF also reaches localhost, your internal admin panel on 10.0.x.x, and 127.0.0.1:6379 Redis. Block all private, loopback, link-local, and unique-local ranges.
5. Trusting the scheme. Without a scheme check, file:///etc/passwd, gopher://, and dict:// open whole new attack classes. Pin to https: only.
6. Relying on app code alone. The next SSRF will be in a transitive dependency you never audited. IMDSv2, egress firewalls, and least-privilege roles are what save you when the code layer fails.

Takeaways

Where to go next

SSRF is one risk in a family of input-trust failures. Build the surrounding muscles next:

• The OWASP API Security Top 10, where SSRF fits among the other API risks you should be hunting.
• Cloud IAM from first principles, least-privilege roles are what cap the damage of a stolen metadata credential.
• Zero-trust networking for beginners, egress control and "never trust the network" are the architectural backstop for SSRF.
• Practice on the networking lab and networking + DNS lab to build intuition for private ranges, link-local addresses, and how DNS resolution really works.