dumbproxy

Simple, scriptable, secure HTTP/SOCKS5 forward proxy.

Features

• Multiple protocol support: both HTTP and SOCKS5 are supported
  • TrustTunnel extensions for UDP and healthchecks are supported as well, which means dumbproxy server running with HTTPS enabled is compatible with TrustTunnel client.
• Cross-platform (Windows/Mac OS/Linux/Android (via shell)/*BSD)
• Deployment with a single self-contained binary
• Zero-configuration
• Seamless forwarding of all kinds of TCP connections in addition to regular web-traffic forwarding
• Supports Basic proxy authentication
  • Via auto-reloaded NCSA httpd-style passwords file
  • Via static login and password
  • Via HMAC signatures provisioned by central authority (e.g. some webservice)
  • Via Redis or Redis Cluster database
  • Chaining of all above in order to lookup multiple sources or provide custom rejection response.
• Supports TLS operation mode (HTTP(S) proxy over TLS)
  • Supports client authentication with client TLS certificates
  • Native ACME support (can issue TLS certificates automatically using Let's Encrypt or BuyPass)
    • Certificate cache in local directory
    • Certificate cache in Redis/Redis Cluster
    • Optional local in-memory inner cache
    • Optional AEAD encryption layer for cache
• Per-user bandwidth limits
• HTTP/2 support, both server and client, including h2c support
• Advanced DNS support
  • Plain DNS
  • DNS-over-HTTPS
  • DNS-over-TLS
  • System-provided DNS
  • Competitive parallel resolving using any of above
  • Optional DNS cache
• Resilient to DPI (including active probing, see hidden_domain option for authentication providers)
• Connecting via upstream HTTP(S)/SOCKS5 proxies (proxy chaining)
  • Optional parroting of TLS fingerprints of popular software such as web browsers.
  • Optional countermeasures against TLS-in-TLS detection (available when both client and server are dumbproxy).
• systemd socket activation
• Proxy protocol support for instances working behind a reverse proxy (HAProxy, Nginx)
• Scripting with JavaScript:
  • Access filter by JS function
  • Upstream proxy selection by JS function
• Seamless proxy client integration with OpenSSH: ssh -o ProxyCommand="dumbproxy -config proxy.cfg -mode stdio %h %p" root@server1
• Port-forwarding mode

Installation

Binary download

Pre-built binaries available on releases page.

From source

Alternatively, you may install dumbproxy from source. Run within source directory

go install .

Docker

Docker image is available as well. Here is an example for running proxy as a background service:

docker run -d \
    --security-opt no-new-privileges \
    -p 8080:8080 \
    --restart unless-stopped \
    --name dumbproxy \
    ghcr.io/senseunit/dumbproxy -auth 'static://?username=admin&password=123456'

Snap Store

sudo snap install dumbproxy

easy-dp

There is a simple shell script available for complete installation of dumbproxy on a fresh Linux server: https://github.com/Snawoot/easy-dp

Usage

Just run program and it'll start accepting connections on port 8080 (default).

Example: plain proxy

Run proxy on port 1234 with Basic authentication with username admin and password 123456:

dumbproxy -bind-address :1234 -auth 'static://?username=admin&password=123456'

Example: HTTP proxy over TLS (LetsEncrypt automatic certs)

Run HTTPS proxy (HTTP proxy over TLS) with automatic certs from LetsEncrypt on port 443 with Basic authentication with username admin and password 123456:

dumbproxy -bind-address :443 -auth 'static://?username=admin&password=123456' -autocert

Example: HTTP proxy over TLS (pre-issued cert) behind Nginx reverse proxy performing SNI routing

Run HTTPS proxy (HTTP proxy over TLS) with pre-issued cert listening proxy protocol on localhost's 10443 with Basic authentication (users and passwords in /etc/dumbproxy.htpasswd)):

dumbproxy \
	-bind-address 127.0.0.1:10443 \
	-proxyproto \
	-auth basicfile://?path=/etc/dumbproxy.htpasswd \
	-cert=/etc/letsencrypt/live/proxy.example.com/fullchain.pem \
	-key=/etc/letsencrypt/live/proxy.example.com/privkey.pem

Nginx config snippet:

stream
{
	ssl_preread on;

	map $ssl_preread_server_name $backend
	{
		proxy.example.com dumbproxy;
		...
	}

	upstream dumbproxy
	{
		server 127.0.0.1:10443;
	}

	server
	{
		listen 443;
		listen [::]:443;
		proxy_protocol on;
		proxy_pass $backend;
	}

}

Example: HTTP proxy over TLS (ACME-issued cert) behind Traefik reverse proxy running in Docker Compose and performing SNI routing

Have following labels attached to dumbproxy service in compose file:

        traefik.enable: "true"
        traefik.tcp.routers.dumbproxy.service: dumbproxy
        traefik.tcp.routers.dumbproxy.rule: HostSNI(`<your-domain>`)
        traefik.tcp.routers.dumbproxy.tls: "true"
        traefik.tcp.routers.dumbproxy.tls.passthrough: "false"
        traefik.tcp.routers.dumbproxy.tls.certResolver: letsencrypt
        traefik.tcp.services.dumbproxy.loadBalancer.server.port: 8080
        traefik.tcp.services.dumbproxy.loadbalancer.proxyProtocol.version: 2

dumbproxy service should be run in plaintext mode as TLS is handled on Traefik side. So options would be just -bind-address=:8080 -proxyproto and probably something for authorization. This recipe is explained in Wiki with more details and configuration files provided for context.

Example: HTTP proxy over TLS (BuyPass automatic certs)

Run HTTPS proxy (HTTP proxy over TLS) with automatic certs from BuyPass on port 443 with Basic authentication with username admin and password 123456:

dumbproxy \
	-bind-address :443 \
	-auth 'static://?username=admin&password=123456' \
	-autocert \
	-autocert-acme 'https://api.buypass.com/acme/directory' \
	-autocert-email YOUR-EMAIL@EXAMPLE.ORG \
	-autocert-http :80

See Wiki for more examples, recipes and notes.

Using HTTP-over-TLS proxy

It's quite trivial to set up program which supports proxies to use dumbproxy in plain HTTP mode. However, using HTTP proxy over TLS connection with browsers is little bit tricky. Note that TLS must be enabled (-cert and -key options or -autocert option) for this to work.

Routing all browsers on Windows via HTTPS proxy

Open proxy settings in system's network settings:

Turn on setup script option and set script address:

data:,function FindProxyForURL(u, h){return "HTTPS example.com:8080";}

where instead of example.com:8080 you should use actual address of your HTTPS proxy.

Note: this method will not work with MS Edge Legacy.

Using with Firefox

Option 1. Inline PAC file in settings.

Open Firefox proxy settings, switch proxy mode to "Automatic proxy configuration URL". Specify URL:

data:,function FindProxyForURL(u, h){return "HTTPS example.com:8080";}

Option 2. Browser extension.

Use any proxy switching browser extension which supports HTTPS proxies like this one.

Using with Chrome

Option 1. CLI option.

Specify proxy via command line:

chromium-browser --proxy-server='https://example.com:8080'

Option 2. Browser extension.

Use any proxy switching browser extension which supports HTTPS proxies like this one.

Using with other applications

It is possible to expose remote HTTPS proxy as a local plaintext HTTP proxy with the help of some application which performs remote communication via TLS and exposes local plaintext socket. dumbproxy itself can play this role and use upstream proxy to provide local proxy service. For example, command

dumbproxy -bind-address 127.0.0.1:8080 -proxy 'https://login:password@example.org'

would expose remote HTTPS proxy at example.org:443 with login and password on local port 8080 as a regular HTTP proxy without authentication. Or, if you prefer mTLS authentication, it would be

dumbproxy -bind-address 127.0.0.1:8080 -proxy 'https://example.org?cert=cert.pem&key=key.pem&cafile=ca.pem'

Using with Android

1. Run proxy as in examples above.

2. Install DumDum on your Android device from F-Droid or GitHub.

3. Open DumDum, tap ➕ (in the upper right corner) and choose "HTTP(S)".

4. Configure a connection:

   <img width="335" height="450" alt="dumdum" src="https://github.com/user-attachments/assets/c7ae85ca-61eb-4167-965b-6245a411eaf7" />

[!IMPORTANT] For HTTPS, make sure the "Encryption" parameter is set to "tls".

5. Save settings by tapping ✔️.
6. If a self-signed certificate is used, go to "Settings > Advanced > Connection" and enable "Ignore Proxy SSL Certificate."
7. Enjoy!

Authentication

Authentication parameters are passed as URI via -auth parameter. Scheme of URI defines authentication metnod and query parameters define parameter values for authentication provider.

• none - no authentication. Ex