Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 38 ยท Projects and Practice

Project: Build and Test an SSRF Guard

Build a URL guard that blocks private, loopback and metadata destinations, then write a test table with tricky inputs to prove it holds. No network calls are made.

In this project you write a reusable URL guard: a function every outbound fetch must call before connecting. You then build a table of tricky inputs and prove that it behaves. It makes the ideas from Defending Against SSRF concrete. The guard never opens connections; DNS answers come from a fake resolver so the results are the same every time.

Test-driven development fits well here: write the hostile cases first, then make them pass.

Design

The guard takes a URL and returns an object with allowed (true or false), a reason and, if allowed, the pinned IP to connect to. It enforces:

  1. Scheme is https only.
  2. No user-info (user:pass@) and no fragment tricks.
  3. Port 443 only.
  4. Host is on an allow-list (exact names or approved suffix).
  5. Every resolved address is public: not loopback, private, link-local (including 169.254.169.254), multicast, reserved, or an IPv4-mapped IPv6 form of those.
  6. Literal IP hosts are rejected outright, in any spelling.

Step 1: the address checker

Python Step 1: is this address public?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

2001:db8::1 is a documentation range and is not global, so it is rejected too, which is the safe default.

Step 2: the full guard

Python Step 2: the complete guard

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Read the cases as a security test table. api.partner.example is on the allow-list but has one bad DNS record, and the guard blocks the host because any non-public answer is risky.

Step 3: use the guard correctly

A guard that is called but then bypassed gives false comfort. The calling code must:

  1. Call the guard on the original URL.
  2. Connect to the returned IP (pinning), with TLS validation using the original host name.
  3. Disable automatic redirects, or call the guard again for each Location header.
  4. Apply timeouts and a size limit, and return only parsed data.

Sketch (read-only; the HTTP client calls depend on your language):

Python
ok, reason, ip = guard(user_url)
if not ok:
    log_security_event("ssrf_blocked", reason=reason, url=user_url)
    return error("That address is not allowed")
response = http_get(connect_to=ip, server_name=host, follow_redirects=False,
                    timeout=3, max_bytes=2_000_000)
Python Step 3: redirect-aware fetch simulation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Extend the project

  • Add a per-host port allow-list instead of a global rule.
  • Return a generic error to the user and the detailed reason only to the log.
  • Add rate limiting for the fetch feature itself.
  • Turn the case table into a unit test file that fails the build when behavior changes.
  • Add a new hostile case you invented, run it, and fix the guard if it passes through.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Why does the guard return a pinned IP address?

    Pinning closes the DNS rebinding window between checking and connecting.
  2. 2. api.partner.example is allow-listed but one DNS record is 127.0.0.1. What does the guard do and why?

    An allow-listed name can still resolve to internal addresses; all answers must be public.
  3. 3. Why test with a table of hostile inputs?

    A security test table turns the threat list into repeatable checks.

Summary

  • Build the guard from small, tested pieces: address checks, allow-list, resolved-IP validation.
  • Reject literal IPs and unusual spellings, non-HTTPS schemes, odd ports and embedded credentials.
  • Use the pinned address, disable or re-validate redirects, and limit time and size.
  • Keep a test table of hostile cases and grow it over time.

Next: OWASP Top 10 Review and Practice Scenarios