Download and Install the Insight Agent

This article guides you through the different methods you can use to install and download the Insight Agent.

You can install the Insight Agent on your target assets using 2 required installation options that can be used interchangeably depending on the network connectivity settings of your assets. While either of the options functionally achieve the same goal of installing the agent and connecting it to the Insight Platform, this article details each of the installation options available and explains their differences so you can decide which would be most suitable for deployment in your organization.

Deciding which installation option to use

There are two main Agent Installation options available that can be used interchangeably:

• Token
• Certificate

Installing the Insight Agent using a Token

Choose the Token installation option when your install destination host machine can reach Rapid7 endpoints directly or via a Rapid7 collector.

If you intend to install the Insight Agent using your organization’s token:

• Your assets must be able to communicate with the Insight platform in order for the installer to download its necessary dependencies.
  • As long as you verify the network connectivity requirements noted previously, this communication channel will be available for use.
• If your assets are deployed in a network with strict URL filtering rules in place, you may need to allowlist 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
1
2
https://<REGION>.deployment.endpoint.ingress.rapid7.com/api/v1/get_agent_files

What is a Token?

A token is your organization’s unique identifier that can be used to install the Insight Agent in your environment and helps to link the installed agents to your organization. At the time of installation, the Insight Agent uses the token that you specify to pull all the necessary certificates and configuration files from the Insight Platform that pertain to your organization and uses them to configure the agent to be listed in your organization within the Insight Platform.

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:

<region_id>:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Note that the process of installation with a token, the Insight Agent installer will download the following dependencies onto 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.

To Generate a Token (if you have not done so already):

1. Go to insight.rapid7.com and sign in with your Insight account email address and password.
   1. 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. On the left menu, click the Data Collection tab, then click the Agents tab.
3. At the top of the screen, click the Agent Installer tab.
4. At the bottom of the Install Agent using Token card on the left side of the screen, click on Token Management.
5. Once in the Token Management screen, click on the Generate button. This will create a Token ID for you to use.

Install the Insight Agent using the Certificate Package

Choose the Certificate Installation method when your install destination host machine can not reach Rapid7 endpoints directly or via a Rapid7 collector.

You can download the latest Certificate Package from insight.rapid7.com > Data Collection Management > Agent Installer > Install using Certificate Package > Download Certificates

What is the Certificate Package?

The certificate package comes in the form of a ZIP file that contains the necessary certificates and configuration files that pertain to your organization. You can download and use these dependencies to install the Insight Agent when the network connectivity of the asset does not allow pulling down these dependencies automatically using the token. For example, the certificate package is often the only option if you need to deploy the Insight Agent on restricted or fire-walled systems.

Certificate package contents

Your certificate package ZIP file contains the following security files in addition to the installer executable:

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

Expired certificates

If you use the Certificate Package Installation method to install the Insight Agent, your certificates will expire after 5 years. Insight Agents that were previously installed with a valid certificate are not impacted and will continue to update their SSL certificates. New installations of the Insight Agent using an expired certificate will not be able to fully connect to the Insight Platform to run jobs in InsightVM, InsightIDR, or InsightOps.

Refresh your certificates

If you host your certificate package on a network share, or if it is baked into a golden image for a virtual machine, redownload your certificate package within 5 years to ensure new installations of the Insight Agent run correctly.

Available installation options

The Insight Agent has several installation options that enable you to install the agents according to the specific configuration needs of your organization. Learn more about the installation options available below.

Download an Installer from the Insight Platform

Now that you’ve determined which Insight Agent installation method you want to use, you’re ready to download the installer. You can download both installer types from the Agent Management screen in your Insight Platform user interface.

After you download the installer, we’ll direct you to our dedicated installation documents to cover the rest of the procedure for both installation methods.

To download a token-based or certificate package installer for your desired operating system:

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. At the top of the screen, click the Agent Installer tab.
4. Select the Agent Installation method of your choice and follow the instructions.
   • Each panel includes separate procedures for both the token and certificate package installation methods.
5. Download the Insight Agent installer based on the operating system of your choice.

Next Steps

Now that you have your desired installer in place, you’re ready to move on to the installation phase. See our dedicated documents for Windows, Mac, and Linux installation methods for further instructions.