{"id":2270,"library":"safehttpx","title":"safehttpx","description":"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.","status":"active","version":"0.1.7","language":"en","source_language":"en","source_url":"https://github.com/gradio-app/safehttpx","tags":["security","ssrf","httpx","async","networking","dns-validation"],"install":[{"cmd":"pip install safehttpx","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Core dependency, safehttpx wraps httpx.AsyncClient.","package":"httpx","optional":false}],"imports":[{"note":"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.","wrong":"import safehttpx\nsafehttpx.get()","symbol":"get","correct":"import safehttpx as sh\nawait sh.get(...)"}],"quickstart":{"code":"import asyncio\nimport safehttpx as sh\n\nasync def fetch_safe_url():\n    try:\n        response = await sh.get(\"https://huggingface.co\")\n        response.raise_for_status() # Raise an exception for HTTP errors\n        print(f\"Success: {response.status_code} - {response.url}\")\n        # Example of blocked internal IP\n        await sh.get(\"http://127.0.0.1\")\n    except ValueError as e:\n        print(f\"Validation Error: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(fetch_safe_url())","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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())`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"Potentially all versions, depending on `httpx` version pinning and user environment."}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}