Outbound Request Safety and SSRF

When Your API Makes the Request

Most API security is about requests coming in. Server-side request forgery (SSRF) is about the requests your API sends out on a caller’s behalf. Any feature that takes a URL from a user and fetches it gives that user a client running inside your network, with your network position, your firewall exemptions and your cloud credentials within reach.

The classic target is the cloud instance metadata service at 169.254.169.254, which on most clouds hands out the machine’s own credentials to anything that can reach it. The OWASP API Security Top 10 (2023) lists this as API7:2023 Server Side Request Forgery, and its second example scenario is precisely a webhook test feature that fetched an attacker’s metadata URL and returned the credentials in the response.

A URL check at input time is not enough on its own, because the hostname that resolves to a public address when you validate it can resolve to a private one when you connect. The defenses below are layered for that reason: each one closes a gap the others leave.

1. Know Where You Fetch URLs

SSRF surfaces are easy to miss because they rarely look like “fetch a URL” in the product spec.

Inventory these, then route every one of them through a single outbound client that applies the rules below. Five features each doing their own validation is five chances to get it slightly wrong.

2. Allowlist Scheme and Port

Accept https and nothing else. Every other scheme your HTTP library happens to support (file:, gopher:, ftp:, dict:) is attack surface with no product use. Allowing plain http also lets an attacker reach internal services that never bothered with TLS, so require https for webhooks and imports alike; customers who need plain HTTP are rarely the ones you want to make an exception for.

Restrict ports to 443, or to a short published list. An attacker who can choose the port can probe internal services by response timing even when the response body is never returned, which is OWASP’s first API7 scenario.

Parse URLs with one well-maintained, standards-conforming parser, and make the decision on the parsed result, not on the raw string. Parsers disagree on edge cases such as userinfo (https://trusted.example@evil.example/), backslashes and numeric hosts, and an attack that exploits a disagreement needs your validator and your HTTP client to use different parsers. Reject URLs containing userinfo outright; RFC 9110 already forbids senders from generating it in http and https URIs.

3. Block Non-Public Address Ranges

The destination must be a publicly routable address. The authoritative lists are the IANA IPv4 and IPv6 Special-Purpose Address Registries, which mark each block as globally reachable or not. Block every block marked not globally reachable. The ones that matter most:

Three traps:

• Check the address, not the string. 2130706433, 0x7f.1 and 017700000001 are all ways of writing 127.0.0.1 that URL parsers accept. Resolve to a binary address first, then compare it against CIDR ranges.
• Unwrap embedded IPv4. IPv4-mapped addresses and NAT64 prefixes such as 64:ff9b::/96 carry an IPv4 address inside an IPv6 one. Extract it and check it against the IPv4 rules too.
• Do not hand-maintain the list from memory. Use a library that tracks the IANA registries, and re-check when the registries change; the IPv6 registry gained new non-reachable blocks in recent years.

Blocking ranges is necessary and not sufficient. Your own infrastructure may have internal services on public addresses, and none of this stops the rebinding attack in the next section.

4. Resolve Once, Then Connect to That Address

The naive implementation resolves the hostname, checks the address, then hands the URL to an HTTP client, which resolves it again. Between the two lookups, an attacker who controls the domain’s DNS can change the answer: a public address with a short TTL for the check, 169.254.169.254 for the connection. This is DNS rebinding, and it defeats every validator that checks a hostname rather than the socket.

The defense is to make the check and the connection use the same resolution:

addresses = resolve(host)                  # all A and AAAA records
if any address is not globally reachable:  # reject if ANY fails, not just the first
    reject
connect to addresses[0] directly
    send Host / SNI = original hostname     # so TLS and virtual hosting still work
    verify certificate against original hostname

Most HTTP clients let you supply a custom resolver or a dial hook that receives the resolved address before the socket opens; do the check there, at connect time, on the actual address being dialed. That also covers connection pools and retries, which may resolve again behind your back.

Validate at subscription time as well, so customers get an immediate error for an obviously bad URL. But treat that as a usability check. The security check is the one at connect time, on every delivery, because DNS answers change.

5. Re-Validate Every Redirect

An HTTP client that follows redirects automatically will happily follow 302 Found with Location: http://169.254.169.254/latest/meta-data/ from a perfectly public server. OWASP’s API7 guidance is to disable redirects.

• For webhooks, do not follow redirects at all. Treat a 3xx as a delivery failure, as the webhooks guide already recommends. The customer can update their endpoint.
• For fetches where redirects are legitimate (image imports, link previews), follow them manually: take the Location, run it through the full scheme, port and address checks again, cap the number of hops at a small number, and refuse a redirect from https to anything else.

6. Bound Time and Size

A user-supplied URL can point at a server that never finishes responding, or that streams forever. Without bounds, each fetch ties up a worker, and a handful of them is a denial of service against your delivery pipeline.

Pick numbers that fit the feature and publish the ones customers can hit, such as the webhook timeout.

7. Isolate the Fetcher

Application-level checks fail eventually: a new feature bypasses the shared client, a library upgrade changes parsing, a redirect path gets missed. Put a network boundary behind them so that a bypass reaches nothing valuable.

• Use an egress proxy. Route all user-directed outbound traffic through a forward proxy that performs the address checks itself and is the only path to the internet for that workload. Stripe’s open-source Smokescreen is one example: an HTTP CONNECT proxy that resolves each destination and refuses internal addresses by default.
• Run fetchers on a separate network segment with no route to internal services, databases or the metadata endpoint. The fetcher only needs the internet; give it only the internet.
• Harden the metadata service. On AWS, require IMDSv2, which only issues credentials in response to a session token obtained by a PUT request, and keep the response hop limit at 1 where your containers allow it. Azure’s metadata service requires a Metadata: true header and rejects requests carrying X-Forwarded-For; Google Cloud’s requires Metadata-Flavor: Google. These help against the simplest SSRF, where the attacker controls only the URL, but treat them as defense in depth, not as a reason to skip the address checks.
• Give the fetching workload minimal credentials, so that if metadata is reached, what it yields is worth little.

8. Do Not Echo the Response

The worst SSRF outcomes come from features that return what they fetched. A webhook “test” button that shows the receiver’s response body, or an import that reports the remote server’s error page verbatim, turns a blind SSRF into one that reads internal data.

Return the status code, the timing and a classified error (“connection refused”, “TLS handshake failed”, “timed out”, “destination not allowed”), and nothing from the response body. Make the “destination not allowed” error generic: telling the caller which rule matched helps them map your network. See webhook delivery history for what to record about each attempt, and API security for where SSRF sits among the other OWASP risks.