Deploy the Insight Agent

The Insight Agent is lightweight software you can install on supported assets—in the cloud or on-premises—to easily centralize and monitor data on the Insight platform. The Insight Agent gives you endpoint visibility and detection by collecting live system information—including basic asset identification information, running processes, and logs—from your assets and sending this data back to the Insight platform for analysis.

The Insight Agent can be installed directly on Windows, Linux, or Mac assets. Each Insight Agent only collects data from the endpoint on which it is installed.

For information on mass deployments of the Insight Agent, see Mass Deploy in the Insight Agent product documentation.

Determine the Installer Type

You can install the Insight Agent on your target assets using one of two distinct installer types. While both installer types functionally achieve the same goal, the following table details each type and explains their differences so you can decide which would be most suitable for deployment in your organization.

Token-Based Installer (Preferred)

Token-Based Installer (Preferred)

The token-based installer is the newer Insight Agent installer type and eliminates much of the configuration complexity inherent to its certificate package counterpart. In almost all situations, it is the preferred installer type due to its ease of use.

How the Token Works

The token-based installer is a single executable file formatted for your intended operating system. At the time of execution, the installer uses a token that you specify to pull all the necessary certificates from the Insight Platform that pertain to your organization. Since this installer automatically downloads and locates its dependencies for you, it significantly reduces the number of steps involved for any Insight Agent deployment.

Certificate Package Installer (Legacy)

Certificate Package Installer (Legacy)

The certificate package installer predates the token-based variant and relies on the user to properly locate all dependencies during deployment. It is considered a legacy installer type because the token-based installer achieves the exact same purpose with reduced complexity. However, some deployment situations may be more suited to the certificate package installer type. For example, the certificate package installer type is often the only option if you need to deploy the Insight Agent on restricted or firewalled systems.

Certificates expire after 5 years

If you download and host the certificate package installer, you will need to refresh your certificates within 5 years to ensure new installations of the Insight Agent are able to fully connect to the Insight Platform. For more information on what to do if you have an expired certificate, refer to Expired Certificates.

How the Certificate Package Works

The certificate package installer comes in the form of a ZIP file that also contains the necessary certificates that pertain to your organization. Since these dependencies come in the ZIP file itself, the installer does not rely on the Insight Platform to retrieve them. However, this also means that you must properly locate the installer with its dependencies in order for the installation to complete successfully.

Reinstalling the Insight Agent with a certificate package? Check your directory first!

When reinstalling the Insight Agent using the installation wizard and the certificate package installer, the certificates must be in the same directory where the installer is executed.

This page covers the Token-Based Installer

The Token-Based installer type is recommended and steps to deploy the agent follow steps for that installer. For information about the legacy installer, see Legacy Agent Install.

## Download an Installer from Agent Management

NOTE - Privileges required

You must be a platform or product administrator to access Agent Management.

  1. Go to insight.rapid7.com and sign in with your Insight account email address and password.
    • If you are not directed to the Insight Platform Home page upon signing in, open the navigator in the upper left corner of your screen and click Insight Platform Home.
  2. Open the left menu and click the Data Collection Management tab, then click Agents.
  3. Open the Add New dropdown in the upper right corner of the screen and click Agent. The Download Insight Agent page displays with a group of supported operating systems.
  4. Click any of these operating system buttons to open their respective installer download panel. Each panel includes separate procedures for both the token-based and certificate package installers:
    • Token-based installers are available in the Download tab.
    • Certificate package installers are available in the Advanced tab.
  5. Download the installer type for the operating system of your choice.

File types

The contents of your download will vary depending on the installer type and operating system you select. Token-based installers come in a single .msi file (Windows) or .sh script (Mac and Linux). Certificate package installers come in ZIP files and are so named because they also contain your necessary certificates that the installer will reference when you execute it.

Install using Token-Based Installer

The Insight Agent supports proxies

Both the token-based and certificate package installer types support proxy definitions. If you need to direct your agents to send data through a proxy before reaching the Insight platform, see the Proxy Configuration page for instructions.

Before proceeding with the installation, verify that your intended asset is running a supported operating system and meets the connectivity requirements. If your organization also uses endpoint protection software, ensure that the Insight Agent is allowed to run when detected.

Installer Requirements

Installer requirements

Install the Insight Agent on the Collector

As with the rest of the endpoints on your network, you must install the Insight Agent on the Collector.

The token-based installer also requires the following:

  • Your asset must be able to communicate with the Insight platform in order for the installer to download its necessary dependencies.
  • If your assets are deployed in a network with strict URL filtering rules in place, you may need to whitelist the following token resource endpoint to ensure that the installer can pull its configuration files from the Insight Platform. Substitute <REGION> with the code that applies to your data region:
1
https://<REGION>.deployment.endpoint.ingress.rapid7.com/api/v1/get_agent_files
Installer Characteristics

Installer characteristics

Unlike the certificate package variant, the token-based installer does not include its necessary dependencies when downloaded. Instead, the installer uses a token specific to your organization to send an API request to the Insight platform. This allows the installer to download all required files at install time and place them in the appropriate directories on your asset.

When the installer runs, it downloads and installs the following dependencies on your asset. All together, these dependencies are no more than 20KB in size:

  • client.key
  • client.crt
  • config.json
  • cafile.pem

Generate a Token

The first step of any token-based Insight Agent deployment is to generate your organizational token. If you were directed to this article from the Download page, you may have done this already when you downloaded your installer.

Token Overview

Your token consists of two parts:

  • The region identifier - This portion identifies the region where your organization is located. For example, us is the region identifier for the United States, while ca is the region identifier for Canada.
  • The Universally Unique Identifier (UUID) - The UUID represents the token itself. The API request initiated by the installer sends this UUID to the Insight platform in order to retrieve the JSON document that contains all the necessary dependencies noted previously.

A fully generated token appears in the following format:

us:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

  1. Go to insight.rapid7.com and sign in with your Insight account email address and password.
    • If you are not directed to the Insight Platform Home page upon signing in, open the navigator in the upper left corner of the screen and click Insight Platform Home.
  2. Open the left menu and click the Data Collection Management tab, then click Agents.
  3. Click Add New in the upper right corner of the page. The Download Insight Agent page displays with a group of supported operating systems.
  4. Click any of these operating system buttons to open their respective installer download panel.
  5. On the Download tab of this panel, navigate to the Token Management section and click Generate.
    • For Windows assets, you must copy your token and enter it during the installation wizard, or format it manually in an installation command for the command prompt.
    • For Mac and Linux assets, the Download tab in this panel automatically formats your install command to include your current token.

NOTE - Does your company have multiple Rapid7 organizations?

Keep in mind that a token is specific to one organization. If your company has multiple organizations with Rapid7, make sure you select the correct organization from the "Download Insight Agent" page before you generate your token.

Agent Attributes for InsightVM

Agent attribute configuration is an optional asset labeling feature for customers using the Insight Agent for vulnerability assessment with InsightVM. Configured exclusively using the command line installation method, InsightVM imports agent attributes as asset tags that you can use to group and sort your assets in a way that is meaningful to your organization.

If you want to install your agents with attributes, check out the Agent Attributes page to review the syntax requirements before continuing with the rest of this article.

Install on Windows

Windows is the only operating system that supports installation of the agent through both a GUI-based wizard and the command line. This section covers both installation methods.

Install using the Wizard

The installation wizard guides you through the setup process and automatically downloads the configuration files to the default directories.

NOTE

If you want to store the configuration files in a custom location, you’ll need to install the agent using the command line.

To install the Insight Agent using the wizard:

  1. Run the .msi installer.
  2. Follow the prompts to install the Insight Agent.
  3. When the "Agent Pairing" screen appears, select the Pair using a token option.
  4. Enter your token in the provided field.
  5. Advance through the remaining screens to complete the installation process. The Insight Agent will be installed as a service and appear with the name "Rapid7 Insight Agent" in your service manager.

What if I wasn’t prompted to enter my token?

If the "Agent Pairing" screen does not appear during the wizard, the installer may have detected existing dependencies for the Insight Agent on your asset. To resolve this issue, delete any of those files manually and try running the installer again.

Install Using the Command Line

Running the Windows installer from the command line allows you to specify a custom path for the agent’s dependencies, configure any agent attributes for InsightVM, and perform a silent installation.

The following example command utilizes these flags:

  • CUSTOMCONFIGPATH - The absolute path where the installer downloads its dependencies.
    • If you specify this path as a network share, the installer must have write access in order to place the files. Additionally, any local folder specified here must be a writable location that already exists.
  • CUSTOMTOKEN - The token you generated and copied from the Insight Agent download panel.
    • Note that the token flag is always required. If the token is not specified, the installer will have no way to download the necessary dependencies.

REMINDER

Unlike its usage with the certificate package installer, the CUSTOMCONFIGPATH flag has a different function when used with the token-based installer. In this example, the path you specify establishes the target directory where the installer will download and place its necessary configuration files.

If you omit this flag from your command line operation, all configuration files will download to the current directory of the installer.

To perform a silent installation of a token-based installer with a custom path, run the following command in a command prompt. Substitute <target-directory-for-dependencies> and <regionalID:UUID> with your custom path and token, respectively:

1
msiexec /i agentInstaller-x86_64.msi /l*v insight_agent_install_log.log CUSTOMCONFIGPATH=<target-directory-for-dependencies> CUSTOMTOKEN=<regionalID:UUID> /quiet

The Insight Agent will be installed as a service and appear with the name "Rapid7 Insight Agent" in your service manager.

Install on Mac and Linux

TIP

All Mac and Linux installations of the Insight Agent are silent by default.

Running the Mac or Linux installer from the terminal allows you to specify a custom path for the agent’s dependencies and configure any agent attributes for InsightVM.

The following example command utilizes these flags:

  • --config_path - The absolute path where the installer downloads its dependencies.
    • Note that if you specify this path as a network share, the installer must have write access in order to place the files. Additionally, any local folder specified here must be a writable location that already exists.
  • --token - The token you generated and copied from the Insight Agent download panel.
    • Note that the token flag is always required. If the token is not specified, the installer will have no way to download the necessary dependencies.

REMINDER

Unlike its usage with the certificate package installer, the --config_path flag has a different function when used with the token-based installer. In this example, the path you specify establishes the target directory where the installer will download and place its necessary configuration files.

If you omit this flag from your command line operation, all configuration files will download to the current directory of the installer.

Install the Insight Agent on Linux (Intel)

  1. Open a terminal and change the execute permissions of the installer script:
1
chmod u+x agent_installer-x86_64.sh
  1. Copy and run the command that was formatted for you in the Linux download panel of Agent Management. This command already includes your organizational token. If you want to format the command manually, substitute <regionalID> and <UUID> with your region code and token as shown in the following example:
1
sudo ./agent_installer-x86_64.sh install_start --token <regionalID>:<UUID>

Alternatively, if you wish to include the --config_path option noted previously, run the following appended command, substituting <target-directory-for-dependencies>, <regionalID>, and <UUID> with the appropriate values:

1
sudo ./agent_installer-x86_64.sh install_start --config_path <target-directory-for-dependencies> --token <regionalID>:<UUID>

Your complete command should match the format shown in this example:

1
sudo ./agent_installer-x86_64.sh install_start --config_path /path/to/location/ --token us:11111111-1111-1111-1111-11111111111

The Insight Agent will be installed as a service and appear with the name "ir_agent" in your service manager. If you prefer to install the agent without starting the service right away, modify the previous installation command by substituting install_start with install.

Install the Insight Agent on Linux (ARM64)

  1. Open a terminal and change the execute permissions of the installer script:
1
chmod u+x agent_installer-arm64.sh
  1. Copy and run the command that was formatted for you in the Linux download panel of Agent Management. This command already includes your organizational token. If you want to format the command manually, substitute <regionalID> and <UUID> with your region code and token as shown in the following example:
1
sudo ./agent_installer-arm64.sh install_start --token <regionalID>:<UUID>

Alternatively, if you wish to include the --config_path option noted previously, run the following appended command, substituting <target-directory-for-dependencies>, <regionalID>, and <UUID> with the appropriate values:

1
sudo ./agent_installer-arm64.sh install_start --config_path <target-directory-for-dependencies> --token <regionalID>:<UUID>

Your complete command should match the format shown in this example:

1
sudo ./agent_installer-arm64.sh install_start --config_path /path/to/location/ --token us:11111111-1111-1111-1111-11111111111

The Insight Agent will be installed as a service and appear with the name "ir_agent" in your service manager. If you prefer to install the agent without starting the service right away, modify the previous installation command by substituting install_start with install.

Install the Insight Agent on Mac (Intel)

  1. Open a terminal and change the execute permissions of the installer script:
1
chmod u+x agent_installer-x86_64.sh
  1. Copy and run the command that was formatted for you in the Mac download panel of Agent Management. This command already includes your organizational token. If you want to format the command manually, substitute <regionalID> and <UUID> with your region code and token as shown in the following example:
1
sudo ./agent_installer-x86_64.sh install_start --token <regionalID>:<UUID>

Alternatively, if you wish to include the --config_path option noted previously, run the following appended command, substituting <target-directory-for-dependencies>, <regionalID>, and <UUID> with the appropriate values:

1
sudo ./agent_installer-x86_64.sh install_start --config_path <target-directory-for-dependencies> --token <regionalID>:<UUID>

Your complete command should match the format shown in this example:

1
sudo ./agent_installer-x86_64.sh install_start --config_path /path/to/location/ --token us:11111111-1111-1111-1111-11111111111

The Insight Agent will be installed as a service and appear with the name "ir_agent" in your service manager. If you prefer to install the agent without starting the service right away, modify the previous installation command by substituting install_start with install.

Install the Insight Agent on Mac (ARM64)

  1. Open a terminal and change the execute permissions of the installer script:
1
chmod u+x agent_installer-arm64.sh
  1. Copy and run the command that was formatted for you in the Mac download panel of Agent Management. This command already includes your organizational token. If you want to format the command manually, substitute <regionalID> and <UUID> with your region code and token as shown in the following example:
1
sudo ./agent_installer-arm64.sh install_start --token <regionalID>:<UUID>

Alternatively, if you wish to include the --config_path option noted previously, run the following appended command, substituting <target-directory-for-dependencies>, <regionalID>, and <UUID> with the appropriate values:

1
sudo ./agent_installer-arm64.sh install_start --config_path <target-directory-for-dependencies> --token <regionalID>:<UUID>

Your complete command should match the format shown in this example:

1
sudo ./agent_installer-arm64.sh install_start --config_path /path/to/location/ --token us:11111111-1111-1111-1111-11111111111

The Insight Agent will be installed as a service and appear with the name "ir_agent" in your service manager. If you prefer to install the agent without starting the service right away, modify the previous installation command by substituting install_start with install.


How to Uninstall

If you want to uninstall the Insight Agent from your assets, see the Agent Controls page for instructions.

NOTE - Agent directory retention after uninstalling

In order to quicken agent uninstalls and streamline any potential reinstalls, be aware that agent uninstallation procedures still retain portions of the agent directory on the asset.

If you need to remove all remaining portions of the agent directory, you must do so manually.