Alpaca

Alpaca is a local HTTP proxy for command-line tools. It supports proxy auto-configuration (PAC) files and NTLM authentication.

Install using Homebrew

If you're using macOS and use Homebrew, you can install using:

$ brew tap samuong/alpaca
$ brew install samuong/alpaca/alpaca

Launch Alpaca by running alpaca, or by using brew services start alpaca.

Install using Go

If you've got the Go tool installed, you can install using:

$ go install github.com/samuong/alpaca/v2@latest

Download Binary

Alpaca can be downloaded from the GitHub releases page.

Install from distribution packages

Usage

Start Alpaca by running the alpaca binary.

If the proxy server requires valid authentication credentials, you can provide them by means of:

• the shell prompt, if -d is passed,
• the shell environment, if NTLM_CREDENTIALS is set,
• the system keyring (macOS, Windows and Linux/GNOME supported), if none of the above applies.

Otherwise, the authentication with proxy will be simply ignored.

Shell Prompt

You can also supply your domain and username (via command-line flags) and a password (via a prompt):

$ alpaca -d MYDOMAIN -u me
Password (for MYDOMAIN\me):

Non-interactive launch

If you want to use Alpaca without any interactive password prompt, you can store your NTLM credentials (domain, username and MD4-hashed password) in an environment variable called $NTLM_CREDENTIALS. You can use the -H flag to generate this value:

$ ./alpaca -d MYDOMAIN -u me -H
# Add this to your ~/.profile (or equivalent) and restart your shell
NTLM_CREDENTIALS="me@MYDOMAIN:823893adfad2cda6e1a414f3ebdf58f7"; export NTLM_CREDENTIALS

Note that this hash is not cryptographically secure; it's just meant to stop people from being able to read your password with a quick glance.

Once you've set this environment variable, you can start Alpaca by running ./alpaca.

Keyring

On macOS, if you use NoMAD and have configured it to use the keychain, Alpaca will use these credentials to authenticate to any NTLM challenge from your proxies.

On Windows and Linux/GNOME you will need some extra work to persist the username (NTLM_USERNAME) and the domain (NTLM_DOMAIN) in the shell environoment, while the password in the system keyring. Alpaca will read the password from the system keyring (in the login collection) using the attributes service=alpaca and username=$NTLM_USERNAME.

To store the password in the GNOME keyring, do the following:

$ export NTLM_USERNAME=<your-username-here>
$ export NTLM_DOMAIN=<your-domain-here>
$ sudo apt install libsecret-tools
$ secret-tool store -c login -l "NTLM credentials" "service" "alpaca" "username" $NTLM_USERNAME
Password:
# Type your password, then run
$ alpaca

On macOS and Linux/GNOME systems, Alpaca uses the PAC URL from your system settings. If you'd like to override this, or if Alpaca fails to detect your settings, you can set this manually using the -C flag.

---

Proxy

You also need to configure your tools to send requests via Alpaca. Usually this will require setting the http_proxy and https_proxy environment variables:

$ export http_proxy=http://localhost:3128
$ export https_proxy=http://localhost:3128
$ curl -s https://raw.githubusercontent.com/samuong/alpaca/master/README.md
# Alpaca
...

When moving from, say, a corporate network to a public WiFi network (or vice-versa), the proxies listed in the PAC script might become unreachable. When this happens, Alpaca will temporarily bypass the parent proxy and send requests directly, so there's no need to manually unset/re-set http_proxy and https_proxy as you move between networks.