Server-side request forgery

What it is and why it exists

Server-side request forgery (SSRF) is a vulnerability in which a caller influences where a server-side component sends a network request. The dangerous authority comes from the server: its network location, service identity, credentials, and access to destinations that are not exposed to the caller.

The vulnerable feature is often legitimate. Link previews, remote-image imports, webhooks, PDF renderers, feed readers, repository integrations, and URL-based file uploads all need to retrieve or contact something. SSRF appears when the feature accepts more destination authority than its product contract requires.

The input does not have to be a field literally named url. A hostname, webhook target, redirect location, document containing remote resources, or user-controlled part of a proxy route can reach the same request sink. Trace data into HTTP clients, SDK download helpers, headless browsers, image libraries, and document converters.

An ordinary SSRF response may return internal data to the attacker. In blind SSRF, the application hides the response, but timing, error differences, DNS lookups, or state-changing requests can still reveal reachability or cause effects. “We do not return the body” therefore changes the observation channel, not the trust boundary.

The immediate targets include loopback listeners, private networks, link-local services, Unix-host integrations exposed through HTTP gateways, and control planes reachable only from the workload network. In cloud environments, instance metadata is a well-known target because it may expose identity or configuration to the instance.

SSRF is not limited to stealing a response. A request can scan reachable services, invoke an internal state-changing endpoint, spend money through a metered API, download an oversized body, or hold sockets open. The defense must constrain both destination authority and resource consumption.

The safest design question is narrower than “is this URL safe?” Ask which remote service the feature needs, which operation it may perform, and which caller-controlled values belong only in data fields or path segments. That produces a small contract you can enforce and test.

How it works

An SSRF path has three actors: the external caller, a server-side requester, and a destination visible to that requester. The application accidentally transfers part of its outbound authority from policy-controlled code to caller-controlled data.

The parser gives one interpretation of the input. Policy then decides whether the scheme, credentials, hostname, port, and operation are allowed. Handwritten substring checks are not parsers: trusted.example.attacker.test contains a trusted-looking label but is not a subdomain of trusted.example.

Hostname policy and network policy answer different questions. An exact hostname allowlist identifies an approved service name. DNS resolution yields one or more addresses for a particular attempt, and every usable answer must satisfy the address policy.

Address policy normally rejects more than RFC 1918 private IPv4 ranges. It also accounts for loopback, link-local, unspecified, multicast, IPv6 unique-local and link-local space, IPv4-mapped IPv6 forms, and environment-specific control-plane ranges. Maintain this set as policy data rather than scattering regular expressions through handlers.

Validation must govern the connection that actually occurs. If code resolves a host for checking but the HTTP client resolves it again, the two lookups can return different answers. This time-of-check/time-of-use gap enables DNS rebinding and ordinary DNS changes to bypass the decision.

A safe connection layer uses the approved address for the socket while preserving the original hostname for TLS certificate verification, Server Name Indication, and the HTTP authority. That is subtle enough to justify a maintained outbound proxy or a client integration designed for custom lookup and address pinning. Replacing the hostname in an HTTPS URL with an IP is not an equivalent implementation.

Redirects begin a new destination decision. Resolve a relative Location against the current URL, then repeat scheme, host, port, address, credential, and method policy before the next connection. Automatic redirect following skips that control point unless the client exposes a policy hook that performs the full check.

The request itself also carries authority. Strip inbound Authorization, Cookie, proxy, and forwarding headers instead of copying the caller’s header set. Fix or allowlist the method, request headers, and body shape that the integration needs.

The response is untrusted content from an untrusted dependency even when its destination was approved. Enforce connection and overall deadlines, redirect count, byte limit, content type, decompression limit, and concurrency budget. Stream under a byte counter when the body can be large; a Content-Length header alone is not proof of the bytes delivered.

Network controls provide a separate boundary. Egress filtering can force the workload through a controlled proxy or deny routes to internal and metadata networks. It limits damage when application checks are wrong, but it does not define which public services or billable operations the product intended to allow.

Cloud metadata hardening is another layer. For example, requiring AWS IMDSv2 makes metadata access require a session token obtained with a specific request flow. That reduces exposure for some SSRF shapes, but it does not repair arbitrary outbound requests or protect other internal services.

The complete decision sequence is:

1. Replace a caller-supplied URL with a server-side service identifier where the product permits it.
2. Parse once with the same URL semantics used by the request client.
3. Enforce scheme, exact hostname, effective port, credentials, method, headers, and path contract.
4. Resolve the hostname and reject the attempt if any selectable answer violates address policy.
5. Bind an approved answer to the connection while retaining hostname-based TLS verification.
6. Repeat the destination decision after every redirect and stop at a small fixed hop count.
7. Enforce time, byte, decompression, concurrency, and response-type limits.
8. Backstop the code with outbound network policy and narrow workload identity permissions.

Examples

Build a destination from a service contract

The strongest fix removes destination choice from input. This avatar feature owns the scheme and host; the account identifier is encoded as one path segment rather than concatenated into a URL.

The second input remains one encoded segment. It cannot replace the destination authority or turn the rest into a query string. The origin assertion is defense against a later refactor; the primary design property is that callers never provide a hostname.

This pattern also improves authorization and observability. A service identifier can map to an exact method, route template, credential, quota, and response schema. Logs can record the identifier without retaining an attacker-supplied URL containing credentials or sensitive query data.

Classify resolved addresses

When arbitrary public URLs are a real requirement, inspect concrete DNS answers using an IP parser and reviewed network ranges. This small example demonstrates the mechanics with Node’s net.BlockList; production policy must include every special-purpose and environment-specific range relevant to its deployment.

import net from 'node:net';

const denied = new net.BlockList();
for (const [network, prefix] 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], ['240.0.0.0', 4],
]) denied.addSubnet(network, prefix, 'ipv4');

denied.addAddress('::', 'ipv6');
denied.addAddress('::1', 'ipv6');
for (const [network, prefix] of [
  ['fc00::', 7], ['fe80::', 10], ['ff00::', 8],
]) denied.addSubnet(network, prefix, 'ipv6');

function decision(address) {
  const version = net.isIP(address);
  if (version === 0) return 'invalid';
  if (address.toLowerCase().startsWith('::ffff:')) return 'blocked';
  const family = version === 4 ? 'ipv4' : 'ipv6';
  return denied.check(address, family) ? 'blocked' : 'allowed';
}

for (const address of [
  '93.184.216.34', '127.0.0.1', '169.254.169.254',
  '::1', '::ffff:127.0.0.1', 'not-an-address',
]) console.log(`${address}: ${decision(address)}`);

93.184.216.34: allowed
127.0.0.1: blocked
169.254.169.254: blocked
::1: blocked
::ffff:127.0.0.1: blocked
not-an-address: invalid

Reject invalid text and any prohibited answer; do not silently keep only an allowed address from a mixed DNS response. The request layer must then connect to an address that passed this decision rather than resolving the hostname again.

The listed prefixes teach the shape of the policy, not a complete Internet routing registry. Generate or centrally maintain the production set from authoritative registries, add deployment-specific service and control-plane networks, and cover IPv4 and IPv6 in tests.

Revalidate every redirect

This example uses a fake resolver and transport so it runs without network access. It abbreviates the address-range policy shown above and focuses on the control flow: inspection happens before the initial request and again before a redirected request.

import net from 'node:net';
const allowedHosts = new Set(['start.example', 'cdn.example']);
const dnsAnswers = new Map([
  ['start.example', ['203.0.113.10']],
  ['cdn.example', ['203.0.113.20']],
]);
const responses = new Map([
  ['https://start.example/photo', { status: 302, location: 'https://cdn.example/p.jpg' }],
  ['https://cdn.example/p.jpg', { status: 200, body: 'image/jpeg' }],
  ['https://start.example/admin', { status: 302, location: 'http://127.0.0.1/admin' }],
]);
function inspect(target) {
  if (target.protocol !== 'https:' || !allowedHosts.has(target.hostname)) {
    throw new Error(`destination rejected: ${target.href}`);
  }
  const addresses = dnsAnswers.get(target.hostname) ?? [];
  if (addresses.length === 0 || addresses.some((ip) => net.isIP(ip) === 0)) {
    throw new Error(`DNS answer rejected: ${target.hostname}`);
  }
}
function fetchMock(target) {
  const response = responses.get(target.href);
  if (!response) throw new Error(`no response: ${target.href}`);
  return response;
}
function fetchWithPolicy(start, maxRedirects = 2) {
  let target = new URL(start);
  for (let hop = 0; hop <= maxRedirects; hop += 1) {
    inspect(target);
    const response = fetchMock(target);
    if (response.status < 300 || response.status >= 400) return response.body;
    if (hop === maxRedirects) throw new Error('redirect limit exceeded');
    target = new URL(response.location, target);
  }
}
for (const path of ['photo', 'admin']) {
  try { console.log(`${path}: ${fetchWithPolicy(`https://start.example/${path}`)}`); }
  catch (error) { console.log(`${path}: ${error.message}`); }
}

photo: image/jpeg
admin: destination rejected: http://127.0.0.1/admin

The first chain moves between two approved HTTPS hosts. The second begins at an approved host but is stopped before the redirected connection. In real code, inspect must also apply the complete address policy and pass its chosen address into the connection layer.

Relative redirects need the same treatment. new URL(location, current) makes the resolution rule explicit, after which the resulting URL receives an independent policy decision. Do not compare the raw Location string with prefixes.

Bound the response while streaming

An approved destination can still exhaust resources. This reader accepts one exact media type and cancels as soon as the observed bytes cross its limit, rather than buffering first and checking afterward.

function mockResponse(parts) {
  const encoder = new TextEncoder();
  const body = new ReadableStream({
    start(controller) {
      for (const part of parts) controller.enqueue(encoder.encode(part));
      controller.close();
    },
  });
  return new Response(body, {
    headers: { 'content-type': 'application/json' },
  });
}

async function readBounded(response, maxBytes) {
  if (response.headers.get('content-type') !== 'application/json') {
    throw new Error('content type rejected');
  }
  const reader = response.body.getReader();
  const chunks = [];
  let total = 0;
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    total += value.byteLength;
    if (total > maxBytes) {
      await reader.cancel();
      throw new Error(`body exceeds ${maxBytes} bytes`);
    }
    chunks.push(Buffer.from(value));
  }
  return Buffer.concat(chunks).toString('utf8');
}

for (const parts of [['{"ok":', 'true}'], ['{"data":"', '0123456789', '"}']]) {
  try { console.log(await readBounded(mockResponse(parts), 12)); }
  catch (error) { console.log(error.message); }
}

{"ok":true}
body exceeds 12 bytes

Production code also needs a total deadline, an idle-read deadline, decompression accounting, and a concurrency budget. Apply the byte limit to the representation whose cost matters; a small compressed transfer can expand into a much larger decoded body.

Pitfalls

Further reading

• OWASP Server-Side Request Forgery Prevention Cheat Sheet
• RFC 6890: Special-Purpose IP Address Registries
• Node.js v24 net.BlockList
• AWS EC2 instance metadata options