Agent Management in the Insight Platform

Elevated privileges required

Your Insight account must have a platform or product administrator role to access the Agent Management view.

The Agent Management experience in your Insight Platform Home page is the central location for monitoring all the Insight Agents you have deployed across your organization.

For information on how to use additional Agent Management settings and access Insight Agent logging capabilities, see the following articles:

To access Agent Management:

  1. Go to insight.rapid7.com and sign in with your Insight account email address and password.
    • If you do not see the Insight Platform Home screen upon signing in, open the navigator in the upper left corner of the screen and click Insight Platform Home.
  2. On the Insight Platform Home page, open your left menu and click Data Collection Management, then click Agents to open Agent Management.

Download center

Agent Management has a direct link to the Insight Agent download page in the upper right corner of the screen. Once there, select your operating system to get started. Complete installation documentation is available from our installation overview and its included subpages.

Organizations

Agent Management supports dedicated views for environments composed of multiple organizations. Use the dropdown next to the Agents page title to swap between the organizational views that you have privileges to access.

Which organizations can I see?

The availability of organizational views will depend on your level of access:

  • Organizations will not appear if you do not have access to them
  • Organizations will appear if you have read-only access to them, but will be disabled

Status

Agents can have the following statuses:

  • Online - Indicated in green, an online agent has sent its status in the last 10 minutes.
  • Offline - Indicated in gray, an offline agent has sent its status within the last 15 days but not in the last 10 minutes.
  • Stale - Indicated in yellow, a stale agent has not sent its status in at least 15 days.
    • Agent Management will only be able to show this status if your retention setting is set to the 30 day period.

What happens to agents that stop communicating over time?

The Agents table functions as a rolling snapshot of all agents that have communicated with the Insight Platform for the currently selected organization. The duration of this snapshot is determined by a retention period setting that you can configure. By default, this retention period is set to 30 days.

Any agent that has not sent its status to the Insight Platform within the retention period will be removed from your Agents table and will no longer factor into your agent metrics. If the agent is able to check back in at a later time (which is common for assets that go without internet connectivity for extended periods), it will reappear. Consequently, agents shown here may differ from historical agents shown in your Insight products.

Agent errors

The "Status" column of the "Agents" table also indicates any recorded errors that were detected with that particular agent.

Agent errors

Open the Agent Information drawer to inspect detected errors in detail.

Agent error detail view

Metrics

Agent metrics

These metrics display your total number of deployed agents, further divided by status. Each will update in real time when any changes in status are detected.

TIP

Metric values are calculated based on records contained within the Agents table. These values will change based on any filters you have applied. See the Filters section to learn more.

Filters

You can refine the displayed data in the Agents table by applying preset or custom filters.

Preset filters

The Filter window contains a series of agent data categories and their corresponding applicable values. Each granular filter is appended with a value in parentheses to indicate the number of records that qualify. Select any of these checkboxes to apply a filter based on those qualifying agents. You can also apply a bulk-filter based on the data category itself.

TIP

You can apply multiple preset filters across several categories to further refine your metrics and table rows.

Custom queries

Custom queries

Use the query field to create more specific filters on your agents. Custom queries feature several different parameters that can be combined with a variety of operators for highly granular views of your agents in real time.

  1. Click the query field to open the parameter dropdown.
  2. Select any of the listed parameters. You can also type a keyword to narrow the parameter list.
  3. Select an operator. Available operators will depend on the parameter you have specified.
  4. Specify a value between the quotation marks.
  5. If desired, specify additional parameters with the AND or OR operators.
  6. Click Apply when finished.

Agent information drawer

Click the Hostname link of an agent record to open the Agent Information drawer, which contains additional information such as the agent ID, asset type, and in-depth location details.

CSV export

You can export agent records in CSV format with the Export to CSV button in the upper right corner of the Agents table.

CSV export

While it is possible to export your entire agent list with this function, Rapid7 recommends that you apply a filter to contextualize your table records first:

  1. In the Filter panel, apply one or more filters based on the available categories.
    • Alternatively, apply a query filter for a more customized agent list.
  2. Click Export to CSV. A banner appears at the top of the screen indicating a CSV file is being generated.
  3. The banner turns green when the CSV file is ready. Click Download CSV to retrieve your CSV export.

CSV download

NOTE

CSV exports are limited to 100,000 records.