Metadata-Version: 2.4
Name: httpx-secure
Version: 1.3.0
Summary: Drop-in SSRF protection for httpx
Project-URL: Issues, https://github.com/Zaczero/pkgs/issues
Project-URL: Repository, https://github.com/Zaczero/pkgs/tree/main/httpx-secure
Author-email: Kamil Monicz <kamil@monicz.dev>
License-Expression: 0BSD
Keywords: anyio,async,asyncio,client,dns,dns-cache,http,httpx,security,ssrf,ssrf-protection,trio,web-security
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AnyIO
Classifier: Framework :: AsyncIO
Classifier: Framework :: Trio
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zero-Clause BSD (0BSD)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: anyio>=3.0.0
Requires-Dist: httpx>=0.20.0
Description-Content-Type: text/markdown

# httpx-secure

[![PyPI - Python Version](https://shields.monicz.dev/pypi/pyversions/httpx-secure)](https://pypi.org/p/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**](https://semver.org): Predictable, reliable updates
- [**Zero-Clause BSD**](https://choosealicense.com/licenses/0bsd/): Public domain, use freely anywhere

## Installation

```sh
pip install httpx-secure
```

## Quick Start

```python
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:

```python
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.
