Insight Agent
The Insight Agent plugin for InsightConnect allows a user to retrieve details and execute response actions on Rapid7 Insight Agent endpoints. Agents are used in both Rapid7 InsightVM and InsightIDR products.
To use the Insight Agent plugin in InsightConnect, a Rapid7 Platform API Key must be created and then configured within the plugin connection in InsightConnect. For more information on the functionality of the plugin, see the Extension Library listing.
Create a Rapid7 Insight Platform API Key
There are two types of keys:
- a User API Key
- an Organization API Key.
Either key type will work for the integration but choose the appropriate key based on the access you expect the integration to have. Learn more about these key types below or visit Managing Platform API Keys to learn how to manage them.
- User key - Represents a specific user in an organization. This type of key can only be created by a user and inherits the permissions of the user. You cannot generate a user key for other users.
- Organization key - Represents an entire organization and is a super key. This type of key has full access across all products. Only an organization or platform administrator can generate an organization key.
To start, log into the Insight Platform and follow these steps:
- Click the key logo on the left side navigation menu.
- Click User Keys from the list of API Key types.
- Click the blue New User Key button on the right hand side of the page.
In the Generate New User Key window, select the organization the key needs access to and create an identifiable name it.
With the API key created, click Copy to add it to the clipboard to later paste in the Insight Agent plugin connection configuration in InsightConnect. Note that this is the only time that key will be viewable. If the key is not copied for later use, it will need to be deleted and a new API key created in its place.
Configure the Insight Agent Plugin Connection in InsightConnect
Open the connection configuration for the Insight Agent plugin within InsightConnect.
This can be done when selecting the Rapid7 Insight Agent plugin during a workflow building session or by creating the connection independently by choosing Plugins & Tools from the Settings tab on the left menu. We'll use the latter method during this tutorial as it is the best method for managing all of your plugin connections. On the Plugins & Tools page, select the Connections tab and click Add Connection in the upper-right corner.
When creating the Insight Agent plugin connection, be sure to give it a unique and identifiable name. Select where the plugin should run, and then choose the Rapid7 Insight Agent plugin from the list. If it is not available, then import the plugin from the Installed Plugins tab.
With the connection basics configured, it is now time to add the Rapid7 Insight Platform API key and server information. In the API Key field, create a credential and paste in the Rapid7 Insight Platform API key that was copied earlier. Make sure to choose the region that your organization is located in. When the connection details looks correct, press the Save button to save the connection.
Next, a connection test will begin and attempt to authenticate to the Rapid7 Insight Platform. A blue circle on the Connection tile indicates that the Connection test is in progress. If you don't see a blue circle, the connection succeeded and you’re ready to start orchestrating your processes with the Insight Agent plugin.
A red circle indicates that the connection test failed. If this occurs, check your connection details (including the API key and Region) before trying again and that your orchestrator is online and has network access to the Rapid7 Insight Platform.
The log may contain useful troubleshooting information. First, click View to see a list of your recent connection tests.
Under the Test Status tab, expand the dropdown for the test that encountered an error to view its log.
