Agent Management

The Agent Management view in your Insight platform account page is the central location for monitoring all the Insight Agents you have deployed across your organization.

Elevated privileges required

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

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 "My Products & Services" screen upon signing in, open the app switcher in the upper left corner of the screen and click My Account.
  2. On the "My Products & Services" screen, expand your left menu and click Data Collection Management to open Agent Management.

Agent Management includes the following features:

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 Install master page and its included subpages.

Organizations

Agent Management supports dedicated views for environments composed of multiple organizations. Use the dropdown next to “Data Collection Management” 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

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.

Throttle Agent Updates

Agent Management now provides a throttle feature that allows you to modify the allowable rate of concurrent agent updates. If you feel agent updates aren’t being rolled out fast enough or are using too much bandwidth, you can adjust the throttle level to meet the needs of your organization.

Throttle Levels

There are three throttle options:

  • High - This is the default setting. A “High” setting updates agents as fast as possible and uses the most bandwidth.
  • Medium - A “Medium” setting dials back concurrent updates and uses less bandwidth as a result.
  • Low - A “Low” setting dials back concurrent updates even further. As a consequence, this throttle option takes the longest to update all the agents in your organization, but uses the least amount of bandwidth.

NOTE

Throttling cannot be applied to a filtered set of agents. If you modify update throttling, this setting will apply to all agents in your organization.

Modify Agent Update Throttling

Follow these steps to modify update throttling:

  1. In the “Agent Management” screen, select Throttle Agent Updates from the “Settings” dropdown menu.
  1. In the option panel, select Low, Medium, or High.
  2. Click Save when finished.

NOTE

After you modify update throttling, your new throttle level won’t take effect until the next Insight Agent update is released.

Disable or Enable Automatic Agent Updates

NOTE

The ability to manage updates is only available if all the deployed Insight Agents in your organization are on version 2.7.0 and later. If you have agents in your organization that are currently on a version earlier than 2.7.0, this capability will not be available.

We release updates regularly to ensure your agents have the latest software. By default, all agents in your environment update automatically when a software update is available. From the Data Collection Management page, you can configure how you want to update your agents. Settings apply to all agents within an organization.

You can enable or disable automatic updates. For organizations that enable automatic updates, you can choose to update agents to the latest available version or a specific version.

To enable automatic updates:

  1. If you have multiple organizations in your environment, select the organization you want to update on the Data Collection Management page.
  2. From the Agents tab, go to the Settings menu and select Update Agents.
  3. Choose the Enable updates option.
  4. Choose the agent version you want to update to: the latest version or a specific version. The last three released versions will be listed.
  5. Save your changes.

A banner will indicate if the setting change was successful.

Asset Correlation

If you subscribe to InsightVM and use your agents to assess your assets for vulnerabilities in addition to on-premises scanning, Agent Management includes an asset correlation feature that promotes data correlation accuracy for asset records in your Security Console. See the Correlate Assets with Insight Agent UUIDs page on the InsightVM Help pages for complete documentation on this feature.

Table view

The “Agents” table contains individual records of all your deployed agents. Rows are sortable according to the following columns:

  • Hostname
  • Status
  • IP Address
  • Agent Version
  • Operating System
  • Connection Path
  • Last Seen

TIP

Click any of the listed column headers to toggle between ascending and descending order.

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.

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.

NOTE

CSV exports are limited to 100,000 records.

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.

What happens to stale agents over time?

Any agent that has not sent its status for more than 30 days 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 (this is often the case for assets that go without internet connectivity for extended periods), it will reappear.

The “Agents” table itself functions as a rolling 30 day snapshot of all agents deployed in your environment. 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.

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

Log Management

You can download agent logs from each of your individual agents by opening the Agent Information drawer at the table view. All log collection requests are recorded in a filterable archive.

Log Behavior

Log files in Agent Management have the following characteristics:

  • You must request a log file from the agent itself before you can download it.
    • Depending on the location of the agent and its network conditions, your log collection request can take several minutes to complete.
  • You can only download the most recently collected log from the Agent Information drawer.
    • If you want to download older logs, you can do so from the Log Archive.
  • You can only request logs on a per-agent basis.
  • Logs expire after 30 days and cannot be downloaded after that period.
  • If you request a log from an agent that is currently offline, you can collect the log only after the agent comes back online.

How to Download Agent Logs

To download the latest log for a specific agent:

  1. Browse to the desired agent record in the “Agents” table and click the hostname link to open the Agent Information drawer.
  2. Click the Collect logs button under the agent hostname to initiate a log request.
    • The button text changes to “Requested” while the log is collected.
    • If your log collection request fails, click Collect logs again to retry.
  3. After the log is collected, the Download last collected log link becomes available. Click this link to download the log file.

Log Archive

Click the Log Archive link in the upper right corner of your screen to access the “Log Archive” table.

The Log Archive lists all log collection requests that have been initiated in Agent Management, including any ongoing or failed requests. Like the “Agents” table, all Log Archive columns are sortable by ascending or descending order. You can also search for a specific log request by entering a string value in the search field that matches either the agent endpoint hostname or the agent ID.

Download Archived Agent Logs

You can download older agent logs that have not yet expired by clicking the download arrow in the rightmost column of the “Log Archive” table.

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 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

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.

TIP

Your five most recently applied queries will be saved for quick reuse in the Recent queries dropdown.