| Name | safehttpx JSON |
| Version |
0.1.6
JSON |
| download |
| home_page | None |
| Summary | A small Python library created to help developers protect their applications from Server Side Request Forgery (SSRF) attacks. |
| upload_time | 2024-12-02 18:44:10 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >3.9 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# safehttpx
A small Python library created to help developers protect their applications from Server Side Request Forgery (SSRF) attacks. It implements an **asynchronous GET method** called `safehttpx.get()`, which is a wrapper around `httpx.AsyncClient.get()` while performing DNS validation on the supplied URL using [Google DNS](https://developers.google.com/speed/public-dns).
It also implements mitigation for [DNS rebinding](https://en.wikipedia.org/wiki/DNS_rebinding) attacks.
## Why?
Server Side Request Forgery (SSRF) attacks can be particularly dangerous as they allow attackers to make arbitrary HTTP requests from your server, potentially accessing sensitive internal services that are normally unreachable from the internet. This could enable attackers to scan internal networks, access metadata services in cloud environments (like "AWS Instance Metadata Service"), or hit internal APIs - all while appearing to come from your trusted server. By validating URLs against public DNS servers and implementing protections against DNS rebinding, `safehttpx` helps prevent attackers from coercing your application into making requests to internal or otherwise restricted network resources.
## Usage
### Installation
```bash
$ pip install safehttpx
```
Also avalaible through Conda
```bash
$ conda install safehttpx -c conda-forge
```
or
```bash
$ mamba install safehttpx -c conda-forge
```
### Basic Usage
```py
import safehttpx as sh
await sh.get("https://huggingface.co")
>>> <Response [200 OK]>
await sh.get("http://127.0.0.1")
>>> ValueError: Hostname 127.0.0.1 failed validation
```
**Note on Async Usage:**
The example snippets above will work in environments like IPython or Jupyter notebooks where an asyncio event loop is already running. For regular Python scripts, you'll need to explicitly create and run an asyncio event loop. Here's how you can structure your code to use `safehttpx` in a standard Python script:
```python
import asyncio
import safehttpx as sh
asyncio.run(sh.get("https://huggingface.co"))
>>> <Response [200 OK]>
```
### Whitelisted Domains
You may want to whitelist certain domains from being validated. For example, if you are running code on a server that implements DNS splitting, then even public URLs may appear as internal URLs. You can whitelist domains like this:
```py
import safehttpx as sh
PUBLIC_HOSTNAME_WHITELIST = ["hf.co", "huggingface.co"]
await sh.get("https://huggingface.co", domain_whitelist=PUBLIC_HOSTNAME_WHITELIST)
>>> <Response [200 OK]>
```
### Custom Transports (Advanced)
If you know what you are doing, and what to pass in a custom instance of
`httpx.AsyncBaseTransport`, you can use the `_transport` parameter in `sh.get()`. Setting
this to `False` explicitly will use no secure transport (effectively
making `sh.get` equivalent to `httpx.AsyncClient.get()`).
## More Information
This library was created as a result of Trail of Bits' security audit of Gradio 5 (Hugging Face), and is used [in the Gradio library](https://github.com/gradio-app/gradio/) to make secure requests to arbitrary user-specified URLs. We are releasing this as a standalone library so that other developers can benefit from our learnings. In the interest of transparency and the spirit of open-source, we are making the [full security audit public](https://github.com/trailofbits/publications/blob/master/reviews/2024-10-huggingface-gradio-securityreview.pdf).
If you find a security issue in this library, please email the Gradio team at `gradio-team@huggingface.co`. Thanks!
Raw data
{
"_id": null,
"home_page": null,
"name": "safehttpx",
"maintainer": null,
"docs_url": null,
"requires_python": ">3.9",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Abubakar Abid <abubakar@hf.co>",
"download_url": "https://files.pythonhosted.org/packages/67/4c/19db75e6405692b2a96af8f06d1258f8aa7290bdc35ac966f03e207f6d7f/safehttpx-0.1.6.tar.gz",
"platform": null,
"description": "# safehttpx\n\nA small Python library created to help developers protect their applications from Server Side Request Forgery (SSRF) attacks. It implements an **asynchronous GET method** called `safehttpx.get()`, which is a wrapper around `httpx.AsyncClient.get()` while performing DNS validation on the supplied URL using [Google DNS](https://developers.google.com/speed/public-dns). \n\nIt also implements mitigation for [DNS rebinding](https://en.wikipedia.org/wiki/DNS_rebinding) attacks.\n\n## Why?\n\nServer Side Request Forgery (SSRF) attacks can be particularly dangerous as they allow attackers to make arbitrary HTTP requests from your server, potentially accessing sensitive internal services that are normally unreachable from the internet. This could enable attackers to scan internal networks, access metadata services in cloud environments (like \"AWS Instance Metadata Service\"), or hit internal APIs - all while appearing to come from your trusted server. By validating URLs against public DNS servers and implementing protections against DNS rebinding, `safehttpx` helps prevent attackers from coercing your application into making requests to internal or otherwise restricted network resources.\n\n## Usage\n\n### Installation\n\n```bash\n$ pip install safehttpx\n```\nAlso avalaible through Conda\n```bash\n$ conda install safehttpx -c conda-forge\n```\nor\n```bash\n$ mamba install safehttpx -c conda-forge\n```\n### Basic Usage\n\n```py\nimport safehttpx as sh\n\nawait sh.get(\"https://huggingface.co\")\n>>> <Response [200 OK]>\n\nawait sh.get(\"http://127.0.0.1\")\n>>> ValueError: Hostname 127.0.0.1 failed validation\n```\n\n**Note on Async Usage:**\n\nThe example snippets above will work in environments like IPython or Jupyter notebooks where an asyncio event loop is already running. For regular Python scripts, you'll need to explicitly create and run an asyncio event loop. Here's how you can structure your code to use `safehttpx` in a standard Python script:\n\n```python\nimport asyncio\nimport safehttpx as sh\n\nasyncio.run(sh.get(\"https://huggingface.co\"))\n>>> <Response [200 OK]>\n```\n\n### Whitelisted Domains\n\nYou may want to whitelist certain domains from being validated. For example, if you are running code on a server that implements DNS splitting, then even public URLs may appear as internal URLs. You can whitelist domains like this:\n\n\n```py\nimport safehttpx as sh\n\nPUBLIC_HOSTNAME_WHITELIST = [\"hf.co\", \"huggingface.co\"]\n\nawait sh.get(\"https://huggingface.co\", domain_whitelist=PUBLIC_HOSTNAME_WHITELIST)\n>>> <Response [200 OK]>\n```\n\n### Custom Transports (Advanced)\n\nIf you know what you are doing, and what to pass in a custom instance of\n`httpx.AsyncBaseTransport`, you can use the `_transport` parameter in `sh.get()`. Setting\nthis to `False` explicitly will use no secure transport (effectively \nmaking `sh.get` equivalent to `httpx.AsyncClient.get()`).\n\n## More Information\n\nThis library was created as a result of Trail of Bits' security audit of Gradio 5 (Hugging Face), and is used [in the Gradio library](https://github.com/gradio-app/gradio/) to make secure requests to arbitrary user-specified URLs. We are releasing this as a standalone library so that other developers can benefit from our learnings. In the interest of transparency and the spirit of open-source, we are making the [full security audit public](https://github.com/trailofbits/publications/blob/master/reviews/2024-10-huggingface-gradio-securityreview.pdf).\n\nIf you find a security issue in this library, please email the Gradio team at `gradio-team@huggingface.co`. Thanks!\n",
"bugtrack_url": null,
"license": null,
"summary": "A small Python library created to help developers protect their applications from Server Side Request Forgery (SSRF) attacks.",
"version": "0.1.6",
"project_urls": {
"homepage": "https://github.com/gradio-app/safehttpx",
"repository": "https://github.com/gradio-app/safehttpx"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4dc01108ad9f01567f66b3154063605b350b69c3c9366732e09e45f9fd0d1deb",
"md5": "6586a72dd275603d865c4cc28791fcb5",
"sha256": "407cff0b410b071623087c63dd2080c3b44dc076888d8c5823c00d1e58cb381c"
},
"downloads": -1,
"filename": "safehttpx-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6586a72dd275603d865c4cc28791fcb5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.9",
"size": 8692,
"upload_time": "2024-12-02T18:44:08",
"upload_time_iso_8601": "2024-12-02T18:44:08.555127Z",
"url": "https://files.pythonhosted.org/packages/4d/c0/1108ad9f01567f66b3154063605b350b69c3c9366732e09e45f9fd0d1deb/safehttpx-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "674c19db75e6405692b2a96af8f06d1258f8aa7290bdc35ac966f03e207f6d7f",
"md5": "c9bd00f12c7ef214d8366d1c00bda93d",
"sha256": "b356bfc82cee3a24c395b94a2dbeabbed60aff1aa5fa3b5fe97c4f2456ebce42"
},
"downloads": -1,
"filename": "safehttpx-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "c9bd00f12c7ef214d8366d1c00bda93d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.9",
"size": 9987,
"upload_time": "2024-12-02T18:44:10",
"upload_time_iso_8601": "2024-12-02T18:44:10.226506Z",
"url": "https://files.pythonhosted.org/packages/67/4c/19db75e6405692b2a96af8f06d1258f8aa7290bdc35ac966f03e207f6d7f/safehttpx-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-02 18:44:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gradio-app",
"github_project": "safehttpx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "safehttpx"
}
