Upgrading Integrity Monitor

Tasks for the July 2022 upgrade

The July 2022 release of Integrity Monitor changes how labeled events are stored, how watchlists and monitors are targeted, and the sensors used, which requires certain manual changes. This upgrade does not automatically redeploy monitors and rules or deploy watchlists. Complete all upgrade-related tasks before you redeploy monitors and rules and deploy watchlists for the first time.

Review changes related to removal of server-side storage of labels

During the upgrade, the following changes occur:

Legacy monitors that store events on the server (formerly known as basic monitors) are migrated to standard monitors.
Legacy rules (formerly known as basic rules) are removed. You must recreate rules and apply them to migrated monitors to continue automatically labeling events for migrated monitors.
The Reports tab is removed from legacy monitors.
Manual labeling controls are removed from legacy monitors.
Any existing labels are removed from events.

Update sensors in saved questions

Because Integrity Monitor now uses a different database to store recorded events, legacy sensors that were used with earlier versions are deprecated. Deprecated sensors remain available and continue to return events from before the upgrade, until those events are pruned from the database. Only the legacy sensors return these legacy events, and only the new sensors return new events that occur after you first deploy monitors after the upgrade. Events are pruned from an endpoint database according to the Monitor Pruning Age that is configured for the monitor that is deployed to that endpoint, which is six months by default. An endpoint automatically deletes the legacy event database and removes legacy Client Management tools after the full time of the Monitor Pruning Age has passed since you first deployed monitors after the upgrade.

The Monitor Pruning Age determines how long Client Management stores events in the endpoint database. Auditing this database requires the assistance of Tanium Support. When asking questions using Client Management sensors, you can view events as old as 250 hours.

To collect new event data, you must replace each sensor as directed in saved questions, including those used with Connect.

New sensors use different parameters and return data with groupings and columns that are different from legacy sensors. In addition to replacing sensors, you must review and update any saved question, connection, or logic at a connection destination that depends on the groupings and columns in the deprecated sensor. For more information about new event sensors, see Use sensors to view events or event counts. For more information about updating connections, see the Tanium Connect User Guide.

Deprecated Sensor	Replacement Sensor
Integrity Monitor - Coverage Status	Client Extensions - Status or Integrity Monitor - Tools Version
Integrity Monitor Endpoint Config Monitor Status	Client Extensions - Status
Integrity Monitor Endpoint Config Priority	Client Extensions - Status
Integrity Monitor Endpoint ID	Client Extensions - Endpoint ID
Integrity Monitor Endpoint Process Restart Needed	Client Extensions - Status
Integrity Monitor Endpoint Tools Status	Client Extensions - Status or Integrity Monitor - Tools Version
Integrity Monitor File Events Details	Integrity Monitor - Monitor Events
Integrity Monitor File Events Overview	Integrity Monitor - Monitor Events
Integrity Monitor Filtered Events Count	Integrity Monitor - Event Count
Integrity Monitor Filtered File Events Details	Integrity Monitor - Monitor Events
Integrity Monitor Filtered File Events Overview	Integrity Monitor - Monitor Events
Integrity Monitor Labeled File Events Details	Integrity Monitor - Monitor Events
Integrity Monitor Unlabeled File Events Details	Integrity Monitor - Monitor Events Unlabeled
Integrity Monitor Unlabeled File Events Overview	Integrity Monitor - Monitor Events Unlabeled

After the Monitor Pruning Age has passed for all monitors and all legacy events have been pruned, delete the deprecated sensors to avoid confusion.

Add filters to saved questions for change types

In earlier versions of Integrity Monitor, you could select specific change types for Client Management to record for each path in a watchlist. Integrity Monitor now monitors all change types for all paths. If you want to limit saved questions to specific change types, including saved questions used with Connect, you must update those saved questions with a filter. For example, the following question returns only file creation events:

Get Integrity Monitor - Monitor Events[10,0,360,15,0,""] having Integrity Monitor - Monitor Events:Change Type equals CreateNewFile from all machines

Review monitor and watchlist targeting

Earlier versions of Integrity Monitor handled targeting exclusively through monitors, and you assigned watchlists to monitors for deployment. Now you target and deploy watchlists and monitors separately, which lets you use fewer monitors and use watchlist targeting to more closely control which paths Integrity Monitor watches on each endpoint. You no longer assign watchlists to monitors, though each endpoint that you target in a watchlist must also be targeted in a monitor for the watchlist to take effect.

The upgrade automatically adds computer groups to the targeting for each watchlist, based on the targeting of the monitors to which that watchlist was assigned in the earlier version. Before redeploying watchlists and monitors, review the targeting of each watchlist and monitor to determine whether it needs refinement to avoid watching unnecessary paths on some endpoints.

In certain cases where multiple monitors target the same endpoint, the automatic application of watchlist targeting can cause a watchlist to apply to an endpoint where it did not apply before the upgrade.

For example, assume the following conditions applied in the earlier version of Client Management:

Watchlist 1 was assigned only to Monitor A
.
Watchlist 2 was assigned only to Monitor B
.
Both Monitor A and Monitor B targeted computer groups that contain Endpoint Z.
Monitor A was above Monitor B in the priority list.

Because Client Management deploys only one monitor to each endpoint based on the priority list, it deploys only Monitor A to Endpoint Z, and this still applies after the upgrade. However, before the upgrade, Watchlist 2 did not apply on Endpoint Z because Monitor B was not deployed there. The upgrade copies targeting from Monitor A to Watchlist 1 and from Monitor B to Watchlist 2, and because watchlists are now deployed separately from monitors, both watchlists apply to Endpoint Z after the upgrade. If you redeploy watchlists and monitors without any adjustments to targeting, Client Management now watches paths in Watchlist 2 on Endpoint Z.

If you use overlapping monitors, take extra care in reviewing watchlist targeting to avoid watching unnecessary paths on endpoints that are included in the targeting for multiple monitors.

Edit watchlists to apply narrow targeting and watch only the necessary paths on the necessary endpoints. Consolidate monitors, and target consolidated monitors as broadly as possible. Use additional monitors only to accommodate different scan settings, scan intervals, or rules.

Review monitor settings

In earlier versions of Client Management, you could select hash monitoring, event monitoring, or both for the monitoring method. Client Management now performs hash monitoring for all monitors, which uses Index CX to detect and record basic file and registry events. Monitors that were configured to perform event monitoring before the upgrade have the Collect process and user attribution information setting enabled after the upgrade. This setting uses Recorder CX to record the specific operation, as well as the associated user or process path. You can optionally disable this setting for a monitor if you do not need process and user information for events that the monitor records.

Additionally, the Install Tanium Driver setting has been removed, and Client Management now automatically installs the Tanium Driver on all targeted Windows endpoints when you deploy a monitor with the Collect process and user attribution information setting enabled.

After the driver is first installed on a targeted endpoint, you must reboot that endpoint before Client Management can record process and user information associated with file and registry operations.

Review paths that include symbolic links

Client Management now watches files and directories that are referenced by a symbolic link, if you directly specify a symbolic link in a path (including with the use of wildcard characters), whereas earlier versions watched only the symbolic link file itself. If an existing watchlist includes a path that directly specifies a symbolic link, Client Management starts watching referenced files and directories after the upgrade. If you want to continue watching only the symbolic link file itself, you can change the path to watch the parent directory that contains the symbolic link file, and specify the symbolic link file as an inclusion.

To avoid recursion, Client Management does not watch the referenced directories or files if the symbolic link is contained within a directory that the path specifies. For example, if you have a symbolic link at /my/path/directory-symlink that references /other/path/referenced-directory, then if you specify the path /my/path/directory*, Client Management watches the referenced directory /other/path/referenced-directory. If you specify the path /my/path, then Client Management watches the symbolic link file itself, but it does not watch the referenced directory.

If a watchlist includes paths that contain symbolic links but no paths that directly specify symbolic links, there is no change in behavior after the upgrade.

Review registry paths, inclusions, and exclusions that specify values

In earlier versions of Client Management, a double-backslash separator (\\) specified a registry value in a path, inclusion, or exclusion. Client Management no longer lets you specify registry values, and all values are watched for each watched key. Watchlist paths, inclusions, and exclusions are not modified for this behavior during the upgrade, but Client Management now ignores anything after two backslashes (\\) in a registry path, inclusion, or exclusion.

This change in behavior can result in Client Management watching values and subkeys that it did not watch before the upgrade. Because a value in an existing registry path, inclusion, or exclusion is now ignored, a path, inclusion, or exclusion that contains a value now indicates the key immediately preceding the double-backslash separator (\\).

This change results in the following behavior after the upgrade:

For a path that contains a value, Client Management watches the key immediately preceding the double-backslash separator (\\), all subkeys of that key unless inclusions or exclusions specify otherwise, and all values of that key and watched subkeys, regardless of inclusions or exclusions.
For an inclusion or exclusion that contains a key and a value, Client Management interprets the inclusion or exclusion as the key immediately preceding the double-backslash separator (\\).
For an inclusion or exclusion that contains only a value, Client Management ignores the inclusion or exclusion.

If you use registry paths, inclusions, or exclusions that specify values, carefully review those items and make adjustments to avoid watching additional subkeys unnecessarily.

Review path inclusions and exclusions that include wildcard characters

In earlier versions of Client Management, a single asterisk wildcard character (*) matched path separators when used in an inclusion or exclusion. Now a single asterisk (*) does not match path separators, and two asterisks together (**) do include path separators. During the upgrade, each asterisk in an inclusion or exclusion is automatically changed to a pair of asterisks. Because this automatic change maintains the previous behavior for inclusions and exclusions, no manual updates are necessary. However, make sure you use two asterisks (**) in an inclusion or exclusion to match path separators when you add new inclusions or exclusions or import paths from a file.

Deploy monitors, watchlists, and rules

This upgrade does not automatically redeploy monitors and rules or deploy watchlists. After you complete all upgrade-related tasks and review your configuration, you must manually deploy monitors, watchlists, and rules. For more information, see Deploy monitors, Deploy watchlists, and Deploy rules.

You must deploy both a monitor and at least one watchlist to each endpoint for Client Management to watch paths on that endpoint. You can ask questions to identify endpoints that are missing either a monitor or watchlist:

To identify endpoints to which you have deployed one or more watchlists but no monitor, ask the question: Get Computer Name and Client Extensions - Status matches "^integrity_monitor\|monitor_id\|.*$" from all machines with Client Extensions - Status matches "^integrity_monitor\|monitor_id\|0$".
To identify endpoints to which you have deployed a monitor but no watchlists, ask the question: Get Computer Name and Client Extensions - Status matches "^integrity_monitor\|monitor_id\|[^0].*$" and Integrity Monitor - Active Watchlists from all machines with ( Client Extensions - Status matches "^integrity_monitor\|.*$" and Integrity Monitor - Active Watchlists contains No Results Found ).

Import the Integrity Monitor board in Trends

Because of a known issue, the Trends board for Client Management is not updated during the upgrade. You must manually import the Client Management board in Trends.

The known issue does not affect the panels on the Client Management Overview page.

From the Main menu, go to Modules > Trends.
From the Trends menu, click Boards.
Go to > Import Gallery.
Select the Integrity Monitor board and click Validate.
Click Import to complete the import.

For the steps to upgrade Integrity Monitor, see Tanium Console User Guide: Import, re-import, or update specific solutions. After the upgrade, verify that the correct version is installed. See Verify Integrity Monitor version.

Read the release notes for a particular version before you upgrade Integrity Monitor.

Perform some basic tests in Integrity Monitor before and after the upgrade to ensure that all operations are working as expected.

Upgrading from a version earlier than 3.0

Integrity Monitor 3.0 and later changes how labeled events are stored, how watchlists and monitors are targeted, and the sensors used, which requires certain manual changes. An upgrade from a version earlier than 3.0 to 3.0 or later does not automatically redeploy monitors and rules, regardless of the Automatically deploy monitors and rules when upgrading the module setting in the earlier version (see Redeploy monitors, watchlists, and rules), or deploy watchlists. Complete all upgrade-related tasks before you redeploy monitors and rules and deploy watchlists for the first time.

Review changes related to removal of server-side storage of labels

In Integrity Monitor 3.0 and later, all labels for events are stored on endpoints. To support this functionality, when you upgrade from a version earlier than 2.4, all existing labels become global labels. Any user-defined custom labels that were assigned to specific monitors are migrated to a matching global label. Any custom labels that have conflicting names are merged into a single global label. (These changes already occurred if you upgraded to version 2.4 or later.)

Additionally, when you upgrade from a version earlier than 3.0, the following changes occur:

Legacy monitors that store events on the server (formerly known as basic monitors) are migrated to standard monitors.
Legacy rules (formerly known as basic rules) are removed. You must recreate rules and apply them to migrated monitors to continue automatically labeling events for migrated monitors.
The Reports tab is removed from legacy monitors.
Manual labeling controls are removed from legacy monitors.
Any existing labels are removed from events.

Update sensors in saved questions

Because Integrity Monitor 3.0 and later uses a different database to store recorded events, legacy sensors that were used with versions earlier than 3.0 are deprecated. Integrity Monitor 3.0 or later does not install these sensors in a new installation. If you are upgrading from a version earlier than 3.0, deprecated sensors remain available and continue to return events from before the upgrade, until those events are pruned from the database. Only the legacy sensors return these legacy events, and only the new sensors return new events that occur after you first deploy monitors after the upgrade. Events are pruned from an endpoint database according to the Monitor Pruning Age that is configured for the monitor that is deployed to that endpoint, which is six months by default. An endpoint automatically deletes the legacy event database and removes legacy Client Management tools after the full time of the Monitor Pruning Age has passed since you first deployed monitors after the upgrade.

To collect new event data, you must replace each sensor as directed in saved questions, including those used with Connect.

Deprecated Sensor	Replacement Sensor
Integrity Monitor - Coverage Status	Client Extensions - Status or Integrity Monitor - Tools Version
Integrity Monitor Endpoint Config Monitor Status	Client Extensions - Status
Integrity Monitor Endpoint Config Priority	Client Extensions - Status
Integrity Monitor Endpoint ID	Client Extensions - Endpoint ID
Integrity Monitor Endpoint Process Restart Needed	Client Extensions - Status
Integrity Monitor Endpoint Tools Status	Client Extensions - Status or Integrity Monitor - Tools Version
Integrity Monitor File Events Details	Integrity Monitor - Monitor Events
Integrity Monitor File Events Overview	Integrity Monitor - Monitor Events
Integrity Monitor Filtered Events Count	Integrity Monitor - Event Count
Integrity Monitor Filtered File Events Details	Integrity Monitor - Monitor Events
Integrity Monitor Filtered File Events Overview	Integrity Monitor - Monitor Events
Integrity Monitor Labeled File Events Details	Integrity Monitor - Monitor Events
Integrity Monitor Unlabeled File Events Details	Integrity Monitor - Monitor Events Unlabeled
Integrity Monitor Unlabeled File Events Overview	Integrity Monitor - Monitor Events Unlabeled

After the Monitor Pruning Age has passed for all monitors and all legacy events have been pruned, delete the deprecated sensors to avoid confusion.

Add filters to saved questions for change types

In Integrity Monitor versions earlier than 3.0, you could select specific change types for Client Management to record for each path in a watchlist. Integrity Monitor 3.0 and later monitors all change types for all paths. If you want to limit saved questions to specific change types, including saved questions used with Connect, you must update those saved questions with a filter. For example, the following question returns only file creation events:

Get Integrity Monitor - Monitor Events[10,0,360,15,0,""] having Integrity Monitor - Monitor Events:Change Type equals CreateNewFile from all machines

Review monitor and watchlist targeting

Integrity Monitor versions earlier than 3.0 handled targeting exclusively through monitors, and you assigned watchlists to monitors for deployment. In Integrity Monitor 3.0 and later, you target and deploy watchlists and monitors separately, which lets you use fewer monitors and use watchlist targeting to more closely control which paths Integrity Monitor watches on each endpoint. You no longer assign watchlists to monitors, though each endpoint that you target in a watchlist must also be targeted in a monitor for the watchlist to take effect.

When you upgrade to Integrity Monitor 3.0 or later, the upgrade automatically adds computer groups to the targeting for each watchlist, based on the targeting of the monitors to which that watchlist was assigned in the earlier version. Before redeploying watchlists and monitors, review the targeting of each watchlist and monitor to determine whether it needs refinement to avoid watching unnecessary paths on some endpoints.

For example, assume the following conditions applied in the earlier version of Client Management:

Watchlist 1 was assigned only to Monitor A
.
Watchlist 2 was assigned only to Monitor B
.
Both Monitor A and Monitor B targeted computer groups that contain Endpoint Z.
Monitor A was above Monitor B in the priority list.

Because Client Management deploys only one monitor to each endpoint based on the priority list, it deploys only Monitor A to Endpoint Z, and this still applies in Client Management 3.0 and later. However, before the upgrade, Watchlist 2 did not apply on Endpoint Z because Monitor B was not deployed there. The upgrade to Client Management 3.0 or later copies targeting from Monitor A to Watchlist 1 and from Monitor B to Watchlist 2, and because watchlists are now deployed separately from monitors, both watchlists apply to Endpoint Z after the upgrade. If you redeploy watchlists and monitors without any adjustments to targeting, Client Management now watches paths in Watchlist 2 on Endpoint Z.

If you use overlapping monitors, take extra care in reviewing watchlist targeting to avoid watching unnecessary paths on endpoints that are included in the targeting for multiple monitors.

Review monitor settings

In Client Management versions earlier than 3.0, you could select hash monitoring, event monitoring, or both for the monitoring method. Client Management 3.0 and later performs hash monitoring for all monitors, which uses Index CX to detect and record basic file and registry events. Monitors that were configured to perform event monitoring before the upgrade have the Collect process and user attribution information setting enabled after the upgrade. This setting uses Recorder CX to record the specific operation, as well as the associated user or process path. You can optionally disable this setting for a monitor if you do not need process and user information for events that the monitor records.

Additionally, the Install Tanium Driver setting has been removed, and Client Management 3.0 and later automatically installs the Tanium Driver on all targeted Windows endpoints when you deploy a monitor with the Collect process and user attribution information setting enabled.

Review paths that include symbolic links

Client Management 3.0 and later watches files and directories that are referenced by a symbolic link, if you directly specify a symbolic link in a path (including with the use of wildcard characters), whereas versions earlier than 3.0 watched only the symbolic link file itself. If an existing watchlist includes a path that directly specifies a symbolic link, Client Management starts watching referenced files and directories after the upgrade. If you want to continue watching only the symbolic link file itself, you can change the path to watch the parent directory that contains the symbolic link file, and specify the symbolic link file as an inclusion.

If a watchlist includes paths that contain symbolic links but no paths that directly specify symbolic links, there is no change in behavior after the upgrade.

Review registry paths, inclusions, and exclusions that specify values

In Client Management versions earlier than 3.0, a double-backslash separator (\\) specified a registry value in a path, inclusion, or exclusion. Client Management 3.0 and later does not let you specify registry values, and all values are watched for each watched key. Watchlist paths, inclusions, and exclusions are not modified for this behavior during the upgrade, but Client Management 3.0 and later ignores anything after two backslashes (\\) in a registry path, inclusion, or exclusion.

This change in behavior can result in Client Management watching values and subkeys that it did not watch before the upgrade. Because a value in an existing registry path, inclusion, or exclusion is ignored after the upgrade, a path, inclusion, or exclusion that contains a value indicates the key immediately preceding the double-backslash separator (\\) after the upgrade.

This change results in the following behavior after the upgrade:

For a path that contains a value, Client Management watches the key immediately preceding the double-backslash separator (\\), all subkeys of that key unless inclusions or exclusions specify otherwise, and all values of that key and watched subkeys, regardless of inclusions or exclusions.
For an inclusion or exclusion that contains a key and a value, Client Management interprets the inclusion or exclusion as the key immediately preceding the double-backslash separator (\\).
For an inclusion or exclusion that contains only a value, Client Management ignores the inclusion or exclusion.

If you use registry paths, inclusions, or exclusions that specify values, carefully review those items and make adjustments to avoid watching additional subkeys unnecessarily.

Review path inclusions and exclusions that include wildcard characters

In Client Management versions earlier than 3.0, a single asterisk wildcard character (*) matched path separators when used in an inclusion or exclusion. In Integrity Monitor 3.0 and later, a single asterisk (*) does not match path separators, and two asterisks together (**) do include path separators. When you upgrade from a version earlier than 3.0 to version 3.0 or later, each asterisk in an inclusion or exclusion is automatically changed to a pair of asterisks. Because this automatic change maintains the previous behavior for inclusions and exclusions, no manual updates are necessary. However, make sure you use two asterisks (**) in an inclusion or exclusion to match path separators when you add new inclusions or exclusions or import paths from a file.

Deploy monitors, watchlists, and rules

An upgrade from a version earlier than 3.0 to 3.0 or later does not automatically redeploy monitors and rules, regardless of the Automatically deploy monitors and rules when upgrading the module setting in the earlier version (see Redeploy monitors, watchlists, and rules), or deploy watchlists. After you complete all upgrade-related tasks and review your configuration, you must manually deploy monitors, watchlists, and rules. For more information, see Deploy monitors, Deploy watchlists, and Deploy rules.

To identify endpoints to which you have deployed one or more watchlists but no monitor, ask the question: Get Computer Name and Client Extensions - Status matches "^integrity_monitor\|monitor_id\|.*$" from all machines with Client Extensions - Status matches "^integrity_monitor\|monitor_id\|0$".
To identify endpoints to which you have deployed a monitor but no watchlists, ask the question: Get Computer Name and Client Extensions - Status matches "^integrity_monitor\|monitor_id\|[^0].*$" and Integrity Monitor - Active Watchlists from all machines with ( Client Extensions - Status matches "^integrity_monitor\|.*$" and Integrity Monitor - Active Watchlists contains No Results Found ).

Import the Integrity Monitor board in Trends

Because of a known issue, the Trends board for Client Management is not updated during the upgrade. You must manually import the Client Management board in Trends.

The known issue does not affect the panels on the Client Management Overview page.

From the Main menu, go to Modules > Trends.
From the Trends menu, click Boards.
Go to > Import Gallery.
Select the Integrity Monitor board and click Validate.
Click Import to complete the import.

Redeploy monitors, watchlists, and rules

After you upgrade Integrity Monitor, all monitors, rules, and watchlists must be redeployed. The default configuration automatically redeploys all items after an upgrade, or if the automatic deployment setting is not configured, you must manually redeploy them: see Deploy monitors, Deploy watchlists, and Deploy rules.

If you do not redeploy monitors, watchlists, and rules, the system might be left in a nonworking state.

Configure automatic redeployment of monitors

From the Integrity Monitor Overview page, click Settings .
Click the General Settings tab.
In the Automatic Deployment on Upgrade section, select Automatically deploy monitors, watchlists, and rules when upgrading the module.

Verify Integrity Monitor version

After you import or upgrade Integrity Monitor, verify that the correct version is installed:

Refresh your browser.
From the Main menu, go to Modules > Integrity Monitor to open the Integrity Monitor Overview page.
To display version information, click Info .