httpx-secure

Drop-in SSRF protection for httpx.

Why Use This?

• SSRF Protection: Block requests to private/internal IP addresses
• Custom Validation: Extend with your own validation logic
• Minimal Overhead: Efficient implementation with built-in DNS caching
• Broad Python Support: Compatible with Python 3.9+
• Semantic Versioning: Predictable, reliable updates
• Zero-Clause BSD: Public domain, use freely anywhere

Installation

pip install httpx-secure

Quick Start

import httpx
from httpx_secure import httpx_ssrf_protection

client = httpx_ssrf_protection(
    httpx.AsyncClient(),
    dns_cache_size=1000,  # Cache up to 1000 DNS resolutions
    dns_cache_ttl=600,    # Cache for 10 minutes
)

await client.get("https://public.domain")   # Allowed
await client.get("https://private.domain")  # Blocked

Custom Validation

For example, implement a simple domain whitelist to restrict requests to specific hosts:

import httpx
from httpx_secure import httpx_ssrf_protection
from ipaddress import IPv4Address, IPv6Address

def custom_validator(
    hostname: str,
    ip: IPv4Address | IPv6Address,
    port: int
) -> bool:
    return hostname in {
        "whitelisted.domain",
        "webhook.partner.com",
    }

client = httpx_ssrf_protection(
    httpx.AsyncClient(),
    custom_validator=custom_validator,
)

await client.get("https://whitelisted.domain")  # Allowed
await client.get("https://unknown.domain")      # Blocked

How It Works

1. Cache Lookup: First checks if the host has been recently validated and cached
2. DNS Resolution: If not cached, resolves the hostname to an IP address
3. Validation: Verifies the IP is globally routable, blocking private/internal addresses
4. Custom Validation: If provided, your custom validator is called for additional checks
5. Request Modification: Rewrites the request to use the validated IP directly

The DNS cache significantly reduces latency for repeated requests, while per-host locking ensures efficient concurrent resolution of parallel requests.

Tip

The SSRF protection applies to all HTTP methods (GET, POST, PUT, DELETE, etc.) and automatically validates redirects to prevent SSRF attacks through redirect chains.