Back to binalyze.com

Adding proxy to Responder

Why Proxy Support

Responder establishes connections to remote servers over HTTP, HTTPS, NATS, SFTP, FTPS, SMB, and Websocket over HTTPS. Please note that the supported protocols are subject to change in the future.

Responder primarily communicates with the AIR Console via HTTP/S, as HTTP/S is the most essential protocol.

There is a requirement to tunnel the responder’s connections over a different server, not to directly communicate with AIR Console or other servers. As a result, we implemented the proxy feature for all types of communication methods, which is entirely optional. Although it is optional, we enable the Proxy feature of the responder by default during the initial installation. However, previous installations without the proxy feature are unaffected, and the feature remains disabled. This means upgrading an existing responder to a version <= v2.15.x will not be affected by this new feature as long as it is not enabled explicitly. Enabling and disabling the proxy feature manually is documented below. Please note that, as of now, the only way to enable or disable the proxy feature is to run the related commands on the machine. That is to say, it cannot be changed remotely via the AIR Console.

Proxy Server Types

In this document, we are only interested in Forward proxy servers. Other types of proxy servers, such as reverse proxy servers and transparent proxy servers, are out of scope.

We only support forward proxy servers that support HTTP Tunneling with the HTTP Connect method and SOCKS5 proxy servers.

Note that we also support HTTP proxy servers using SSL/TLS encryption via HTTPS protocol; however, the SSL certificate of the server must be a valid certificate, or the CA certificate of the server certificate must be loaded to the machine to determine whether the encrypted connection is secure or not.

The responder uses the system’s SSL/TLS certificate validation methods and AIR Console’s CA certificate to validate the certificates of the remote server.

We will also describe how we handle Authenticated Proxy Servers below.

We anticipate encountering more issues with HTTPS proxy servers, authenticated proxy servers, and SSL interception/bumping in the future. Because of this, the proxy configuration of these types of servers and the Agent must be performed carefully.

Configure Proxy Settings

There are different ways to configure the proxy settings for all supported platforms, including the machine and the Agent. Due to historical reasons, responders can detect proxy settings on different platforms from various sources. As a result, our detection of the proxy settings logic is described below.

  1. If ProxyEnabled: false or missing ProxyEnabled option in the agent’s config.yml file, we skip reading proxy settings. Missing ProxyEnabled option means ProxyEnabled: false, implicitly.

  2. Try to find proxy settings using AIR_HTTP_PROXY and AIR_HTTPS_PROXY environment variables. If they are set, they will be used as the source of proxy settings.

  3. Try to find proxy settings using HTTP_PROXY, HTTPS_PROXY, http_proxy, and https_proxy environment variables. If they are set, they will be used as the source of proxy settings. Note that this is the default approach for UNIX-like systems.

  4. If the proxy environment variable is not set, we use the operating system's API to retrieve the proxy settings.

Note that setting one of the HTTP_PROXY, HTTPS_PROXY, AIR_HTTP_PROXY, or AIR_HTTPS_PROXY environment variables is sufficient to use a single proxy address.

You must restart the responder’s service if there is a change in the environment variables or config.yml file changes to let the Agent take the new values into account.

Configure Proxy Settings on Linux

AIR_HTTP_PROXY, AIR_HTTPS_PROXY, HTTP_PROXY, HTTPS_PROXY, http_proxy, and https_proxy proxy server environment variables are used if they are set. We use them to configure the Agent's proxy behavior. In addition to these environment variables AIR_NO_PROXY, NO_PROXY, and no_proxy environment variables are also used if they are set as long as a proxy server is set in the proxy environment variables.

We use an additional AIR_ prefix for responder-specific proxy environment variables to let users set a proxy server for only the Agent or use a different proxy server for the responder.

Since the Agent runs as a service or daemon, users need to configure the proxy settings using the following method.

If /etc/environment.d/binalyze-air-agent.conf does not exist, create it.

Open /etc/environment.d/binalyze-air-agent.conf and add the following example lines to it:

AIR_HTTP_PROXY=proxy.example.com:3128 AIR_HTTPS_PROXY=proxy.example.com:4128 AIR_NO_PROXY=localhost,127.0.0.0/8,::1

The responder's systemd service file will read the changes made to the edited file. Therefore, it is necessary to reload the changes and restart the service for the changes to take effect. You can do this by running the following commands:

sudo systemctl daemon-reload sudo systemctl restart Binalyze.AIR.Agent.service

You should keep in mind that using systemd’s approach to override service settings to set proxy settings can create an issue after uninstalling the responder from the machine. Because the overridden service settings are retained after uninstallation, installing a responder to that machine after uninstallation will utilize the overridden service configuration.

Configure Proxy Settings on macOS

Setting proxy environment variables, as in Linux, is a way to configure a proxy for the responder.

As the agent works as a daemon in the macOS system with root privileges under the launchd service manager, we can set the environment variables like this

Open the launchd.conf file to add environment variables (Note that the file may not exist, you can create it)

sudo nano /etc/launchd.conf

Append the proxy environment variables like this. Alternatively, you can skip AIR_ prefix but it will affect other programs in the system.

# ... setenv AIR_HTTP_PROXY proxy.example.com:3128 setenv AIR_HTTPS_PROXY proxy.example.com:4128 setenv AIR_NO_PROXY *.local,169.254/16

The method above will require a reboot to be effective. Alternatively, you can use the other methods mentioned below without needing to reboot.

The second method for setting environment variables on macOS is to use the following commands.

sudo launchctl setenv AIR_HTTP_PROXY proxy.example.com:3128 # You should use the same command for other environment variables

The method above requires restarting the responder’s service like this:

sudo launchctl unload /Library/LaunchDaemons/com.binalyze.air-agent.plist sudo launchctl load -w /Library/LaunchDaemons/com.binalyze.air-agent.plist

Apple explains the third way to set a proxy for macOS systems with this link Change proxy settings on Mac

You should bear in mind that only HTTP and HTTPS proxies are supported via System Settings > Network > ... > Proxies not SOCKS or other types.

macOS saves the credentials of the proxies set by System Sessions to the Key Chain. The responder doesn’t support Key Chain access to get the credentials, so we don’t recommend using authenticated proxies using this method. You can set the username and password of the proxy server using environment variables, which are explained in this document.

macOS launchd Tips

Question:

How do I set environment variables that persist across reboots for a specific daemon/service on a macOS system?

Answer:

To set environment variables that are persisted across reboots for a specific daemon or service on a macOS system, you can use the launchctl setenv command as follows:

  1. Identify the name of the daemon or service that you want to set the environment variables for. This name is typically specified in the Label key in the daemon's property list file, which is stored in /Library/LaunchDaemons or /System/Library/LaunchDaemons for system-level daemons, or in ~/Library/LaunchAgents for user-level daemons and services.

  2. Use the launchctl setenv command to set the environment variables for the daemon or service, using the -n option to specify the name of the daemon or service. For example, to set the FOO environment variable to bar for the com.example.myservice service, you would use the following command:

sudo launchctl setenv -n com.example.myservice FOO bar

  1. To verify that the environment variable has been set, you can use the launchctl getenv command, using the -n option to specify the name of the daemon or service. For example:

sudo launchctl getenv -n com.example.myservice FOO

This should print bar.

Keep in mind that the launchctl setenv command only sets environment variables for processes launched by launchd, and it does not modify the environment of processes that are already running. If you want to set environment variables for a running process, you will need to use a different method, such as setting the variables in the process's shell configuration file or using the export command in the process's shell.

Also, note that the launchctl setenv command only sets environment variables for daemons and services managed by launchd. If you want to set environment variables for other processes, you will need to use a different method.

The responder’s service/daemon name is com.binalyze.air-agent on macOS systems.

Configure Proxy Settings on Windows

As explained for Linux and macOS, the responder can also use the specified proxy environment variables for Windows.

The responder runs as a service using SYSTEM account on Windows systems. Because of this, a user’s proxy settings cannot be accessed by the SYSTEM account without using unnecessarily complex methods.

The responder can only access the system’s environment variables, not the user’s environment variables.

The first method is to use the proxy environment variables to set a proxy for the responder. There are different ways to set environment variables for Windows.

Question:

Please instruct me on how to set system environment variables for Windows systems.

Answer:

To set system environment variables on a Windows system, you will need to follow these steps:

  1. Press the Windows key + R to open the Run dialog.

  2. Type "sysdm.cpl" and press Enter to open the System Properties window.

  3. Switch to the "Advanced" tab.

  4. Click the "Environment Variables" button.

  5. In the Environment Variables window, you can set system environment variables by doing the following:

  • To set a new system environment variable, click the "New" button under the "System variables" section.

  • To edit an existing system environment variable, select it from the list and click the "Edit" button.

  1. In the Edit Environment Variable window, enter the name and value for the environment variable.

  2. Click "OK" to save the changes.

  3. Close the Environment Variables and System Properties windows.

Note: You will need to have administrator privileges to make these changes.

The second method is to use the netsh command to set winhttp proxy.

Question:

Please instruct me on how to set a proxy using the netsh command on a Windows system with an administrator account.

Answer:

  1. Press the Windows key + X and select "Command Prompt (Admin)" to open an elevated Command Prompt window.

  2. Type the following command and press Enter to set the proxy server:

netsh winhttp set proxy [proxy_server_name]:[port]

Replace [proxy_server_name] and [port] with the actual values for your proxy server and port.

  1. If your proxy requires authentication, you can use the following command to set the username and password:

netsh winhttp set proxy [proxy_server_name]:[port] "user=[username]&password=[password]"

Replace [proxy_server_name], [port], [username], and [password] with the actual values for your proxy server, port, username, and password.

  1. To verify that the proxy has been set, you can use the following command:

netsh winhttp show proxy

This will display the current proxy settings.

Note: You will need to have administrator privileges to run these commands.

The third way of setting a proxy is to use the netsh winhttp set advproxy command. This is introduced after Windows 11.

Create a settings.json file like this:

{"Proxy": "10.211.55.3:3128", "ProxyBypass": "", "AutoconfigUrl": "", "AutoDetect": false}

Run the command like this:

netsh winhttp set advproxy setting-scope=machine settings-file=settings.json

To clear advproxy settings, you need to run the same command but settings.json should have empty fields like this

{"Proxy": "", "ProxyBypass": "", "AutoconfigUrl": "", "AutoDetect": false}

The fourth way of setting a proxy using the Windows registry is as follows:

Open the registry editor and go to the Internet Settings key

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings

Set the values using proxy settings like this

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings] "ProxyEnable"=dword:00000001 "ProxyOverride"="*.noproxy.example.com" "ProxyServer"="example.com:3128" "AutoConfigURL"="http://example.com/wpad.dat"

You need to restart the responder’s service if proxy settings are changed.

Static vs Automatic Proxy

Automatic proxy means that we use the URL of the PAC file to get the proxy URL from the Operating System. Automatic proxy support is only applicable to macOS and Windows platforms. Other proxy settings are considered static proxy settings, and they require restarting the responder service if any changes are made.

There may be some issues if Automatic Proxy is used with our Isolation feature on Windows.

Because, for automatic proxies, wpad.dat or PAC files are fetched from the AutoConfigURL address by the Windows platform’s own services. Therefore, these services may not have access to the target URL during DNS resolution or HTTP request processing. This may grant the responder direct access to the remote servers, bypassing the proxy. If a direct connection is not allowed from that machine, the responder will not be able to communicate with the AIR Console. It is recommended that users exercise such scenarios for Windows platforms.

Authenticated Proxies

The responder obtains the proxy server’s authentication information using the proxy server's URL. For example, if a proxy is set using an environment variable AIR_HTTP_PROXY=http://username:[email protected]:3128 then the responder parses the URL and uses the username and password of the proxy server to send to the proxy server with an HTTP header, e.g. Proxy-Authorization: Basic encoded-credentials`

For authenticated SOCKS5 proxy servers, the URL structure is the same for authorization, and it uses the SOCKS5 protocol's authentication method, e.g. socks5://username:[email protected]:1080

NATS & Evidence Repositories

The responder uses a NATS client to connect to a NATS server over port 4222. NATS is used to get notifications from the AIR Console about the tasks in the queue. This helps the responder complete tasks promptly when assigned.

As our proxy requirement for the responder is to connect over a proxy server always, if it is set, the responder tries to connect to AIR Console’s NATS server using HTTP or SOCKS5 proxies, like regular HTTP connections. It uses the same HTTP Connect method to create a tunnel to the server for the NATS protocol.

If the proxy server does not support tunneling on port 4222, the responder attempts to connect to the NATS server directly, thereby bypassing the proxy server. Note that this is the default behavior for all non-HTTP protocols, SMB, FTPS, and SFTP.

SMB uses port 445.

SFTP uses port 22.

FTPS uses port 21 and high ports for data transfer.

If the proxy server is configured to open a tunnel for our supported protocols, there shouldn’t be any problem. Because of the fallback mechanism we use to bypass the proxy server when creating a tunnel fails, the responder should be able to send data to the remote server.

SSL Bumping/Interception

If the proxy server is configured to intercept SSL traffic between the responder and the AIR Console, several essential points must be considered.

  1. CA certificate of the AIR Console should be considered valid by the proxy server. Otherwise, the proxy server cannot open a tunnel to the AIR Console.

  2. The responder uses Websocket for interACT communication over the HTTPS protocol. However, some proxy servers, e.g., Squid, may not support WebSocket communication well when SSL Bumping is enabled. So, the proxy server must be configured to handle Websocket over HTTPS with SSL bumping if interACT is used. This can be verified by opening an interACT terminal on the AIR Console and seeing the established connection.

Enable / Disable Proxy

By default, the proxy support is enabled after fresh new installations of version >=2.16.x.

When the proxy support is enabled, the config.yml file contains theProxyEnabled: true entry. When this configuration is set to false or missing, it means it is disabled.

You can enable or disable proxy support by running the following commands after the installation or upgrade is successful. Note that you must be an administrator or root to run these commands.

Windows:

"C:\Program Files (x86)\Binalyze\AIR\agent\AIR.exe" configure --enable-proxy"C:\Program Files (x86)\Binalyze\AIR\agent\AIR.exe" configure --disable-proxy

Linux/macOS:

/opt/binalyze/air/agent/air configure --enable-proxy/opt/binalyze/air/agent/air configure --disable-proxy

These commands enable or disable proxy support to perform the following actions.

  • Check if the configuration change can be applied; otherwise, exit

  • Stop the responder’s service

  • Change the responder’s configuration

  • Start the responder’s service

Note that exit code 0 (zero) means success. Other exit codes indicate that an error occurred.

Last updated

Was this helpful?