httpx-secure 1.3.0

Drop-in SSRF protection for httpx

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.