Managing watched paths with watchlists

Watchlists define a set of files, directories, and Windows registry paths that you want to monitor for changes. Create specific watchlists that target the endpoints where Integrity Monitor should watch the specified paths.

Integrity Monitor includes watchlist templates that contain critical files and directories that are typically monitored for Windows and Linux, and registry paths that are typically monitored for Windows. Create your own watchlists, or create watchlists from the included templates and then add or remove paths to tailor the watchlists to your environment.

You can configure each path in a watchlist to trigger events for changes in files or registry keys. Integrity Monitor records create, write, delete, or rename operations for files, directories, or registry keys, as well as changes to permission for files or directories.

Use monitors to configure scan settings for endpoints. Each endpoint that you target in a watchlist must also be targeted in a monitor for the watchlist to take effect when you deploy watchlists and monitors. 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$". For more information about monitors, see Managing scan settings with monitors.

Create or edit a watchlist

1. From the Integrity Monitor menu, go to Watchlists.
2. Click Create Watchlist, or click Edit in the row for an existing watchlist that you want to edit.

3. Enter a Name and Description for the watchlist.

4. For Path Style, select Windows or Unix.

   • The target endpoint operating system and path style must be consistent within a watchlist. For example, you cannot add a Windows file path or a Windows registry path to a watchlist that uses the Unix path style.

   • You cannot edit the path style of a watchlist while it is assigned to a monitor.

5. (Optional) In the Watchlist Templates section, select templates from which to add initial paths to the watchlist.

6. In the Targeting section, click Select Computer Groups, select the computer groups to target, and click Save.

7. Click Create (for a new watchlist) or Save (for an existing watchlist).

If you edit the targeting for an existing watchlist, you must redeploy all watchlists. See Deploy watchlists.

Add and edit paths

After you create a watchlist, you add paths to determine the files, directories, and Windows registry paths that are monitored. If you used a template when creating a watchlist, you can edit the paths that were defined in the template.

Paths, inclusions, and exclusions

The paths you add to a watchlist determine the files, directories, and registry paths that are monitored on endpoints where the watchlist is deployed. In a path, you can use wildcard characters within a directory, file, or registry key name, but you cannot use wildcard characters to match path separators or specify multiple directory or subkey levels.

To refine the files, directories, and registry paths that are monitored for a watchlist, add path inclusions or path exclusions. Without inclusions or exclusions defined, the path matches all files and subdirectories in a file path or all subkeys in a registry path. By default, a file path that specifies a directory includes subdirectories recursively, and a registry path that specifies a registry key includes subkeys recursively.

If you define path inclusions, the path matches only subdirectories, files, or registry subkeys that match the inclusions.

If you define path exclusions, the path does not match subdirectories, files, or registry subkeys that match the exclusions.

Exclusions take precedence over inclusions. If you define both inclusions and exclusions, the path matches all directories, files, or registry keys that match the inclusions, except those that match exclusions.

You can also use wildcard characters in inclusions or exclusions. Use a single asterisk (*) to represent a string of characters within a directory, file, or registry key name, just as you can in a path. In inclusions or exclusions, you can use two asterisks together (**) to include path separators (and therefore multiple directory or subkey levels) in the match.

If you directly specify a symbolic link in a path (including with the use of wildcard characters), Integrity Monitor watches the directories or files that the symbolic link references. It also follows symbolic links nested within that referenced directory. To avoid recursion, Integrity Monitor does not watch the referenced directories or files if the symbolic link is contained within a directory that you specify in a path. For example, assume you have a symbolic link at /my/path/directory-symlink that references /other/path/referenced-directory. If you specify the path /my/path/directory*, Integrity Monitor watches the referenced directory /other/path/referenced-directory, and it also follows any additional symbolic links contained within /other/path/referenced-directory. If you specify the path /my/path, then Integrity Monitor watches the symbolic link file itself, but it does not watch the referenced directory.

For more information and examples, see Reference: Watchlist path inclusions and exclusions.

Add a file path

Add file paths to a watchlist to define the files and directories that you want to monitor for changes on certain endpoints.

1. From the Integrity Monitor menu, go to Watchlists.
2. Go to Watchlists > [watchlist name].
3. (For Windows watchlist path style) Make sure the File Paths tab is active.
4. Click Add Paths > New.
5. In the Details section, provide the information for the path:

   • Enter the absolute path for the file or directory.

     • You can use wildcard characters within a directory or file name in a path, but you cannot use wildcard characters to specify path separators or multiple directory levels. For example, if you specify the path /a/*/z, the path a/b/z is monitored, but not a/b/c/z.
     • If you specify a root directory, you must include the slash. For example: D:\

   • (For Windows watchlist path style) In the Change Type section, if you want to record process and user information for permission changes, select Permission.

6. In the Inclusions and Exclusions section, expand the Path Inclusions or Path Exclusions section to add path inclusions or exclusions.

   In inclusions or exclusions, you can use two asterisks together (**) to include path separators (and therefore multiple directory or subkey levels) in the match. For example, if the path is /a and an inclusion is **/z, this inclusion matches /a/b/z, /a/b/c/z, or /a/b/c/d/e/f/g/z. For more information, see Reference: Watchlist path inclusions and exclusions.

   If a symbolic link is referenced by a path inclusion or exclusion, it applies only to the symbolic link name itself, not the target of the link.

   To add an additional path inclusion or exclusion, click Add in the corresponding section.

   To delete an inclusion or exclusion, click .

7. Click Add Path.

(Windows) Add a registry path

Add registry paths to a watchlist to define the registry keys that you want to monitor for changes on certain endpoints. Registry paths are available only for watchlists with a Windows path style.

1. From the Integrity Monitor menu, go to Watchlists.
2. Go to Watchlists > [watchlist name]. Click the Registry Paths tab.
3. Click Add Paths > New.
4. For Path, enter the absolute path for the registry key.

   You can use wildcard characters within a key name in a path, but you cannot use them to specify path separators or multiple key levels. For example, if you have a path HKEY_LOCAL_MACHINE\*\z, the path HKEY_LOCAL_MACHINE\a\z is monitored, but not HKEY_LOCAL_MACHINE\a\b\z.

   For additional considerations for registry paths, see Considerations for registry paths.

5. In the Inclusions and Exclusions section, expand the Path Inclusions or Path Exclusions section to add path inclusions or exclusions.

   In inclusions or exclusions, you can use two asterisks together (**) to include path separators (and therefore multiple directory or subkey levels) in the match. For example, if the path is HKEY_LOCAL_MACHINE\a and an inclusion is **\z, this inclusion matches HKEY_LOCAL_MACHINE\a\b\z, HKEY_LOCAL_MACHINE\a\b\c\z, or HKEY_LOCAL_MACHINE\a\b\c\d\e\f\g\z. For more information, see Reference: Watchlist path inclusions and exclusions.

   To add an additional path inclusion or exclusion, click Add in the corresponding section.

   To delete an inclusion or exclusion, click .

6. Click Add Path.

Considerations for registry paths

Determining watched subkeys

A path matches all subkeys recursively under a key or keys that are specified by the path. For example, if you specify the path HKEY_LOCAL_MACHINE\a, then the path matches all subkeys of the a key (such as HKEY_LOCAL_MACHINE\a\x, HKEY_LOCAL_MACHINE\a\x\y, and HKEY_LOCAL_MACHINE\a\z), unless you otherwise exclude them. If the Collect process and user attribution information setting is enabled in the monitor that you deploy to that endpoint, all values of matching subkeys are watched.

You cannot monitor an entire subtree, such as HKEY_LOCAL_MACHINE, and you cannot specify individual values within a key.

Using an abbreviation for a subtree

You can use the abbreviation for the subtree in a path. Integrity Monitor expands the subtree name when you save your changes. For example, you can enter the path HKLM\MyKey, which is saved as HKEY_LOCAL_MACHINE\MyKey.

Subtree name	Abbreviation
HKEY_LOCAL_MACHINE	HKLM
HKEY_USERS	HKU

Using the HKEY_CURRENT_USER subtree in a path

When you add a path in the HKEY_CURRENT_USER subtree, such as HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Group Policy, Integrity Monitor changes the HKEY_CURRENT_USER subtree in the path to HKEY_USERS\* when you save your changes (for example, HKEY_USERS\*\Software\Microsoft\Windows\CurrentVersion\Group Policy). Because the Tanium Client uses the SYSTEM account, the HKEY_CURRENT_USER subtree applies to the SYSTEM account rather than the user account that is currently signed in to Windows. Using HKEY_USERS\* instead lets Integrity Monitor record events for all users, including the user account that is currently signed in to Windows.

Using a redirected registry key in a path

For 64-bit Windows, the registry redirector maps some keys, such as HKEY_LOCAL_MACHINE\SOFTWARE\, to a WOW6432Node subkey (for example, HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node) for use by 32-bit applications. When you add key paths that are redirected under WOW64, the watchlist does not automatically include the parallel key paths under the WOW6432Node keys. If you want to monitor keys under these paths, you must enter them separately.

Import a path

You can import paths to a watchlist from a file that you created in another monitoring tool, or from a template that is provided with Integrity Monitor.

Add paths from a file

Tanium provides limited support for importing paths from Tripwire configurations, Open Source HIDS Security (OSSEC) configurations, Log Correlation Engine (LCE) Client policies, or CSV files. For details about CSV formatting, see CSV format for path imports. An imported file can contain either file and directory or registry paths.

Use a backslash (\) to escape backslashes in Windows paths.

1. From the Integrity Monitor menu, go to Watchlists.
2. Go to Watchlists > [watchlist name].
3. Click Add Paths > Import From File.
4. Click Choose Files.
5. Browse to and select the path file or files and click Open.
6. Click Import to import the file or files.

CSV format for path imports

The first line of a CSV file specifies the field names and defines the order of the values in the subsequent rows. The import uses the following fields:

Field	Description
path	The file, directory, or registry path
ops_permission	Whether to monitor a Windows file path for changes in permission (on or off)
excludes_spec	An exclusion to apply to the path

You can add additional exclusions to a path by adding subsequent lines with all fields empty except for excludes_spec. These lines inherit the blank field values from the parent entry.

The following example CSV file demonstrates the structure to use to import paths to Integrity Monitor.

path,ops_permission,excludes_spec
C:\\autoexec.bat,on,
C:\\Windows\\logs,off,\\**
C:\\Windows,on,NtServicePackUninstall
,,NtServicePackUninstall\\**
,,NtUninstall
,,NtUninstall\\**
,,Help
,,Help\\**
C:\\Windows\\assembly,on,\\**

In the preceding example, the following line adds the path C:\autoexec.bat and enables monitoring file permission changes:

C:\\autoexec.bat,on,

The following line adds the path C:\Windows\logs, disables monitoring file permission changes, and adds the exclusion \**, which excludes any subdirectories within C:\Windows\logs:

C:\\Windows\\logs,off,\\**

The following lines add the path C:\Windows, enable monitoring file permission changes, and add exclusions for three directories and their subdirectories (NtServicePackUninstall, NtUninstall, and Help):

C:\\Windows,on,on,on,on,on,NtServicePackUninstall
,,NtServicePackUninstall\\**
,,NtUninstall
,,NtUninstall\\**
,,Help
,,Help\\**

The following line adds the path C:\Windows\assembly, enables monitoring file permission changes, and adds the exclusion \**:

C:\\Windows\\assembly,on,\\**

Add paths from templates

Integrity Monitor includes watchlist templates that contain critical files and directories that are typically watched for Windows and Linux. You can use these templates when creating new watchlists, and you can also use them to add paths to existing watchlists.

1. From the Integrity Monitor menu, go to Watchlists.
2. Go to Watchlists > [watchlist name].
3. Click Add Paths > Import From Templates.
4. Select one or more templates and click Import.

Use a template as a starting point, and modify the watchlist to suit the needs of your environment. Monitors that use the default watchlists from the included templates might record a significant number of events that are not necessarily cause for concern.

(Windows path style only) Update the Permission change type setting for multiple paths

1. From the Integrity Monitor menu, go to Watchlists.
2. Go to Watchlists > [watchlist name].
3. Select one or more paths.
4. Click Manage Change Type.
5. Update the selection for Permission and click Save.

Review watchlist details

On the Watchlists page, click Expand for a watchlist to view the monitors that target the same endpoints, computer groups that the watchlist targets, and the revision number of the watchlist.

To view paths for a watchlist, click the name of the watchlist. From the details page for the watchlist, click Expand for a path to view inclusions and exclusions for that path.

To determine the watchlists that apply to particular endpoints, ask a question using the Integrity Monitor - Active Watchlists sensor.

Deploy watchlists

After you create, edit, or delete watchlists, you must deploy all watchlists to the endpoints. A Deploy Now banner appears, and Pending Deployment (new watchlists), Needs Deployment (changed watchlists), or Pending Deletion (deleted watchlists) appears in the Status column for the watchlist on the Watchlists page.

If you have more than one watchlist, all watchlists are deployed each time you deploy watchlists.

When you deploy a watchlist, you deploy all watchlists. When you create, edit, or delete a watchlist, you are prompted to deploy all watchlists. For best results, create all planned watchlists, and then deploy them at the same time. If you deploy a watchlist with restricted management rights, the set of management rights is applied to all deployed watchlists. The watchlist or Integrity Monitor tools are removed from any endpoints that are not a member of the updated computer management group.

You cannot deploy watchlists to endpoints with action locks turned on.on, unless Endpoint Configuration is configured to ignore action locks. For more information, see Install and configure Tanium Endpoint Configuration and Tanium Console User Guide: Managing action locks.

1. Click Deploy Now in the banner or Deploy Watchlists on the Watchlists page.
2. Confirm the deployment. If you have more than one watchlist, all watchlists are deployed.

If you enabled Endpoint Configuration approval, watchlist deployment must be approved in Endpoint Configuration before watchlists deploy to endpoints.

Watchlists are automatically redeployed when the Integrity Monitor module is upgraded in Tanium™ Cloud, which could occur without prior notice. If you have not yet deployed a newly created watchlist, it is automatically deployed if the module is upgraded before you manually deploy it.

Each endpoint that you target in a watchlist must also be targeted in a monitor for the watchlist to take effect when you deploy watchlists and monitors. For more information about monitors, see Managing scan settings with monitors.

Export and import watchlists

You can export a watchlist to transfer it to another environment (for example, if you created the watchlist in a QA or lab environment and you want to move it to a production environment) or for backup.

Export a watchlist

1. From the Integrity Monitor menu, go to Watchlists.
2. Click the name of a watchlist to open the details page for that watchlist.

3. Click Export Watchlist .

   The exported watchlist downloads in your browser in JSON format.

Import a watchlist

1. From the Integrity Monitor menu, go to Watchlists.
2. Click Import Watchlist .
3. Click Choose File.
4. Browse to the watchlist file and click Open.
5. Click Import to import the file.