Configuring a Proxy

Configure proxy support either server wide or per integration

Proxy configuration is required if your Polarity server needs proxy access to reach the Internet and you are running integrations that rely on Internet based services or resources. Proxy support can be enabled for integrations either on a server-wide basis or a per-integration basis.

In general, integrations that will be connecting to internal resources do not need to have a proxy configured. Integrations that will be accessing Internet based APIs will need to have a proxy configured. If you are seeing an ECONNRESET error when using your integration, this is most commonly due to a missing or misconfigured proxy configuration for the integration.

Global Proxy

A global proxy will pass all integration traffic through the configured proxy. The proxy can be set via the HTTP_PROXY and HTTPS_PROXY environment variables. Specific domains or IPs can be set to ignore the proxy configuration via the NO_PROXY environment variable.

To set the required environment variables begin by opening the .env file found at /app/polarity-server/.env.

vi /app/polarity-server/.env

Add HTTP_PROXY and HTTPS_PROXY variables to the file. Ensure that the USERNAME:PASSWORD and proxy SERVER:PORT are replaced with your own proxy settings. If the proxy is unauthenticated then you do not need to provide the USERNAME:PASSWORD@ portion of the proxy configuration string (i.e., http://PROXYSERVER:PROXYPORT is all that would be required).

We’ve seen the most success with only specifying the HTTP_PROXY environment variable due to SSL certificate trust issues. If you set the proxy environment variables and still see ECONNRESET errors, try only specifying the HTTP_PROXY environment variable.

/app/polarity-server/.env

# We've seen cases where HTTPS_PROXY does not work. If you see a ECONNRESET
# then try just specifying the HTTP_PROXY environment variable. 
HTTP_PROXY=http://USERNAME:PASSWORD@PROXYSERVER:PROXYPORT
HTTPS_PROXY=https://USERNAME:PASSWORD@PROXYSERVER:PROXYPORT

# Any domains that match the pattern (* is a wildcard) will not use the
# proxy setting. You cannot wildcard IP addresses but you can specify
# specific IPs. If multiple domains or IP addreses are specified you should
# comma delimit them with no spaces 
NO_PROXY="*.domain.net,10.2.3.1"

The NO_PROXY variable is optional

After saving changes to the .env you must restart the polarity service for the changes to take effect.

systemctl restart polarityd

Integration Specific Proxies

To set the proxy on each individual integration and not system-wide, please follow the below steps. Ensure that the USERNAME:PASSWORD and the proxy SERVER:PORT are replaced with values for your own proxy.

Please note, if the proxy requires domain based authentication in the format of domain\username, the \ character needs to be encoded as %5C in the config.js file (see second example below).

To start, open the integration’s config.js file (replace <integration_name> with the directory name of the integration you are configuring).

1vi /app/polarity-server/integrations/<integration_name>/config/config.js

Within the config.js file find the property called proxy which will be located under the request property. The default is for the proxy property to be an empty string ''. Replace the empty string with the appropriate proxy string value:

config.js

// An HTTP proxy to be used. Supports proxy Auth with Basic Auth, identical to support for
// the url- parameter (by embedding the auth info in the uri)
proxy:'http://USERNAME:PASSWORD@PROXYSERVER:PROXYPORT',

Note that the proxy setting should be enclosed in single or double quotes and should have a trailing comma at the end.

Domain Based Authentication

If the proxy uses domain based authentication then the \ character should be encoded with %5C.

config.js

//Example of Domain based auth
proxy:'http://DOMAIN%5CUSERNAME:PASSWORD@PROXYSERVER:PROXYPORT',

or in the .env file it would look like this:

/app/polarity-server/.env

HTTP_PROXY=http://DOMAIN%5CUSERNAME:PASSWORD@PROXYSERVER:PROXYPORT

After modifying the proxy value, save the file and restart the integration from the Polarity Server Integration Settings page (you do not need to restart the server).

Testing the proxy using curl

If you need to confirm that you have the correct proxy information you can use the following curl command to test your proxy.

curl --verbose -x http://USERNAME:PASSWORD@PROXYSERVER:PROXYPORT https://cve.circl.lu/api/cve/CVE-2020-0796

If you run into any issues please don’t hesitate to contact us at [email protected]