Proxy Configuration

Insight Agent versions 2.3 and later are proxy-aware and comply with proxy routing definitions for the purpose of communicating with the Insight platform at https://endpoint.ingress.rapid7.com:443 and its various subdomains. The agent follows the highest priority proxy definition found, whether configured at the operating system level or in the file structure of the agent, according to an obedience hierarchy.

Requirements

The Insight Agent can only communicate through proxies that meet the following protocol requirements and authentication schemes.

Supported HTTPS Proxies

Your proxy must support the Request For Comments (RFC) 2817 standard, which specifies the HTTP CONNECT verb.

Authentication Schemes

Currently, only BASIC authentication is supported.

Agent Behavior With Proxies

If an HTTPS proxy is detected, the Insight Agent adds it as an additional communication route. Existing routes to any deployed Collectors or standard direct communication routes to the Insight platform are not removed in the process. Although the agent automatically determines the most efficient route through a calculated efficiency metric, proxy routes are always used if they can reach the Insight platform at the time of transmission.

Priority 1: proxy.config File

You can automatically configure the proxy.config file during a command line installation of the Insight Agent or manually after the agent has been installed.

To configure the proxy.config file at install time with the command line:

1. Download the Insight Agent installer for the operating system of your choice.
2. Open a command line interface or terminal.
3. Run one of the following installation or post-installation commands according to your endpoint operating system and include the proxy argument as shown (10.1.2.3:8443 appears here as an example IP address and port combination). For Windows, substitute <installerType> with x86_64 for most Windows architectures or arm64 for Windows ARM64.

• Windows - msiexec /i agentInstaller-<installerType>.msi HTTPSPROXY=10.1.2.3:8443
• Linux - sudo ./configure_agent.sh --https-proxy=10.1.2.3:8443
• Mac - sudo ./configure_agent.sh --https-proxy=10.1.2.3:8443

If you want to configure proxy.config during a token-based agent installation, make sure your install command also contains the following token and region attributes. In the command, specify this information where indicated:

• <target-directory-for-dependencies> - Specify your custom path.
• <regionalID:UUID> - Specify your custom token.
• <installerType> (Windows only) - Specify x86_64 for most Windows architectures or arm64 for Windows ARM64.

Windows - msiexec /i agentInstaller-<installerType>.msi CUSTOMTOKEN=<regionalID>:<UUID> HTTPSPROXY=10.1.2.3:8443

Linux - sudo ./configure_agent.sh --token=<regionalID>:<UUID> --https-proxy=10.1.2.3:8443

Mac - sudo ./configure_agent.sh --token=<regionalID>:<UUID> --https-proxy=10.1.2.3:8443

Alternatively, you can configure proxy awareness on individual agents that you have already installed by manually creating the proxy.config file in the agent installation directory.

To manually create and configure the proxy.config file:

1. Browse to the following folder in your agent installation directory according to your operating system:
   • Linux - /opt/rapid7/ir_agent/components/bootstrap/common/
   • Windows - C:\Program Files\Rapid7\Insight Agent\components\bootstrap\common\
   • Mac - /opt/rapid7/ir_agent/components/bootstrap/common/
2. Create a new file named proxy.config.
   • .config is the necessary file extension.
3. Open proxy.config in a text editor and define your proxy address according to this example syntax:

json
1
{ "https": "10.1.2.3:8443" }

This JSON string stipulates that the agent must tunnel all HTTPS traffic to the address and port that you specify.

If you want to specify your proxy address with basic authentication, you can do so by modifying the proxy declaration string to include a username and password. Substitute <username> and <password> with the appropriate values according to this example:

json
1
{ "https": "<username>:<password>@10.1.2.3:8443" }

Priority 2: Environment Variable

While lower in priority than the manual proxy.config file configuration method, the agent regards the HTTPS_PROXY environment variable as the highest priority system-level proxy definition. Additionally, the agent also obeys any destinations excluded by the NO_PROXY environment variable.

Linux HTTPS_PROXY Environment Variable Procedure

The HTTPS_PROXY environment variable must be configured in the Insight Agent service file in order to save properly and persist as the host is powered on and off. The agent service file is located in /etc/systemd/system/ir_agent.service.

To set the HTTPS_PROXY environment variable using the agent service file on a Linux host:

1. Open a terminal on the Linux host.
2. Navigate to your ir_agent.service file and open it with a text editor, such as vi:

 
1
vi /etc/systemd/system/ir_agent.service

3. The output displays a series of categorical tags with variables under each tag. Under the [Service] tag, add the following line as shown and specify your desired IP address and port (10.1.2.3:8443 appears here as an example IP address and port combination):

 
1
Environment="HTTPS_PROXY=10.7.1.219:3128"

4. Save and close your changes.
5. To finish, reload systemctl and restart the agent service:

 
1
systemctl daemon-reload
2
service ir_agent restart

Priority 3: Operating System Configuration

If higher priority proxy definitions do not exist, the agent obeys proxy rules defined by the standard proxy configuration tools featured by the Windows and Mac operating systems.

Windows

The agent supports both the Automatically detect settings and Use automatic configuration script options shown in the following "Local Area Network (LAN) Settings" window.

You can manually configure proxy definitions in the "Proxy Settings" window:

1. Browse to the "Internet Properties" window.
2. Click LAN settings.
3. On the "Local Area Network (LAN) Settings" window, check the box under "Proxy server" to enable the proxy configuration fields.
4. Click Advanced.
5. Specify your proxy address in the "Secure" field.
6. Specify any exceptions as necessary.

Additionally, the agent references WinHTTP settings if no proxy definitions are found in the previous Windows system configuration options. Run the following command in a command prompt to set a WinHTTP proxy definition. Substitute <ip_address_or_domain> and <port> with the necessary values as shown:

 
1
netsh winhttp set proxy <ip_address_or_domain>:<port>

If you need to specify exclusions, append the previous command with an exclusion list according to the following syntax. Substitute instances of <exclusion> with the necessary values and delimit multiple exclusions with a ; as shown:

 
1
netsh winhttp set proxy <ip_address_or_domain>:<port> "<exclusion1>;<exclusion2>"

Given all these system-level proxy configuration options, the agent also follows a Windows-specific obedience hierarchy:

Mac

Configure proxy definitions in the "Proxies" tab:

1. Click System Preferences.
2. In the "System Preferences" window, click Network.
3. In the "Network" window, click Advanced.
4. Click the Proxies tab.
5. Select the Secure Web Proxy (HTTPS) option.
6. Specify an address in the "Secure Web Proxy Server" field.
7. Specify any exceptions as necessary.