safehttpx

0.1.7 · active · verified Thu Apr 09

safehttpx is a small Python library designed to protect applications from Server Side Request Forgery (SSRF) attacks. It provides an asynchronous `safehttpx.get()` method, which wraps `httpx.AsyncClient.get()` while performing DNS validation using Google DNS and implementing mitigation for DNS rebinding attacks. The current version is 0.1.7, and releases are irregular, driven primarily by security updates and the needs of its primary consumer, Gradio.

Warnings

gotcha Setting `_transport=False` in `safehttpx.get()` explicitly bypasses all SSRF protections, effectively making the call equivalent to a raw `httpx.AsyncClient.get()`. This should only be used if you fully understand and accept the security implications.
Fix: Avoid using `_transport=False` unless absolutely necessary and with a clear understanding of the risks. Ensure all URLs passed to `safehttpx.get()` are intended for public access.
gotcha `safehttpx.get()` is an asynchronous function. It must be `await`-ed within an `async` function. In a script, you'll need to use `asyncio.run()` to execute the async call.
Fix: Always use `await safehttpx.get(...)` within an `async` function. For top-level calls in scripts, wrap the async function call with `asyncio.run(your_async_function())`.
gotcha safehttpx's DNS validation relies on Google DNS by default. While generally robust, highly restrictive network environments or specific corporate policies might require custom DNS resolvers. This could lead to legitimate external domains being blocked if Google DNS is unreachable or if local DNS records differ.
Fix: Ensure that Google DNS (8.8.8.8, 8.8.4.4) is reachable from your application's environment. If not, investigate network configuration or consider contributing to the library for custom DNS resolver options if needed.
gotcha safehttpx primarily focuses on securing `GET` requests. While it wraps `httpx`, users who directly instantiate `httpx.AsyncClient` or use other HTTP methods (like `POST`, `PUT`) without explicit safehttpx wrappers might inadvertently bypass the SSRF protections for those requests. The `safehttpx` module currently only exposes a `get` method.
Fix: Ensure all network requests that could be susceptible to SSRF are routed through `safehttpx.get()`. Do not assume other HTTP methods or direct `httpx` client usage inherit `safehttpx`'s protections.
breaking As `safehttpx` is a wrapper around `httpx`, it is implicitly affected by breaking changes in `httpx` (e.g., changes in redirect handling or SSL configuration). While `safehttpx` may pin `httpx` versions, custom environment setups could lead to mismatches.
Fix: Refer to the `httpx` changelog (e.g., v0.20.0 for redirect changes, v0.28.0 for SSL config changes) if unexpected behavior occurs. Ensure your `httpx` version is compatible with the `safehttpx` version you are using.

Install

pip install safehttpx PyPI

Imports

get
```
import safehttpx as sh
await sh.get(...)
```
The library is typically imported with the alias `sh` for brevity, as shown in official examples. Direct import is also functional but less common in examples.

Quickstart

This quickstart demonstrates how to use `safehttpx.get()` asynchronously. It attempts to fetch a valid external URL and then demonstrates how an attempt to access a local IP address (a common SSRF target) is blocked by default, raising a `ValueError`. Remember to run this in an async context.

import asyncio
import safehttpx as sh

async def fetch_safe_url():
    try:
        response = await sh.get("https://huggingface.co")
        response.raise_for_status() # Raise an exception for HTTP errors
        print(f"Success: {response.status_code} - {response.url}")
        # Example of blocked internal IP
        await sh.get("http://127.0.0.1")
    except ValueError as e:
        print(f"Validation Error: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == "__main__":
    asyncio.run(fetch_safe_url())

view raw JSON →