SSRF and Cloud Metadata — Block Server-Side Forgery

Your app has a harmless feature: paste a URL, get a link preview. Or import a file from a URL. Or receive webhooks from a partner. Behind each of these sits server-side code that fetches an arbitrary address — and if any part of that address comes from user input, you've built an SSRF hole: Server-Side Request Forgery.

SSRF lets an outsider aim your server's network access at targets they choose. Scan internal ports. Hit admin panels that listen only on localhost. And in the cloud, query the instance metadata service — a special internal address that happily describes your infrastructure and, worst of all, dispenses temporary credentials for the instance's IAM role. A single crafted URL can escalate from 'fetch my avatar' to 'keys to the kingdom'.

What makes SSRF stubborn is that every fix teams try first is bypassable. Block the metadata IP and attackers use DNS rebinding, decimal IP encoding, or redirects to reach it anyway. Check the URL string but not the resolved address and redirects walk right past. This guide covers the entry points, the metadata service mechanics, and the layered defense — allowlists, egress controls, IMDSv2 — that actually holds when any single layer fails.

How a URL Field Becomes a Server-Side Request

SSRF starts with a feature that seems user-friendly: paste a link, get a preview card. Import your avatar from a URL instead of uploading. Register a webhook and we'll call you back. Each of these hands part of an outbound request to the user — the host, the path, sometimes headers — and the server executes it with the server's network position. Your backend can reach the internal admin panel on localhost:8080, the database on its private IP, and the metadata service. The attacker can't reach those directly, so they borrow your server's legs.

The entry points cluster in a few shapes. Fetchers (previews, imports, converters) take full URLs. Webhook registrations store a callback the server will later call, sometimes with secrets attached. Document pipelines (PDF renderers, SVG processors, XML parsers) resolve embedded external references during conversion — a file upload becomes a request engine. And open redirectors elsewhere in your app become accomplices, laundering attacker destinations through your own domain.

Map these features before you harden them. For each one, answer: which URL parts does the user control, does the fetcher follow redirects, and is DNS re-resolved at fetch time? The snippet below is the hardened fetch helper every one of these features should share — allowlisted hosts, DNS resolved and checked, private ranges rejected, redirects off. One choke point beats ten ad-hoc validators.

import ipaddress
import socket
from urllib.parse import urlparse

ALLOWED_HOSTS = {"avatars.example-cdn.com", "partner.example.org"}
BLOCKED_NETS = [ipaddress.ip_network(c) for c in
                ("10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16",
                 "169.254.0.0/16", "127.0.0.0/8", "::1/128", "fe80::/10")]

def _ip_blocked(ip: str) -> bool:
    addr = ipaddress.ip_address(ip)
    return any(addr in net for net in BLOCKED_NETS)

def safe_fetch(url: str, timeout: int = 5) -> bytes:
    host = urlparse(url).hostname or ""
    if host not in ALLOWED_HOSTS:  # allowlist first, no regexes
        raise ValueError(f"Host not allowlisted: {host}")
    for _, _, _, _, sockaddr in socket.getaddrinfo(host, 443):
        if _ip_blocked(sockaddr[0]):  # re-check AFTER resolution
            raise ValueError(f"Resolved to blocked range: {sockaddr[0]}")
    return http_get(url, timeout=timeout, allow_redirects=False)

The Cloud Metadata Address and Why Attackers Love It

Every major cloud runs an instance metadata service at the link-local address 169.254.169.254 — reachable only from inside the instance, serving data about the machine itself. That data includes instance identity, network config, user-data scripts (which sometimes embed secrets), and IAM role credentials. The credentials are the prize: temporary, auto-rotating, and usable from anywhere on the internet until they expire. Read them once through SSRF and you wear the instance's permissions like a costume.

The shape is identical on every platform: query a well-known URL, get JSON back, extract the temporary credentials. Attackers automate the walk — role name first, credentials second — in seconds. From there the blast radius equals the role's permissions: storage buckets, queues, other instances, sometimes the whole account. The mining-fleet incident earlier is the standard monetization; data theft is the quieter one.

This is why metadata access deserves its own defensive layer regardless of application fixes. Application code changes weekly; the metadata service is forever. Enforce the hardened metadata version, restrict which network tiers can reach the address at all, and keep instance roles minimal so that even a successful read yields little. The fetcher fix stops the knock; the metadata hardening decides what's behind the door.

# Verify IMDSv2 enforcement: v1-style bare GETs must fail, token GETs work
# (non-sensitive path used; proves the PUT handshake is required)
if curl -s --max-time 3 http://169.254.169.254/latest/meta-data/ami-id; then
  echo 'WARN: metadata answers bare GETs — IMDSv1 still allowed'
else
  echo 'OK: bare GET refused'
fi
TOKEN=$(curl -s -X PUT http://169.254.169.254/latest/api/token \
  -H 'X-aws-ec2-metadata-token-ttl-seconds: 60' --max-time 3)
curl -s --max-time 3 -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/ami-id && echo ' <- token path works'

Allowlists and Egress Controls That Actually Hold

Denylists fail against SSRF because attacker input has infinite spellings: decimal IPs (2130706433 for localhost), octal variants, DNS rebinding that resolves safe-then-evil, and redirect chains that start trusted and end anywhere. Every denylist is a bet you've enumerated all evil; allowlists flip the bet to enumerating the small set of legitimate destinations, which for most features is a handful of hosts.

Build the allowlist at the right layer. In code, check the parsed hostname against an explicit set — never a regex on the raw string — then resolve DNS yourself and reject private, loopback, link-local, and metadata ranges on every resolved address. Handle redirects by re-running the full check on each hop or by refusing to follow them; most preview and import features work fine fetching only the first response. Set aggressive timeouts so attackers can't use your fetcher for slow port scans.

Then assume the code check has a bug and add network controls that don't depend on it. Egress proxy rules that permit only approved external hosts, security groups that deny the metadata address from application subnets, and DNS filtering that sinkholes metadata-looking queries all keep working when the parser slips. The YAML below shows the Kubernetes-flavored version: a NetworkPolicy that confines the app tier's egress so even a compromised pod can't wander the network freely.

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: app-tier-egress
  namespace: production
spec:
  podSelector:
    matchLabels:
      tier: app
  policyTypes: [Egress]
  egress:
    - to:
        - namespaceSelector: {}  # cluster DNS only
      ports:
        - port: 53
          protocol: UDP
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except: [169.254.169.254/32]  # never metadata
      ports:
        - port: 443
          protocol: TCP

IMDSv2 and Hop Limits as Defense in Depth

IMDSv2 (Instance Metadata Service version 2) fixes the protocol mismatch that made SSRF so rewarding: v1 answers plain GETs, which is all SSRF can easily produce, while v2 demands a PUT to mint a session token before any data is served. URL fetchers, XML resolvers, and PDF renderers issue GETs — they can't complete the PUT handshake, so the metadata stays silent even when the request reaches it. Enforcing v2-only (HttpTokens=required) converts most SSRF from credential theft back into mere reconnaissance.

The hop limit (HttpPutResponseHopLimit) handles the container wrinkle. Responses from the metadata service carry a TTL that decrements per network hop; containers add hops between the pod and the host network, so defaults were historically raised to 2 for container hosts — which also lets SSRF payloads running in containers reach the service. Setting the limit to 1 on hosts that don't need container metadata access closes that path; where containers legitimately need it, prefer distinct task roles (like ECS task roles) over instance roles so stolen credentials carry less power.

Roll this out as infrastructure, not advice: set the requirement in launch templates and organization policies so new instances inherit it, then audit existing fleets region by region. The commands below show the verification habit — check what's actually enforced, don't trust the ticket that said it was done. Pair the rollout with a smoke test of every agent (monitoring, config management) that reads metadata legitimately, since v2-only breaks clients too old to send the PUT.

# Audit IMDS enforcement across a region (run per region)
aws ec2 describe-instances \
  --query 'Reservations[].Instances[].[InstanceId,MetadataOptions.HttpTokens,MetadataOptions.HttpPutResponseHopLimit]' \
  --output table

# Enforce v2-only with hop limit 1 on a launch template version
aws ec2 modify-instance-metadata-options \
  --instance-id i-0abc123def456 \
  --http-tokens required \
  --http-put-response-hop-limit 1 \
  --http-endpoint enabled

Validating and Sandboxing Outbound Fetches

Some features genuinely need the open web — a feed reader, a link preview for arbitrary sites, a migration importer. Allowlists can't cover 'any URL the user pastes,' so sandbox the fetch instead. Run retrievals in an isolated worker with no cloud credentials in its environment, no route to internal networks, and strict output limits: cap response size, cap time, strip active content from what you store. The fetcher becomes a disposable glove — useful, and safe to contaminate.

Design the sandbox in concentric rings. The worker runs with a dedicated minimal IAM role (or none), in a subnet whose route table has no path to internal tiers and an explicit deny for the metadata address. DNS goes through a resolver that refuses to answer private ranges. The fetched bytes are treated as hostile: images re-encoded, HTML parsed for text only, archives scanned before extraction. What returns to your main app is a sanitized artifact, never the raw response.

This architecture also simplifies incident response. When (not if) someone finds a bypass in your validation, the blast radius is a credential-less sandbox that can only talk to the public internet — annoying, not catastrophic. Log every fetch with source feature, target host, resolved IP, and redirect chain so the bypass announces itself in your telemetry instead of hiding in a generic HTTP client log.

Detecting SSRF Probes in Logs Before They Succeed

SSRF campaigns have a recognizable shape in telemetry: bursts of requests to unusual internal-looking targets, sequential paths or ports from few accounts, and redirect chains that terminate at link-local addresses. Your fetch helper should log the full chain — original URL, each redirect hop, final resolved IP — so analysts see the laundering, not just the innocent first hop. Without chain logging, the attack looks like normal traffic to a trusted domain.

Correlate application logs with network and cloud telemetry. VPC flow logs showing app hosts connecting to the metadata address are a finding on their own — legitimate apps rarely need it per-request. CloudTrail showing role credentials used from unexpected networks means probing already succeeded and the response is now revocation plus rotation. Set the alert threshold on patterns (sequential sweeping, metadata paths, private-range targets), not just volume, since low-and-slow probing stays under volumetric radar.

Rehearse the response so detection converts to containment in minutes: feature-flag the fetcher off, revoke and rotate the exposed role's sessions, and scope with logs before announcing. The 11-hour mining bill in the earlier incident wasn't a detection failure of exotic kind — billing was simply the only alert watching. A metadata-access alert would have fired on the first credential read.