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.

  • On Windows endpoints, the Audit File System permission must be configured in order to record permission changes. For more information, see Prepare Endpoints.

  • You must enable the Collect process and user attribution information setting in the monitor that you deploy to an endpoint to specifically record rename operations. If you disable this setting, Integrity Monitor records a rename operation as a delete operation followed by a create operation. On Solaris and AIX endpoints, Integrity Monitor always records a rename operation as a delete operation followed by a create operation.

Create or edit a watchlist

  • Create as many watchlists as necessary, targeted narrowly to watch only the necessary paths on the appropriate endpoints.
  • Name each watchlist based on the application, business unit, or compliance standard you want to monitor.
  • 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.

  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. You can 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.

  • Be specific when defining watchlists. For example, watching the C:\ or / directories on endpoints results in a large number of events that are not cause for concern. To help focus on events of concern, follow these guidelines:

    • When possible, add multiple specific file paths instead of a single directory path. Add multiple specific registry subkey paths instead of higher-level registry keys.
    • If you add a directory path, add inclusions for specific file types to watch, such as *.exe and *.dll.
    • Create multiple focused watchlists for different types of applications, software components, system configuration areas, or compliance standards. For example, if you need to monitor critical operating system files for Windows, and SQL Server critical files, directories, and registry entries, create separate watchlists for Windows and SQL Server. You can target different computer groups with these watchlists for different monitoring needs.
  • Rely primarily on inclusions to refine paths, and try to limit the number of exclusions for cleaner watchlists and more predictable monitoring.

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. Go to Watchlists > [watchlist name].
  2. (For Windows watchlist path style) Make sure the File Paths tab is active.
  3. Click Add Paths > New.
  4. 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.

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

  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 /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.

    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.



(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 for watchlists with a Windows path style only.

  1. Go to Watchlists > [watchlist name]. Click the Registry Paths tab.
  2. Click Add Paths > New.
  3. 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.

  4. 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 .

  5. 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. 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_CLASSES_ROOT HKCR
HKEY_CURRENT_USER HKCU
HKEY_LOCAL_MACHINE HKLM
HKEY_USERS HKU
HKEY_CURRENT_CONFIG HKCC
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 logged into Windows. Using HKEY_USERS\* instead lets Integrity Monitor record events for all users, including the user account that is currently logged into 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. An imported file can contain either file and directory or registry paths.

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

  1. From the details page for a watchlist, click Add Paths > Import From File.
  2. Click Choose Files.
  3. Browse to and select the path file or files and click Open.
  4. 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 following fields are used in the import:

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. While you can use these templates when creating new watchlists, you can also use them to add paths to existing watchlists.

  1. From the details page for a watchlist, click Add Paths > Import From Templates.
  2. 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 details page for a watchlist, select one or more paths.
  2. Click Manage Change Type.
  3. 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 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.

  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 have enabled Endpoint Configuration approval, watchlist deployment must be approved in Endpoint Configuration before watchlists are deployed 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 Watchlists page, click the name of a watchlist to open the detail page for that watchlist.
  2. Click Export Watchlist .

    The exported watchlist downloads in your browser in JSON format.

Import a watchlist

  1. From the Watchlists page, click Import Watchlist .

  2. Click Choose File.
  3. Browse to the watchlist file and click Open.
  4. Click Import to import the file.