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 Vulnerability Management (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 Vulnerability Management (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.

Agent Test Sets

Test sets allow you to organize assets that have the Insight Agent installed into logical groupings and apply configuration policies consistently across all members of a group. This capability streamlines agent management for teams operating in complex or large environments. Create test sets 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. Multliple test sets can exist at a time.

You must be a Platform Admin or Product Admin to create a test set.

Access your test sets

1. From the Command Platform, go to Command Platform > Data Collectors > Agents.
2. Click the Test Sets tab.

Create a test set

You can test available Insight Agent versions on applicable assets by creating test sets. Each test set can have update policies that differ from your organization-wide settings.

1. From the Test Sets tab, click Create test set.
   The Create Test Set modal appears.
2. Enter a unique name and description.
3. Add assets to your test set now, or skip this step to add them later.
   • Click the Pencil icon beside the Assets field. A table of available agents appears.
   • Do one of the following:
     • Select individual agents by clicking the checkbox beside each one.
     • Bulk select by clicking the checkbox in the header row.
     • Use queries and filters to refine the list.
   • Click Select to confirm your choices.
4. Set the Insight Agent update policy:
   • By default, Automatic updates is enabled.
   • To lock the test set to a specific version, turn off Automatic updates, then choose the version you want to lock to.
5. Click Create.

Modify a test set

You can update the name, description, agents, or update policy for any existing test set from the Test Sets tab or within an individual test set.

Edit test set details

1. From the Test Sets tab, locate the test set you want to update.
2. Click the vertical ellipsis (⋮) icon and select Test Set Details.
3. Update the name or description as needed.
4. Click Save.

Change the Insight Agent update policy

1. From the Test Sets tab, locate the test set you want to update.
2. Click the vertical ellipsis (⋮) icon and select Policies.
3. Click Edit.
4. Update the policy settings.
5. Click Save.

Add or remove agents from a test set

1. Open the test set.
2. In the menu, select Insight Agents, then click Manage Insight Agents.
3. Use the checkboxes to select or deselect agents.
4. Click Select to confirm your changes.

Delete a test set

1. From the Test Sets tab or the test set details page, locate the test set you want to delete.
2. Click the vertical ellipsis (⋮) icon and select Delete Test Set.
3. Confirm the deletion.

Note: Deleting a test set is permanent. All previously associated Insight Agents will revert to the organization’s default update settings.

Test Sets Quick Reference

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.