---
title: ssrf
sidebarTitle: ssrf
---
# `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
## Functions
### `format_ip_for_url`
```python
format_ip_for_url(ip_str: str) -> str
```
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`
```python
is_ip_allowed(ip_str: str) -> bool
```
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
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`
```python
resolve_hostname(hostname: str, port: int = 443) -> list[str]
```
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`
```python
validate_url(url: str, require_path: bool = False) -> ValidatedURL
```
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 URL is invalid or resolves to blocked IPs
### `ssrf_safe_fetch`
```python
ssrf_safe_fetch(url: str) -> bytes
```
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`
```python
ssrf_safe_fetch_response(url: str) -> SSRFFetchResponse
```
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.