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.

Insight Platform-managed agent updates

If you want the Insight Platform to be responsible for managing the update process for all agents you have deployed for an organization, Agent Management provides an update manager you can configure to that effect in the Managed Agent Updates setting. When turned on, the Insight Platform will update your agents and all their included independent components according to the strategy you specify.

These update strategies include:

• Update all agents automatically as soon as a new version is available.
• Lock all agents to a specific version.
  • Agents will not update to a later version beyond the lock you select, even if a later version is available.
  • Any agent running a version prior to the locked version will still be subject to an update to stay current with the locked version.
  • Applying a version lock also allows you to configure a test set as newer agent versions are released.

If you choose to update all agents automatically, you can configure an agent or a group of agents running version 4.0.3 and higher to not update by including -disable-updates=True in the configuration script command. Read more about this installation option here.

How to turn the update manager on or off

You can turn the update manager 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 Managed Agent Updates.
3. On the All Agents tab, select the appropriate option to turn the update manager on or off.
   • If you are turning the update manager on, select an update strategy that the update manager should follow going forward.

Update strategy 1: update all agents automatically

Select the Update all agents to the latest version when available (automatic updates) strategy to allow the update manager to update all the agents that are attached to this organization to the latest available version, and continue to do so going forward.

Update strategy 2: lock your agents on a specific software version

When the update manager is turned on, Agent Management allows you to lock all agents to a specific software version. The update manager will still update any agents running an earlier version, 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 All Agents tab, browse to the Select an update strategy section:
   • If you're applying a version lock for the first time, select Lock all agents to version x.x.x (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 Managed 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.

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.

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.