Skip to main content

​
fastmcp.server.auth.ssrf

SSRF-safe HTTP utilities for FastMCP. This module provides SSRF-protected HTTP fetching with:
  • DNS resolution and IP validation before requests
  • DNS pinning to prevent rebinding TOCTOU attacks
  • Support for both CIMD and JWKS fetches
When FASTMCP_SSRF_TRUST_PROXY is set, DNS resolution and the IP blocklist are skipped and a single request is made to the hostname URL through the configured HTTPS_PROXY/ALL_PROXY, delegating DNS and egress to that trusted proxy (the scheme and hostname checks still apply). The proxy URL is read from the environment and passed to httpx2 explicitly with trust_env disabled, so the request is provably routed through the proxy rather than predicted to be — NO_PROXY is not evaluated in this mode. If no proxy is configured, the fetch is refused rather than sent direct with the blocklist disabled.

​
Functions

​
format_ip_for_url

Format IP address for use in URL (bracket IPv6 addresses). IPv6 addresses must be bracketed in URLs to distinguish the address from the port separator. For example: https://[2001:db8::1]:443/path Args:
  • ip_str: IP address string
Returns:
  • IP string suitable for URL (IPv6 addresses are bracketed)

​
is_ip_allowed

Check if an IP address is allowed (must be globally routable unicast). Uses ip.is_global which catches:
  • Private (10.x, 172.16-31.x, 192.168.x)
  • Loopback (127.x, ::1)
  • Link-local (169.254.x, fe80::) - includes AWS metadata!
  • Reserved, unspecified
  • RFC6598 Carrier-Grade NAT (100.64.0.0/10) - can point to internal networks
  • IPv6 transition forms that embed blocked IPv4 targets
Additionally blocks multicast addresses (not caught by is_global). Args:
  • ip_str: IP address string to check
Returns:
  • True if the IP is allowed (public unicast internet), False if blocked

​
resolve_hostname

Resolve hostname to IP addresses using DNS. Args:
  • hostname: Hostname to resolve
  • port: Port number (used for getaddrinfo)
Returns:
  • List of resolved IP addresses
Raises:
  • SSRFError: If resolution fails

​
validate_url

Validate URL for SSRF and resolve to IPs. Args:
  • url: URL to validate
  • require_path: If True, require non-root path (for CIMD)
Returns:
  • ValidatedURL with resolved IPs
Raises:
  • SSRFError: If the URL is invalid, resolves to blocked IPs, or proxy-trust mode is enabled but no configured proxy will route the request.

​
ssrf_safe_fetch

Fetch URL with comprehensive SSRF protection and DNS pinning. Security measures:
  1. HTTPS only
  2. DNS resolution with IP validation
  3. Connects to validated IP directly (DNS pinning prevents rebinding)
  4. Response size limit
  5. Redirects disabled
  6. Overall timeout
Args:
  • url: URL to fetch
  • require_path: If True, require non-root path
  • max_size: Maximum response size in bytes (default 5KB)
  • timeout: Per-operation timeout in seconds
  • overall_timeout: Overall timeout for entire operation
Returns:
  • Response body as bytes
Raises:
  • SSRFError: If SSRF validation fails
  • SSRFFetchError: If fetch fails

​
ssrf_safe_fetch_response

Fetch URL with SSRF protection and return response metadata. This is equivalent to :func:ssrf_safe_fetch but returns response headers and status code, and supports conditional request headers.

​
Classes

​
SSRFError

Raised when an SSRF protection check fails.

​
SSRFFetchError

Raised when SSRF-safe fetch fails.

​
ValidatedURL

A URL that has been validated for SSRF with resolved IPs.

​
SSRFFetchResponse

Response payload from an SSRF-safe fetch.