Introduction to Proxydetox

A small proxy to relieve the pain of some corporate proxies.

Proxydetox can act as an intermediate HTTP proxy for your local applications and actual HTTP proxy. Proxydtox will talk to the actual corporate HTTP proxies on behalf of the actual application. Proxydetox will select the correct upstream proxy based on the Proxy Auto-Configuration (PAC) file provided by the network administrator and will take care to correctly authenticate against the upstream proxy.

With Proxydetox in place, most local applications can be configured to use the proxy by setting the environment variables http_proxy, and https_proxy.

The following authentication methods are supported:

• Basic: use the username and password from ~/.netrc.
• Negotiate^1,2: on Linux and macOS it will use GSSAPI, on Windows SSPI will be used.

Proxydetox supports the following systems:

• POSIX-compliant systems (tested on Ubuntu and OpenBSD)
• macOS
• Windows

Pre build versions of Proxydetox can be found on the releases page. Installation instructions are provided in the installation section.

¹⁾ Can be disabled via the --no-default-features flag during build time.
²⁾ Can be activated with the --negotiate flag during runtime.

License

This source code is under the MIT license with the exceptions mentioned in "Third party source code in this repository".

Install Proxydetox

The easiest is, to use the download and install a pre-build package from the releases page.

Pre build binaries are available for the following platforms:

• Linux
• macOS
• Windows

Linux

1. Download the proxydetox-*-x86_64-linux.deb Debian package.
2. Install using the dpkg command from on Debian based platforms:

   sudo dpkg --install proxydetox-*-x86_64-linux.deb
   

Register Proxydetox as systemd user daemon

The Debian package comes with systemd service file.

Enabling Proxydetox and starting it, can be done with the following commands:

systemctl --user daemon-reload
systemctl --user enable proxydetox
systemctl --user start proxydetox

To disable and stop it please use:

systemctl --user stop proxydetox
systemctl --user disable proxydetox

macOS

1. Download the proxydetox-*-x86_64-apple-darwin.pkg package.
2. Install using the installer command from macOS:

   sudo installer -package proxydetox-*-x86_64-apple-darwin.pkg -target /
   

Register proxydetox as LaunchAgent

The above steps installed a LaunchAgent for proxydetox named /Library/LaunchAgents/cc.colorto.proxydetox.plist.

Info: Since the installer command is run as the root user (to be able to write the files to the system directories) it cannot know for which user the launch agent needs to be enabled.

The following steps need to be executed as the user who wants to use proxydetox (i.e. not as root).

  launchctl bootstrap "gui/$(id -u)" "/Library/LaunchAgents/cc.colorto.proxydetox.plist"
  launchctl enable "gui/$(id -u)/cc.colorto.proxydetox"
  launchctl print "gui/$(id -u)/cc.colorto.proxydetox"
  launchctl kickstart -kp "gui/$(id -u)/cc.colorto.proxydetox"

To revert the above changes (i.e. you want to uninstall proxydetox), run the following commands:

  launchctl kill SIGTERM "gui/$(id -u)/cc.colorto.proxydetox"
  launchctl disable "gui/$(id -u)/cc.colorto.proxydetox"
  launchctl bootout "gui/$(id -u)/cc.colorto.proxydetox"

Windows

1. Download the proxydetox-win64.zip zip file.
2. Unzip the archive.
3. Run the included install.bat file.

From sources

To build Proxydetox from sources, please refer the Build Proxydetox section.

Configuration

File locations

The following files are read during startup by Proxydetox. These files can be used to tweak the behaviour of Proxydetox.

• proxydetoxrc: Main configuration file.
• proxy.pac: The PAC file, which defines the rules to select the correct upstream proxy.
• .netrc: Contains the authentication information when --negotiate is not used.

The configuration files are searched at the following locations:

The .netrc file is expected to be located in the HOME directory on all platforms. If needed, the location can be specified via the --netrc-file flag when invoking Proxydetox.

The configuration files proxydetoxrc and proxy.pac are searched at user configurable location and system wide locations.

For the different platforms, the user configurable location is as follows:

• ~/.config/proxydetox/ (POSIX-compliant systems like BSD and Linux)
• ~/Library/Application\ Support/proxydetox (macOS)
• %APPDATA% (Windows)

For the different platforms, the user system wide location is as follows:

POSIX-compliant systems like BSD, macOS, and Linux:

• /usr/etc/proxydetox
• /usr/local/etc/proxydetox/
• /opt/proxydetox/etc/

Windows:

• . (the directory of the executable)

proxydetoxrc file format

The proxydetoxrc file lists all options which are usually provided via the command line to proxydetox.

Example

proxydetox --negotiate --listen 127.0.0.1:8080 --pac-file http://example.org/proxy.pac

Is equivalent with a proxydetoxrc file at one of the well known locations listed above with the following content:

--negotiate
--listen 127.0.0.1:8080
--pac-file http://example.org/proxy.pac

Negotiate authentication

To enable the Negotiate authentication the --negotiate flag must be added when calling proxydetox or added to the proxydetoxrc configuration file.

Basic authentication

When the basic authentication shall be used (default), the credentials are read from the ~/.netrc file. An example ~/.netrc file will look as follows:

machine proxy.example.org
login ProxyUsername
password ProxyPassword

The basic authentication is insecure, since it required to store the password in clear text on disk and the password is transferred unencrypted.

Proxy Auto-Configuration (PAC) file

A copy of the PAC file proxy.pac must be places in on of directories searched by Proxydetox or specified via the --pac-file option. The PAC file can be also a HTTP URL. The content will then be downloaded from the given location.

The PAC file is usually maintained by the network administrators. The path (usually some http location in the intranet) can be retrieved from the settings of the pre-configured internet browser.

Examples

proxydetox --pac-file http://example.org/proxy.pac

proxydetox --pac-file /tmp/test.pac

Configuration options

The full list of configuration options can be retrieved with:

proxydetox --help

Usage

With Proxydetox running, it is enough for most tools to set the http_proxy and https_proxy environment variables.

http_proxy=http://127.0.0.1:3128
https_proxy=http://127.0.0.1:3128
no_proxy=127.0.0.1,localhost,::1
export http_proxy https_proxy no_proxy

To make this changes persistent add them to ~/.profile, ~/.bashrc, or ~/.zshrc depending on which shell you are using.

Building Proxydetox

Proxydetox can be build using cargo or Bazel. The macOS application can only build via Bazel.

• Build using cargo
• Build using bazel

Using cargo

The easiest is, to use cargo from rustup. The next command will install the proxydetox binary in ~/.cargo/bin.

cargo install --git https://github.com/kiron1/proxydetox.git

If you have cloned this repository already, you can also do:

cargo install --path .

Enable build features

To enable the Negotiate authentication method, the negotiate feature must be enabled. This means, we would need to add --features negotiate to the above cargo install ... command.

On GNU/Linux and macOS the Generic Security Services Application Program Interface (GSSAPI) will be used. On Windows the Security Support Provider Interface is used .

Using Bazel

The easiest way to obtain Bazel, is by using Bazelisk. The remaining document assumes that either Bazel is installed and available via the PATH variable or Bazelisk is installed and the binary is named bazel and available via the PATH variable.

For the Bazel setup to work, ensue the XCode command line tools are installed:

xcode-select --install

Building ProxydetoxApp (macOS UI)

bazel build //macos/app:ProxydetoxApp

Enable build features

Append --features=negotiate to bazel build to enable the negotiate feature:

bazel build --features=negotiate //...

Autostart

To start Proxydetox automatically when a user is logged in, please see the Autostart section.

Proxydetox as user service

Register Proxydetox as a user service such that it is automatically started by the system when the user is logged in.

Note: This steps are only required when using cargo install. When installing the provided packages this steps are not necessary.

Automatically start Proxydetox with a user session

To automatically start proxydetox when an user session is active, we can register it with systemd(8) on Linux or launchd(8) on macOS.

Linux

Create a file ~/.config/systemd/user/proxydetox.service, you can use debian/proxydetox.service as template, but make sure to update the ExecStart part with an absolute path.

To finally enable the service, us the following commands:

systemctl --user daemon-reload
systemctl --user enable proxydetox.service
systemctl --user start proxydetox.service

macOS

Create a file ~/Library/LaunchAgents/cc.colorto.proxydetox.plist, you can use cc.colorto.proxydetox.plist as template, but make sure to update the ProgramArguments value with an absolute path.

The following steps need to be executed as the user who wants to use proxydetox (i.e. not as root).

  launchctl bootstrap "gui/$(id -u)" "/Library/LaunchAgents/cc.colorto.proxydetox.plist"
  launchctl enable "gui/$(id -u)/cc.colorto.proxydetox"
  launchctl print "gui/$(id -u)/cc.colorto.proxydetox"
  launchctl kickstart -kp "gui/$(id -u)/cc.colorto.proxydetox"

To revert the above changes (i.e. you want to uninstall proxydetox), run the following commands:

  launchctl kill SIGTERM "gui/$(id -u)/cc.colorto.proxydetox"
  launchctl disable "gui/$(id -u)/cc.colorto.proxydetox"
  launchctl bootout "gui/$(id -u)/cc.colorto.proxydetox"

Rust Toolchain

rustup target add x86_64-pc-windows-gnu
rustup toolchain install stable-x86_64-pc-windows-gnu

C Toolchain

We can use pkgsrc to install the the mingw GNU cross compiler:

sudo pkgin install mingw-w64-x86_64-gcc mingw-w64-x86_64-winpthreads-8.0.0

Cargo configuration

File ~/.cargo/config.toml:

[target.x86_64-pc-windows-gnu]
linker = "/opt/pkg/cross/x86_64-w64-mingw32/bin/x86_64-w64-mingw32-gcc"
rustc-link-search = ["/opt/pkg/cross/x86_64-w64-mingw32-winpthreads/mingw//lib/"]

Cross compile

export RUSTFLAGS="-L /opt/pkg/cross/x86_64-w64-mingw32-winpthreads/mingw/lib"
cargo build --target x86_64-pc-windows-gnu

Reference

• https://doc.rust-lang.org/cargo/reference/config.html
• https://doc.rust-lang.org/cargo/reference/config.html#targettriplelinker

For Developers

Components in this repository

Evaluation of PAC scripts

• paclib - Functions needed to implement FindProxyForURL and wrap it in Rust.
• paceval - A utility to evaluate PAC files for a given URL and print the result.

HTTP Proxy code

• proxy_client - Supporting code to allow hyper to utilize HTTP proxies.
• proxydetox - The actual Proxydetox software.

Third party source code in this repository

• pac_utils.js is extracted from Mozillas ProxyAutoConfig.cpp and is under the MPL2 license.

Alternative solutions

• Squid: using the cache_peer directive and translating the given PAC file into Squid ACLs.
• SpechtLite: and translating the PAC file into the SpechtLite YAML configuration format (unmaintained).
• Px: A HTTP proxy server to automatically authenticate through an NTLM proxy (can handle PAC files). Written in Python and focus more on Windows machines.
• Cntlm: a NTLM / NTLMv2 authenticating HTTP/1.1 proxy. Cannot handle PAC files (unmaintained).