# Wormhole
[](https://pypi.org/project/wormhole-proxy/)
[](https://quay.io/repository/cwt/wormhole)
**Wormhole** is a forward proxy without caching. You may use it for:
- Modifying requests to look like they are originated from the IP
address that *Wormhole* is running on.
- Adding an authentication layer to the internet users in your
organization.
- Logging internet activities to your syslog server.
- Blocking ads and other unwanted content.
-----
## Features
- **Secure Digest Authentication:** Wormhole supports HTTP Digest Authentication with the modern **SHA-256** algorithm. Passwords are never stored in plain text, providing a significant security improvement over Basic Authentication.
- **Ad-blocking:** Wormhole can block domains based on a comprehensive list of ad-serving and tracking domains. You can create your own ad-block database or use the provided script to download and compile one from popular sources.
- **Allowlist:** You can specify a list of domains that should never be blocked, ensuring that important services are always accessible.
- **HTTP/1.1 Upgrade:** Automatically attempts to upgrade HTTP/1.0 requests to HTTP/1.1 to leverage modern web features and improve performance.
- **IPv6 Prioritization:** Prefers IPv6 connections when available for faster and more modern networking.
- **Security:** Includes safeguards to prevent proxying to private and reserved IP addresses, mitigating the risk of SSRF (Server-Side Request Forgery) attacks.
- **High Performance:** Built with `asyncio` and can leverage `uvloop` or `winloop` for even better performance. The number of concurrent connections is dynamically adjusted based on system limits.
-----
## Dependency
- Python \>= 3.11
- aiodns
- aiohttp
- aiosqlite
- loguru
- pywin32 (required for Windows)
- [uvloop](https://github.com/MagicStack/uvloop) (optional for Linux and macOS)
- [winloop](https://github.com/Vizonex/Winloop) (optional for Windows)
-----
## How to install
### Stable Version
Please install the **stable version** using `pip` command:
```shell
$ pip install wormhole-proxy
```
### Development Snapshot
You can install the **development snapshot** from the **main** branch on GitHub using the following command:
```shell
$ pip install git+https://github.com/cwt/wormhole.git@main
```
You can also install the **development snapshot** using `pip` with
`mercurial`:
```shell
$ pip install hg+https://hg.sr.ht/~cwt/wormhole
```
Or install from your local clone:
```shell
$ hg clone https://hg.sr.ht/~cwt/wormhole
$ cd wormhole/
$ pip install -e .
```
You can also install the latest `tip` snapshot using the following
command:
```shell
$ pip install https://hg.sr.ht/~cwt/wormhole/archive/tip.tar.gz
```
-----
## How to use
1. Run **wormhole** command
```shell
$ wormhole
```
2. Set browser's proxy setting to
```shell
host: 127.0.0.1
port: 8800
```
### Authentication Setup
Wormhole includes built-in tools to securely manage users. These commands will prompt you to enter and confirm passwords interactively.
* **To create an authentication file and add a new user:**
```shell
$ wormhole --auth-add wormhole.passwd <username>
```
* **To change an existing user's password:**
```shell
$ wormhole --auth-mod wormhole.passwd <username>
```
* **To delete a user:**
```shell
$ wormhole --auth-del wormhole.passwd <username>
```
* **To run the proxy with authentication enabled:**
```shell
$ wormhole --auth wormhole.passwd
```
### Ad-Blocker Usage
1. **Update the ad-block database:**
```shell
$ wormhole --update-ad-block-db ads.sqlite3
```
2. **Run Wormhole with the ad-blocker enabled:**
```shell
$ wormhole --ad-block-db ads.sqlite3
```
-----
## Command help
```shell
$ wormhole --help
```
The output will be similar to this:
```
usage: wormhole [-h] [-H HOST] [-p PORT] [--allow-private] [-S SYSLOG_HOST] [-P SYSLOG_PORT] [-l] [-v]
[--auth AUTH_FILE] [--auth-add <AUTH_FILE> <USERNAME>] [--auth-mod <AUTH_FILE> <USERNAME>]
[--auth-del <AUTH_FILE> <USERNAME>] [--ad-block-db AD_BLOCK_DB] [--update-ad-block-db DB_PATH]
[--allowlist ALLOWLIST]
Wormhole (3.1.3): Asynchronous I/O HTTP/S Proxy
options:
-h, --help show this help message and exit
-H HOST, --host HOST Host address to bind [default: 0.0.0.0]
-p PORT, --port PORT Port to listen on [default: 8800]
--allow-private Allow proxying to private and reserved IP addresses (disabled by default)
-S SYSLOG_HOST, --syslog-host SYSLOG_HOST
Syslog host or path (e.g., /dev/log)
-P SYSLOG_PORT, --syslog-port SYSLOG_PORT
Syslog port [default: 514]
-l, --license Print license information and exit
-v, --verbose Increase verbosity (-v, -vv)
Authentication Options:
--auth AUTH_FILE Enable Digest authentication using the specified file.
--auth-add <AUTH_FILE> <USERNAME>
Add a user to the authentication file and exit.
--auth-mod <AUTH_FILE> <USERNAME>
Modify a user's password in the authentication file and exit.
--auth-del <AUTH_FILE> <USERNAME>
Delete a user from the authentication file and exit.
Ad-Blocker Options:
--ad-block-db AD_BLOCK_DB
Path to the SQLite database file containing domains to block.
--update-ad-block-db DB_PATH
Fetch public ad-block lists and compile them into a database file, then exit.
--allowlist ALLOWLIST
Path to a file of domains to extend the default allowlist.
```
-----
## **Docker Image Usage**
Official images are available at [quay.io/cwt/wormhole](https://quay.io/repository/cwt/wormhole).
### **1. Pull the image**
Pull the desired version tag from Quay.io.
```shell
# Replace <tag> with a specific version, e.g., v3.1.2
podman pull quay.io/cwt/wormhole:<tag>
```
### **2. Run without special configuration**
To run Wormhole on the default port 8800 without authentication or ad-blocking:
```shell
podman run --rm -it -p 8800:8800 quay.io/cwt/wormhole:<tag>
```
### **3. Running with Ad-Blocker**
**Step A: Create the ad-block database on your host**
First, you need to have a local config path to save the generated database file.
```shell
mkdir -p /path/to/config # change this to your desired path
```
Then, run the following command to create the ad-block database file:
```shell
podman run --rm -it -v /path/to/config:/config quay.io/cwt/wormhole:<tag> wormhole --update-ad-block-db /config/ads.sqlite3
```
This will create a file named ads.sqlite3 in `/path/to/config/` on your host.
**Step B: Run the container with the database mounted**
Now, run the container, mounting the ads.sqlite3 file into the container's `/config` directory.
```shell
# Using :ro mounts the database as read-only for better security.
podman run --rm -it -p 8800:8800 \
-v /path/to/config/ads.sqlite3:/config/ads.sqlite3:ro \
quay.io/cwt/wormhole:<tag> \
wormhole --ad-block-db /config/ads.sqlite3
```
### **4. Running with Authentication**
**Step A: Create an authentication file**
First, you need to have a local config path to save the generated authentication file.
```shell
mkdir -p /path/to/config # change this to your desired path
```
Run a temporary container to create the authentication file. You will be prompted to enter a password for the new user.
```shell
# Replace <username> with your desired username
podman run --rm -it -v /path/to/config:/config quay.io/cwt/wormhole:<tag> \
wormhole --auth-add /config/wormhole.passwd <username>
```
**Step B: Run the container with the auth file mounted**
Mount the authentication file into the `/config` directory.
```shell
# Replace /path/to/config with the absolute path to your wormhole.passwd file.
podman run --rm -it -p 8800:8800 \
-v /path/to/config/wormhole.passwd:/config/wormhole.passwd:ro \
quay.io/cwt/wormhole:<tag> \
wormhole -a /config/wormhole.passwd
```
*(Note: You can use docker in place of podman for all examples.)*
-----
## License
MIT License (included in the source distribution)
-----
## Notice
- This project is forked and converted to Mercurial from
[WARP](https://github.com/devunt/warp) on GitHub.
Raw data
{
"_id": null,
"home_page": "https://hg.sr.ht/~cwt/wormhole",
"name": "wormhole-proxy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "wormhole, asynchronous, web, proxy",
"author": "Chaiwat Suttipongsakul",
"author_email": "cwt@bashell.com",
"download_url": "https://files.pythonhosted.org/packages/0d/a2/2cbeb532fad90af6fb7fba6b8201025312478fcb382868af70f44d6c6c24/wormhole_proxy-3.3.3.tar.gz",
"platform": null,
"description": "# Wormhole\n\n[](https://pypi.org/project/wormhole-proxy/)\n[![Quay.io Build Status](https://quay.io/repository/cwt/wormhole/status \"Quay.io Build Status\")](https://quay.io/repository/cwt/wormhole)\n\n**Wormhole** is a forward proxy without caching. You may use it for:\n\n - Modifying requests to look like they are originated from the IP\n address that *Wormhole* is running on.\n - Adding an authentication layer to the internet users in your\n organization.\n - Logging internet activities to your syslog server.\n - Blocking ads and other unwanted content.\n\n-----\n\n## Features\n\n - **Secure Digest Authentication:** Wormhole supports HTTP Digest Authentication with the modern **SHA-256** algorithm. Passwords are never stored in plain text, providing a significant security improvement over Basic Authentication.\n - **Ad-blocking:** Wormhole can block domains based on a comprehensive list of ad-serving and tracking domains. You can create your own ad-block database or use the provided script to download and compile one from popular sources.\n - **Allowlist:** You can specify a list of domains that should never be blocked, ensuring that important services are always accessible.\n - **HTTP/1.1 Upgrade:** Automatically attempts to upgrade HTTP/1.0 requests to HTTP/1.1 to leverage modern web features and improve performance.\n - **IPv6 Prioritization:** Prefers IPv6 connections when available for faster and more modern networking.\n - **Security:** Includes safeguards to prevent proxying to private and reserved IP addresses, mitigating the risk of SSRF (Server-Side Request Forgery) attacks.\n - **High Performance:** Built with `asyncio` and can leverage `uvloop` or `winloop` for even better performance. The number of concurrent connections is dynamically adjusted based on system limits.\n\n-----\n\n## Dependency\n\n - Python \\>= 3.11\n - aiodns\n - aiohttp\n - aiosqlite\n - loguru\n - pywin32 (required for Windows)\n - [uvloop](https://github.com/MagicStack/uvloop) (optional for Linux and macOS)\n - [winloop](https://github.com/Vizonex/Winloop) (optional for Windows)\n\n-----\n\n## How to install\n\n### Stable Version\n\nPlease install the **stable version** using `pip` command:\n\n```shell\n$ pip install wormhole-proxy\n```\n\n### Development Snapshot\n\nYou can install the **development snapshot** from the **main** branch on GitHub using the following command:\n\n```shell\n$ pip install git+https://github.com/cwt/wormhole.git@main\n```\n\nYou can also install the **development snapshot** using `pip` with\n`mercurial`:\n\n```shell\n$ pip install hg+https://hg.sr.ht/~cwt/wormhole\n```\n\nOr install from your local clone:\n\n```shell\n$ hg clone https://hg.sr.ht/~cwt/wormhole\n$ cd wormhole/\n$ pip install -e .\n```\n\nYou can also install the latest `tip` snapshot using the following\ncommand:\n\n```shell\n$ pip install https://hg.sr.ht/~cwt/wormhole/archive/tip.tar.gz\n```\n\n-----\n\n## How to use\n\n1. Run **wormhole** command\n\n ```shell\n $ wormhole\n ```\n\n2. Set browser's proxy setting to\n\n ```shell\n host: 127.0.0.1\n port: 8800\n ```\n\n### Authentication Setup\n\nWormhole includes built-in tools to securely manage users. These commands will prompt you to enter and confirm passwords interactively.\n\n * **To create an authentication file and add a new user:**\n\n ```shell\n $ wormhole --auth-add wormhole.passwd <username>\n ```\n\n * **To change an existing user's password:**\n\n ```shell\n $ wormhole --auth-mod wormhole.passwd <username>\n ```\n\n * **To delete a user:**\n\n ```shell\n $ wormhole --auth-del wormhole.passwd <username>\n ```\n\n * **To run the proxy with authentication enabled:**\n\n ```shell\n $ wormhole --auth wormhole.passwd\n ```\n\n### Ad-Blocker Usage\n\n1. **Update the ad-block database:**\n\n ```shell\n $ wormhole --update-ad-block-db ads.sqlite3\n ```\n\n2. **Run Wormhole with the ad-blocker enabled:**\n\n ```shell\n $ wormhole --ad-block-db ads.sqlite3\n ```\n\n-----\n\n## Command help\n\n```shell\n$ wormhole --help\n```\n\nThe output will be similar to this:\n\n```\nusage: wormhole [-h] [-H HOST] [-p PORT] [--allow-private] [-S SYSLOG_HOST] [-P SYSLOG_PORT] [-l] [-v]\n [--auth AUTH_FILE] [--auth-add <AUTH_FILE> <USERNAME>] [--auth-mod <AUTH_FILE> <USERNAME>]\n [--auth-del <AUTH_FILE> <USERNAME>] [--ad-block-db AD_BLOCK_DB] [--update-ad-block-db DB_PATH]\n [--allowlist ALLOWLIST]\n\nWormhole (3.1.3): Asynchronous I/O HTTP/S Proxy\n\noptions:\n -h, --help show this help message and exit\n -H HOST, --host HOST Host address to bind [default: 0.0.0.0]\n -p PORT, --port PORT Port to listen on [default: 8800]\n --allow-private Allow proxying to private and reserved IP addresses (disabled by default)\n -S SYSLOG_HOST, --syslog-host SYSLOG_HOST\n Syslog host or path (e.g., /dev/log)\n -P SYSLOG_PORT, --syslog-port SYSLOG_PORT\n Syslog port [default: 514]\n -l, --license Print license information and exit\n -v, --verbose Increase verbosity (-v, -vv)\n\nAuthentication Options:\n --auth AUTH_FILE Enable Digest authentication using the specified file.\n --auth-add <AUTH_FILE> <USERNAME>\n Add a user to the authentication file and exit.\n --auth-mod <AUTH_FILE> <USERNAME>\n Modify a user's password in the authentication file and exit.\n --auth-del <AUTH_FILE> <USERNAME>\n Delete a user from the authentication file and exit.\n\nAd-Blocker Options:\n --ad-block-db AD_BLOCK_DB\n Path to the SQLite database file containing domains to block.\n --update-ad-block-db DB_PATH\n Fetch public ad-block lists and compile them into a database file, then exit.\n --allowlist ALLOWLIST\n Path to a file of domains to extend the default allowlist.\n```\n\n-----\n\n## **Docker Image Usage**\n\nOfficial images are available at [quay.io/cwt/wormhole](https://quay.io/repository/cwt/wormhole).\n\n### **1. Pull the image**\n\nPull the desired version tag from Quay.io.\n\n```shell\n# Replace <tag> with a specific version, e.g., v3.1.2 \npodman pull quay.io/cwt/wormhole:<tag>\n```\n\n### **2. Run without special configuration**\n\nTo run Wormhole on the default port 8800 without authentication or ad-blocking:\n\n```shell\npodman run --rm -it -p 8800:8800 quay.io/cwt/wormhole:<tag>\n```\n\n### **3. Running with Ad-Blocker**\n\n**Step A: Create the ad-block database on your host**\n\nFirst, you need to have a local config path to save the generated database file.\n\n```shell\nmkdir -p /path/to/config # change this to your desired path\n```\n\nThen, run the following command to create the ad-block database file:\n\n```shell\npodman run --rm -it -v /path/to/config:/config quay.io/cwt/wormhole:<tag> wormhole --update-ad-block-db /config/ads.sqlite3\n```\n\nThis will create a file named ads.sqlite3 in `/path/to/config/` on your host.\n\n**Step B: Run the container with the database mounted**\n\nNow, run the container, mounting the ads.sqlite3 file into the container's `/config` directory.\n\n```shell\n# Using :ro mounts the database as read-only for better security.\npodman run --rm -it -p 8800:8800 \\\n -v /path/to/config/ads.sqlite3:/config/ads.sqlite3:ro \\\n quay.io/cwt/wormhole:<tag> \\\n wormhole --ad-block-db /config/ads.sqlite3\n```\n\n### **4. Running with Authentication**\n\n**Step A: Create an authentication file**\n\nFirst, you need to have a local config path to save the generated authentication file.\n\n```shell\nmkdir -p /path/to/config # change this to your desired path\n```\n\nRun a temporary container to create the authentication file. You will be prompted to enter a password for the new user.\n\n```shell\n# Replace <username> with your desired username\npodman run --rm -it -v /path/to/config:/config quay.io/cwt/wormhole:<tag> \\\n wormhole --auth-add /config/wormhole.passwd <username>\n```\n\n**Step B: Run the container with the auth file mounted**\n\nMount the authentication file into the `/config` directory.\n\n```shell\n# Replace /path/to/config with the absolute path to your wormhole.passwd file.\npodman run --rm -it -p 8800:8800 \\\n -v /path/to/config/wormhole.passwd:/config/wormhole.passwd:ro \\\n quay.io/cwt/wormhole:<tag> \\\n wormhole -a /config/wormhole.passwd\n```\n\n*(Note: You can use docker in place of podman for all examples.)*\n\n-----\n\n## License\n\nMIT License (included in the source distribution)\n\n-----\n\n## Notice\n\n - This project is forked and converted to Mercurial from\n [WARP](https://github.com/devunt/warp) on GitHub.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Asynchronous I/O HTTP and HTTPS Proxy on Python >= 3.11",
"version": "3.3.3",
"project_urls": {
"Homepage": "https://hg.sr.ht/~cwt/wormhole"
},
"split_keywords": [
"wormhole",
" asynchronous",
" web",
" proxy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5870d933897fd91bc3e1cc9e1168632c616b9092c7ce7b689f47d1ddb168cc29",
"md5": "d2a89e23f172a08f19be1c43aff4fc62",
"sha256": "86262de26561852e662c8e610762c3df1977b2454c98838292ba4ddd5a67afff"
},
"downloads": -1,
"filename": "wormhole_proxy-3.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d2a89e23f172a08f19be1c43aff4fc62",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 29426,
"upload_time": "2025-07-11T16:49:44",
"upload_time_iso_8601": "2025-07-11T16:49:44.110564Z",
"url": "https://files.pythonhosted.org/packages/58/70/d933897fd91bc3e1cc9e1168632c616b9092c7ce7b689f47d1ddb168cc29/wormhole_proxy-3.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0da22cbeb532fad90af6fb7fba6b8201025312478fcb382868af70f44d6c6c24",
"md5": "69eb523755ec06de56549830018d4d58",
"sha256": "8dbe970a2c72981f1e7daacd650d9ec938cac1ddad9bbabd40b44f0dcc8e313a"
},
"downloads": -1,
"filename": "wormhole_proxy-3.3.3.tar.gz",
"has_sig": false,
"md5_digest": "69eb523755ec06de56549830018d4d58",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 26911,
"upload_time": "2025-07-11T16:49:45",
"upload_time_iso_8601": "2025-07-11T16:49:45.626591Z",
"url": "https://files.pythonhosted.org/packages/0d/a2/2cbeb532fad90af6fb7fba6b8201025312478fcb382868af70f44d6c6c24/wormhole_proxy-3.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 16:49:45",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "wormhole-proxy"
}
JSON