Using Watcher With a Proxy

HTTP proxies allow an organization to audit data traversing the network. They are normally set up using environment variables. This document details how to set up proxy support in Watcher (version 4.0.0 or later).

Requirements

To use proxy support, you need proxy software running either locally or on your organization's servers. To use the proxy, you need the HTTPS endpoint and its certificate (to authorize it on your machine).

Configuration

The configuration of proxies for Watcher is entirely through environment variables. These are broken down into two groups.

The "standard" proxy environment variables:

• HTTPS_PROXY - The endpoint used for the HTTPS protocol to talk through
• HTTP_PROXY - The endpoint used for the HTTP protocol to talk through
• NO_PROXY - A comma-separated list of host names that shouldn't go through any proxy

The axe Watcher and Node.js environment variables:

• AXE_WATCHER_USE_ENV_PROXY - Target only Watcher to modify proxy support
• AXE_USE_ENV_PROXY - Target anything from the axe that also supports this variable to utilize a proxy
• NODE_USE_ENV_PROXY - Node.js's native (as of version 24 or later only) way to opt all network requests into using a proxy
• NODE_EXTRA_CA_CERTS - Node.js's native variable to provide trusted CA certificates for HTTPS connections

When any of the AXE_* variables are set to 1, proxy use is enabled. NODE_USE_ENV_PROXY was introduced in Node.js version 24 to enable this globally for the process, and it has been back-ported to Watcher to support it across all versions.

To enable the proxy for Node.js but disable it for Watcher, either of the AXE_* variables can be set to 0.

For HTTPS, the certificate authority certificate that is provided by your proxy should be specified with NODE_EXTRA_CA_CERTS, so it does not reject the connection as untrusted. This value is a path to the certificate file.

Usage Examples

There are two main ways to set up environment variables:

1. Set them up for the machine or CI job doing the processing. This makes them globally available throughout the machine's or job's lifespan.
2. Provide them before a command in the terminal so they only exist for that process's lifespan.

An example of setting proxy environment variables in a GitHub Action workflow file:

# Setup of the workflow and jobs
      - steps:
      - name: Run Tests
        env:
          HTTPS_PROXY: https://localhost:9090
          NODE_EXTRA_CA_CERTS: ~/path/to/ca.pem
          AXE_WATCHER_USE_ENV_PROXY: 1
        run: npm run test

Here is an example of using proxy environment variables locally for a single command to run:

AXE_WATCHER_USE_ENV_PROXY=1 HTTPS_PROXY=https://localhost:9090 NODE_EXTRA_CA_CERTS=~/path/to/ca.pem npm run test

Conditional Proxying on Node.js version 24 or Later

In Node.js version 24 (or later), NODE_USE_ENV_PROXY is enabled by default for all requests, so you may want to conditionally disable the proxy for Watcher in test scenarios.

This can be achieved by using NO_PROXY to instruct the system to allow the domain to bypass proxying. The following example allows the proxy to be used for all requests Node.js initiates but not use it for ones targeting axe.deque.com or example.com:

NODE_USE_ENV_PROXY=1 HTTPS_PROXY=https://our.intranet/proxy NO_PROXY=axe.deque.com,example.com npm run test

The reason to use NO_PROXY is that even if you try to disable axe Watcher's proxy use, it inherits the global request dispatcher, meaning that if NODE_USE_ENV_PROXY is enabled, it would still take precedence and use the proxy.