CleanSnapv1 API
All 25 Developer GuidesSecurity & Production
Advanced·8 min read·Topic: prevent ssrf in url preview api

Preventing SSRF in URL Preview & Web Extraction APIs (Node.js Checklist)

Lock down any backend that fetches user-supplied URLs against cloud metadata theft, localhost probing, and redirect bypasses.

Why this breaks in production

Any API that accepts a `url` parameter and calls `fetch(url)` is a prime target for Server-Side Request Forgery (SSRF). Attackers pass `http://169.254.169.254/latest/meta-data/`, `http://[::ffff:127.0.0.1]:6379`, or a public domain that 302-redirects to `http://localhost:8080`.

Checking only `url.startsWith('https://')` is completely insufficient. Real SSRF defense validates schemes, blocks private IPv4 and IPv6 blocks, resolves DNS records before connecting, and re-validates every manual redirect hop.

Recommended Engineering Approach

1

Whitelist only `http:` and `https:` schemes with no credentials

Reject `file://`, `gopher://`, `ftp://`, `data:`, and any URL containing `username` or `password`.

2

Resolve DNS and block all private/reserved IPv4 & IPv6 CIDRs

Block `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, `100.64.0.0/10`, `::1`, `fc00::/7`, `fe80::/10`, and `::ffff:` IPv4-mapped IPv6 addresses.

3

Disable automatic redirects (`redirect: 'manual'`) and validate each hop

Re-run your full SSRF check on every `Location` header and cap total hops at 4.

Working Code Example

ssrf-safe-redirect-loop.tsts
// Core pattern used inside CleanSnap's lib/extractor.ts
let current = await assertSafePublicUrl(rawUrl);

for (let hop = 0; hop <= 4; hop++) {
  const res = await fetch(current.toString(), {
    redirect: "manual",
    signal: AbortSignal.timeout(10_000),
  });

  if (res.status >= 300 && res.status < 400) {
    const loc = res.headers.get("location");
    if (!loc) throw new Error("Redirect missing Location");
    // Re-validate every redirect target against private IPs & DNS!
    current = await assertSafePublicUrl(new URL(loc, current).toString());
    continue;
  }

  return await res.text();
}
TRY IT LIVE — ZERO LOGIN

Test this workflow in the CleanSnap Playground

Pre-load the Sample Docs Page or paste your own URL to inspect clean Markdown, token savings, and auto-generated cURL / Node / Python / MCP code.

Run Sample Docs Page

Common Edge Cases & Pitfalls

  • Forgetting IPv4-mapped IPv6 addresses (`http://[::ffff:169.254.169.254]`) bypasses naive IPv4-only regex filters.
  • Letting `fetch` follow redirects automatically allows a benign public URL to bounce straight to `127.0.0.1`.
  • Omitting a max response byte cap lets an attacker point your server at a 10 GB binary stream to cause an OOM crash.

Frequently Asked Questions

Does CleanSnap block localhost and cloud metadata IPs?

Yes — CleanSnap blocks localhost, `.local`, `.internal`, RFC1918 IPv4, link-local `169.254.0.0/16`, CGNAT, private IPv6, and DNS records resolving to private IPs, returning HTTP 403 `SSRF_BLOCKED`.

Why cap HTML payload size in an extraction API?

Enforcing a strict ceiling (3 MB in CleanSnap) prevents memory exhaustion DoS attacks against serverless functions.

Can I test CleanSnap's SSRF guard directly?

Yes — try submitting `http://127.0.0.1:3000` or `http://169.254.169.254` in the playground and observe the immediate `403 SSRF_BLOCKED` response.

Related Developer Guides