proxy-pac-proxy

 Forwarding proxy with support for upstream proxy.pac resolution and BASIC authentication.

Forwarding proxy with support for upstream proxy.pac resolution and BASIC authentication

Software development in network environments where Internet access is forced through dynamically configured HTTP proxies is a pain. The simple use of common package managers such as npm, pip, gem or docker -- perhaps in combination with services and repositories on the local network -- requires reverse engineering of a proxy.pac file and the configuration of arbitrarily complicated combinations of the usual *_PROXY environment variables. Worse, if the proxy requires authentication, passwords will quickly spread across environment variables, *_history files and whatnot.

Proxy-pac-proxy tries to alleviate at least some of that pain.

• Installation
• Quick Start
• Retrieving the proxy.pac URL
• Usage
  • proxy-pac-proxy start
  • proxy-pac-proxy stop
  • proxy-pac-proxy env
• Limitations

Installation

Note: proxy-pac-proxy requires at least Node v7.6.0

Note2: installation requires access to the public npmjs.com repository. That is straightforward when connected to a public network, but may be tricky in those network environments where proxy-pac-proxy is needed. In the latter case, npm can be instructed to access the Internet through a previously discovered HTTP proxy by using the --https-proxy option. This is needed only at installation time; afterwards proxy-pac-proxy can take care of the problem

To install proxy-pac-proxy on your system run:

$ npm install -g proxy-pac-proxy

Quick Start

Export the proxy.pac URL (optional, but if the environment variable is not set, the URL will need to be provided on the command line with the -u option):

$ export PROXYPACPROXY_URL=http://intranet.mycompany.com/proxy.pac

Start the forwarding proxy server with authentication:

$ proxy-pac-proxy start -A
Username: joedoe
Password for joedoe: [hidden]
Proxy succesfully started.
You may configure your shell by running the `proxy-pac-proxy env` command.

From this point on, in any shell it will be possible to automatically configure all the appropriate *_PROXY environment variables for steering traffic through the new forwarding proxy:

$ eval $(proxy-pac-proxy env)

Test:

$ curl -v http://example.com
* Rebuilt URL to: http://example.com/
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to (nil) (127.0.0.1) port 8079 (#0)
> GET http://example.com/ HTTP/1.1
> Host: example.com
> User-Agent: curl/7.52.1
> Accept: */*
> Proxy-Connection: Keep-Alive
> 
< HTTP/1.1 200 OK
< date: Sat, 30 Sep 2017 09:16:36 GMT
< etag: "359670651+ident"
< vary: Accept-Encoding
< server: ECS (dca/24D1)
< expires: Sat, 07 Oct 2017 09:16:36 GMT
< x-cache: HIT, HIT from 10.29.176.45
< content-type: text/html
< cache-control: max-age=604800
< last-modified: Fri, 09 Aug 2013 23:54:35 GMT
< content-length: 1270
< proxy-connection: Keep-Alive
< Connection: keep-alive
< ...

Retrieving the proxy.pac URL

The proxy.pac URL is often configured automatically, in ways that depend on the operating system and the IT/network administration policies (e.g. autodiscovery, remote admin...). One simple cross-platform way to retrieve the URL is on the chrome://net-internals tab in Chrome:

Usage

proxy-pac-proxy start

Start a local instance of a forwarding proxy that can be controlled through the stop and env commands.

$ proxy-pac-proxy start --help
proxy-pac-proxy start [options]

Options:
  --url, -u               The proxy.pac URL                 [string] [required]
  --address, -a           The local address the proxy will bind to
                                                [string] [default: "127.0.0.1"]
  --port, -p              The local port the proxy will bind to
                                                       [number] [default: 8079]
  --authenticate, -A      Prompt for username and password for proxy
                          authentication             [boolean] [default: false]
  --username, --user, -U  The username for proxy authentication        [string]
  --password, --pass, -P  The password for proxy authentication        [string]
  --foreground, -f        Run in foreground          [boolean] [default: false]
  -h, --help              Show help                                   [boolean]
  -v, --version           Show version number                         [boolean]

proxy-pac-proxy stop

Stop the local forwarding proxy instance.

$ proxy-pac-proxy stop --help
proxy-pac-proxy stop [options]

Options:

  --address, -a           The local address the proxy is bound to
                                                [string] [default: "127.0.0.1"]
  --port, -p              The local port the proxy is bound to
                                                       [number] [default: 8079]
  -h, --help              Show help                                   [boolean]
  -v, --version           Show version number                         [boolean]

proxy-pac-proxy env

Display the commands to configure the shell environment.

$ proxy-pac-proxy env --help
proxy-pac-proxy env [options]

Options:
  --address, -a           The local address the proxy is bound to
                                                [string] [default: "127.0.0.1"]
  --port, -p              The local port the proxy is bound to
                                                       [number] [default: 8079]
  --reset, -r             Display commands to reset the environment
                                                     [boolean] [default: false]
  -h, --help              Show help                                   [boolean]
  -v, --version           Show version number                         [boolean]

Limitations

• Only supports BASIC Authentication

• Only slightly more secure than storing credentials in environment variables. With BASIC authentication Base64-encoded passwords are transmitted in clear

  • Do not use authentication unless you totally trust the local network administrator; if that's not the case, then leave authentication unset (i.e. don't use -A or -U options) and rely on application-based authentication

• The env command only displays commands for bash. Commands for other shells can be easily derived, but at this point that's a job that must be done manually

  from https://github.com/emarock/proxy-pac-proxy