Agent Management settings - asset correlation, automatic updates, throttling, and retention controls

The Agent Management experience in the Insight Platform allows you to control a variety of Insight Agent behaviors for all agents deployed on assets across your organization. Read this article to learn about these settings and how to configure them.

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 in the InsightVM documentation for instructions on this feature.

Agent update throttle controls

Agent Management allows you to control the allowable rate of concurrent updates for Insight Agents deployed across your organization. If you feel that your agents aren't updating fast enough or are updating too quickly and using too much bandwidth in the process, you can throttle the rate of updates to meet the needs of your organization.

The maximum number of simultaneous agent updates is dynamically enforced by a throttle percentage you specify on a per-organization basis. By default, this throttle percentage is set to 25% of the total agent count tracked by Agent Management. As agents finish updating, others will start their update process as long as the throttle limit is not exceeded.

1% is the lowest possible setting, followed by 5%. The throttle percentage is configurable in increments of 5 beyond this point. 100% is the highest possible setting, and effectively does not apply any update throttling at all.

How to change your throttle level

To adjust agent update throttling:

1. On the Agents page of the Data Collection Management tab in the Insight Platform, use the dropdown in the upper left corner of the screen to select the organization you want to configure. If you only have access to 1 organization, it will already be selected.
2. In the Agent Management interface, click Settings in the upper right corner of the screen, then click Agent Update Throttling.
3. Use the slider to select the throttle percentage you require.
4. Click Save.
   • If your setting is higher than 50%, an alert will prompt you to confirm your decision. Click Save New Setting to finish.

Automatic Insight Agent update controls

The Insight Agent receives regular software updates for operational stability and efficiency. The Automatic Agent Updates panel in Agent Management provides configuration options that govern how these updates apply to agents in each of your organizations. Use these options to turn automatic updates on or off, lock your agents to a specific software version, or test a subset of your agents on a newer software version before applying it across an organization.

By default, all version-compliant agents in an organization update automatically when a software update is available.

How to turn automatic updates on or off

You can turn automatic updates on or off for all agents in an organization:

1. On the Agents page of the Data Collection Management tab in the Insight Platform, use the dropdown in the upper left corner of the screen to select the organization you want to configure. If you only have access to 1 organization, it will already be selected.
2. In the Agent Management interface, click Settings in the upper right corner of the screen, then click Automatic Agent Updates.
3. On the Organization tab, select the appropriate option to turn automatic updates on or off.
   • If you are turning automatic updates on, select Keep me on the latest version.
4. Click Save.

How to lock your agents on a specific software version

When automatic updates are turned on, Agent Management allows you to lock all agents to a specific software version as an additional option. Automatic updates will still take place for all agents in the organization, but only to the version you select.

This version locking capability cannot downgrade an agent's software to a prior version. It only prevents an agent from updating to a later version than its current one.

When version locking your agents for the first time, only the current agent version is available as an option. After the version lock is saved, this marks the beginning of a version history that you can work with as subsequent agent versions are released. You can then use this history to update all agents in your organization to a later specific version at a later time, or create a test set.

Version history characteristics

Your version history is limited to a maximum of 3 options:

• The 2 latest Insight Agent software versions (if available)
• The version of the current lock you have applied

As new versions of the Insight Agent are released, the options shown for the 2 latest versions will change, but your version lock will remain the same.

To version lock all agents in an organization:

1. On the Organization tab, select Enable automatic updates.
   • If you're version locking for the first time, select the version marked (latest).
   • If you're changing an existing version lock to a later specific version, choose between the 2 recent agent versions listed that all agents should now accept. Be aware that this restarts your existing version history.
2. Click Save.

A banner will indicate if the setting change was successful.

Create an Insight Agent test set

When a version lock is enforced for an organization, you can choose to update a subset of your agents to 1 of the 2 latest software versions in your version history (if later versions are available). Creating a test set in this way allows you to test newer versions of the agent software in your environment before allowing all agents to update organization-wide.

Test set membership is determined by queries and filters you apply to your Agents table. Only 1 test set can exist at a time.

To create a test set for agents in an organization:

1. On the Agents page of the Data Collection Management tab in the Insight Platform, use the dropdown in the upper left corner of the screen to select the organization you want to configure. If you only have access to 1 organization, it will already be selected.
2. In the Agent Management interface, apply queries and filters to refine your Agents table to those you want to include in your test set.
3. Click Settings in the upper right corner of the screen, then click Automatic Agent Updates.
4. Click the Test Set tab.
5. Choose one of the available software versions in your history to which your test set agents should update.
6. Click Save. Your test set agents will automatically update to the version you selected.

How to promote a test set version

If you're ready to apply the version of your test set to all agents in the organization, you can do so directly from the Test Set tab by selecting Yes, update all agents. This action clears the existing test set and immediately starts the update process for all agents in the organization subject to your update throttle settings. At this time, you can configure a new test set if you need to.

How to clear a test set

If you decide not to move forward with the test set version for all agents in the organization, you can clear the test set from the Test Set tab by selecting No, clear this test. This action allows you to configure a new test set to work with if you need to. As noted in the preceding section, clearing a test set does not revert those agents to a prior software version.

Insight Agent retention periods

Agent Management keeps track of all Insight Agents you have deployed as long as they stay in communication with the Insight Platform. If an agent goes too long without communicating with the Insight Platform, Agent Management will stop tracking it. Any agents that are removed from Agent Management in this way will automatically reappear if they resume communicating with the Insight Platform at a later time.

The maximum time duration that Agent Management will continue tracking an agent that has stopped communicating is determined by a "retention period" that you can configure. 3 options are available:

• 30 days (default)
• 15 days
• 7 days

How to change your retention period

To change your Agent Management retention period:

1. On the Agents page of the Data Collection Management tab in the Insight Platform, use the dropdown in the upper left corner of the screen to select the organization you want to configure. If you only have access to 1 organization, it will already be selected.
2. In the Agent Management interface, click Settings in the upper right corner of the screen, then click Agent Retention Period.
3. Select the new retention period you want to apply.
4. Click Save.
5. A window appears asking you to confirm your decision. Click Set New Retention Period to finish.
   • As indicated by the confirmation window, shortening your retention period from the current setting will cause Agent Management to immediately start removing any agents that have not communicated with the Insight Platform within the new period.
   • This setting is only adjustable once every 3 hours.