You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 4-6.RSVP
Socket
Book a DemoInstallSign in
Socket

wormhole-proxy

Package Overview
Dependencies
Maintainers
1
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

wormhole-proxy

Asynchronous I/O HTTP and HTTPS Proxy on Python >= 3.11

3.3.6
pipPyPI
Maintainers
1

Wormhole

PyPI Version Quay.io Build Status

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 (optional for Linux and macOS)
  • winloop (optional for Windows)

How to install

Stable Version

Please install the stable version using pip command:

$ pip install wormhole-proxy

Development Snapshot

You can install the development snapshot from the main branch on GitHub using the following command:

$ pip install git+https://github.com/cwt/wormhole.git@main

You can also install the development snapshot using pip with mercurial:

$ pip install hg+https://hg.sr.ht/~cwt/wormhole

Or install from your local clone:

$ 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:

$ pip install https://hg.sr.ht/~cwt/wormhole/archive/tip.tar.gz

How to use

  • Run wormhole command

    $ wormhole
    
  • Set browser's proxy setting to

    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:

    $ wormhole --auth-add wormhole.passwd <username>
    
  • To change an existing user's password:

    $ wormhole --auth-mod wormhole.passwd <username>
    
  • To delete a user:

    $ wormhole --auth-del wormhole.passwd <username>
    
  • To run the proxy with authentication enabled:

    $ wormhole --auth wormhole.passwd
    

Ad-Blocker Usage

  • Update the ad-block database:

    $ wormhole --update-ad-block-db ads.sqlite3
    
  • Run Wormhole with the ad-blocker enabled:

    $ wormhole --ad-block-db ads.sqlite3
    

Command help

$ 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.

1. Pull the image

Pull the desired version tag from Quay.io.

# 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:

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.

mkdir -p /path/to/config  # change this to your desired path

Then, run the following command to create the ad-block database file:

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.

# 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.

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.

# 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.

# 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 on GitHub.

Keywords

wormhole

FAQs

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts