Digest Proxy Bridge for Linux

A lightweight, zero-dependency Python proxy bridge designed to handle HTTP Digest Authentication for upstream corporate or ISP proxies.

This tool is specifically built for Linux users (Ubuntu 24.04+) working behind restricted proxies where standard tools like apt, git, curl, and Homebrew fail due to lack of native Digest handshake support or issues with HTTPS tunneling.

Why this exists

Many corporate proxies use the Digest Authentication protocol, which requires a complex "challenge-response" handshake. While browsers handle this well, command-line tools often:

1. Fail to perform the handshake (resulting in 407 Proxy Authentication Required).
2. Fail to tunnel HTTPS traffic (the CONNECT method).
3. Corrupt binary data (like .deb packages) if they try to decode the stream as text.

This script acts as a local "clear" bridge that handles the authentication and tunneling transparently.

0. Prerequisites

• Python 3 (any version ≥ 3.6) — no third-party packages required.
• Your upstream proxy address, port, username, and password.

1. Configuration

Credentials are never hardcoded in proxy.py. Instead, choose one of the three methods below. Values from a higher-priority source override lower ones.

Priority	Method	Best for
1 (lowest)	Config file proxy.conf	Everyday persistent use
2	Environment variables	CI, containers, or scripted setups
3 (highest)	CLI arguments	Quick one-off overrides

Method 1 — Config file (recommended)

cp proxy.conf.example proxy.conf
nano proxy.conf          # fill in your real values

proxy.conf is listed in .gitignore and will never be committed. The file uses a simple INI format:

[proxy]
upstream_host = your.proxy.server
upstream_port = 8080
username      = your_username
password      = your_password

# optional — defaults shown
listen_host = 127.0.0.1
listen_port = 3128

You can also keep the file elsewhere and point to it at runtime:

python3 proxy.py --config /path/to/my.conf

Method 2 — Environment variables

export PROXY_HOST=your.proxy.server
export PROXY_PORT=8080
export PROXY_USER=your_username
export PROXY_PASSWORD=your_password
# optional
export LISTEN_HOST=127.0.0.1
export LISTEN_PORT=3128

Method 3 — CLI arguments

python3 proxy.py --host your.proxy.server --port 8080 \
                 --username your_username --password your_password

Run python3 proxy.py --help to see all available options.

---

2. Usage Instructions

A. Run the Bridge

Open a dedicated terminal window and run the script. It must remain open while you use other tools.

python3 proxy.py

B. Configure APT (Ubuntu Updates)

Create a persistent configuration for apt:

1. Edit/Create: sudo nano /etc/apt/apt.conf.d/95proxies
2. Paste:

   Acquire::http::Proxy "http://127.0.0.1:3128/";
   Acquire::https::Proxy "http://127.0.0.1:3128/";
   

3. Fixing "Hash Sum Mismatch" errors: If you previously had failed downloads, clear the cache:

   sudo apt-get clean
   sudo rm -rf /var/lib/apt/lists/*
   sudo apt-get update

C. Configure Git

git config --global http.proxy http://127.0.0.1:3128
git config --global https.proxy http://127.0.0.1:3128

D. Configure Curl

echo 'proxy = "http://127.0.0.1:3128"' >> ~/.curlrc

E. Homebrew (Linuxbrew)

Homebrew requires specific environment variables during installation and usage:

export HOMEBREW_HTTP_PROXY=http://127.0.0.1:3128
export HOMEBREW_HTTPS_PROXY=http://127.0.0.1:3128

---

3. Persistent Shell Configuration (Bash & Zsh)

To ensure the proxy is active automatically in every new terminal, add the following block to your shell profile.

For Bash: nano ~/.bashrc
For Zsh: nano ~/.zshrc

# Digest Proxy Bridge Environment Variables
export http_proxy="http://127.0.0.1:3128"
export https_proxy="http://127.0.0.1:3128"
export all_proxy="http://127.0.0.1:3128"
export no_proxy="localhost,127.0.0.1"

# Homebrew specific
export HOMEBREW_HTTP_PROXY=$http_proxy
export HOMEBREW_HTTPS_PROXY=$https_proxy

Apply the changes immediately:

• Bash: source ~/.bashrc
• Zsh: source ~/.zshrc

---

Contributing

Bug reports and pull requests are welcome! Please open an issue on GitHub before submitting larger changes so we can discuss the approach.

---

License

This project is released under the MIT License.

---

Troubleshooting

Issue	Solution
Error: missing required configuration	Copy proxy.conf.example to proxy.conf and fill in your values, or use --host/--username/--password CLI flags.
Error 407	Verify credentials in proxy.conf (or env vars) and ensure the script is running.
Hash Sum Mismatch	Ensure you are using the latest Binary-Safe version of this script. Run sudo apt-get clean to clear bad cache.
Couldn't connect to server	Ensure no other service (like cntlm) is already using port 3128. Check with ss -tulpn | grep 3128.