Table of contents
Topics on this page
Tag attributes
Entity set attributes
Shorthand attributes
Drives mounted as directories
Alternate data streams
Meaning of key
Subelements
Special attributes of Include and Exclude for FileSets

FileSet

The Integrity Monitoring module scans for unexpected changes to directories, registry values, registry keys, services, processes, installed software, ports, groups, users, files, and the WQL query statement on agents. To enable and configure Integrity Monitoring, see Set up integrity monitoring.

The FileSet tag describes a set of Files.

Tag attributes

The following table provides a list and descriptions of the XML attributes of the tag itself, as opposed to the attributes of the Entity monitored by Integrity Monitoring rules.

Attribute Description Required Default Value Allowed Values
base Sets the base directory of the FileSet. Everything else in the tag is relative to this directory. Yes N/A String values resolving to syntactically valid path (Path is not required to exist). Note that UNC paths are allowed by Windows Agents, but require that the remote system allow access by the LocalSystem account of the Agent computer. The agent is a Windows service and runs as LocalSystem, also known as NT AUTHORITY\SYSTEM. When accessing a network resource, the LocalSystem uses the computer's credentials, which is an account named DOMAIN\MACHINE$. The access token presented to the remote computer also contains the Administrators group for the computer, so remote shares must grant read privileges to either the agent computer's account, the agent computer's Administrators group, or Everyone.

If the base value is not syntactically valid, the FileSet is not processed. The rest of the configuration is evaluated.
onChange Whether the files returned should be monitored in real time. No false true, false
followLinks Will this FileSet follow symbolic links. No false true, false

Entity set attributes

These are the attributes of the FileSet that can be monitored by Integrity Monitoring Rules.

For Created, LastModified, and LastAccessed in a Linux environment, the Real-time Integrity Monitoring module detects scans where the file contents have changed, but does not detect a change such as touching a file, reading a file, or any other change that updates only metadata such as the time a file was altered.

  • Created: Timestamp when the file was created.
  • LastModified: Timestamp when the file was last modified.
  • LastAccessed: Timestamp when the file was last accessed. On Windows this value does not get updated immediately, and recording of the last accessed timestamp can be disabled as a performance enhancement. See File Times for details. The other problem with this attribute is that the act of scanning a file requires that the agent open the file, which changes its last accessed timestamp. On Unix, the agent uses the O_NOATIME flag if it is available when opening the file, which prevents the OS from updating the last accessed timestamp and speeds up scanning.
  • Permissions: The file's security descriptor (in SDDL format) on Windows or Posix-style ACLs on Unix systems that support ACLs, otherwise the Unix style rwxrwxrwx file permissions in numeric (octal) format.
  • Owner: User ID of the file owner (commonly referred to as the UID on Unix).
  • Group: Group ID of the file owner (commonly referred to as the GID on Unix).
  • Size: size of the file.
  • Sha1: SHA-1 hash.
  • Sha256:SHA-256 hash.
  • Md5: MD5 hash (deprecated).
  • Flags: Windows-only. Flags returned by the GetFileAttributes() Win32 API. Windows Explorer calls these the Attributes of the file: Read-only, Archived, Compressed, and so on.
  • SymLinkPath (Unix and Linux only): If the file is a symbolic link, the path of the link is stored here. Windows NTFS supports Unix-like symlinks, but only for directories, not files. Windows shortcut objects are not true symlinks since they are not handled by the OS; the Windows Explorer handles shortcut files (\*.lnk), but other applications that open a \*.lnk file will see the contents of the lnk file.
  • InodeNumber (Unix and Linux only): Inode number of the disk on which the inode associated with the file is stored.
  • DeviceNumber (Unix and Linux only): Device number of the disk on which the inode associated with the file is stored.
  • BlocksAllocated (Linux and Unix only): The number of blocks allocated to store the file.
  • Growing: (DSA 7.5+) contains the value true if the size of the file stays the same or increases between scans, otherwise false. This is mainly useful for log files that have data appended to them. Note that rolling over a log file triggers a change in this attribute.
  • Shrinking: (DSA 7.5+) contains the value true if the size of the file stays the same or decreases between scans, otherwise false.

Shorthand attributes

The following are the shorthand attributes and the attributes to which they map:

  • CONTENTS: Resolves to the content hash algorithm set in Computer or Policy editor > Integrity Monitoring > Advanced.
  • STANDARD: Created, LastModified, Permissions, Owner, Group, Size, Contents, Flags (Windows only), SymLinkPath (Unix only).

Drives mounted as directories

Drives mounted as directories are treated as any other directory, unless they are a network drive in which case they are ignored.

Alternate data streams

NTFS based file systems support the concept of alternate data streams. When this feature is used it behaves conceptually like files within the file.

To demonstrate this, type the following at the command prompt:

echo plain > sample.txt
echo alternate > sample.txt:s
more < sample.txt
more < sample.txt:s

The first "more" will show only the text "plain", the same text that will be displayed if the file is opened with a standard text editor, such as notepad. The second "more", which accesses the "s" stream of sample.txt will display the string "alternate".

For FileSets, if no stream is specified, then all streams are included. Each stream is a separate Entity entry in the baseline. The available attributes for streams are:

  • size
  • Sha1
  • Sha256
  • Md5 (deprecated)
  • Contents

The following example would include both streams:

<include key="**/sample.txt" />

To include or exclude specific streams, the : notation is used. The following example matches only the s stream on sample.txt and not the main sample.txt stream:

<include key="**/sample.txt:s" />

Pattern matching is supported for the stream notation. The following example would include sample.txt, but exclude all of its alternate streams:

<include key="**/sample.txt" />

<exclude key="**/sample.txt:\*" />

Meaning of key

Key is a pattern to match against the path of the file relative to the directory specified by base. This is a hierarchical pattern, with sections of the pattern separated by / matched against sections of the path separated by the file separator of the given OS.

Subelements

  • Include
  • Exclude

See Integrity monitoring rules language for a general description of Include and Exclude for their allowed attributes and sub elements. Only information specific to includes and excludes relating to the FileSet Entity Set class are included here.

Special attributes of Include and Exclude for FileSets

executable: Determines if the file is executable. This does not mean that its permissions allow it to be executed. Instead the contents of the file are checked, as appropriate for platform, to determine if the file is an executable file.

This is a relatively expensive operation since it requires the agent to open the file and examine the first kilobyte or two of its content looking for a valid executable image header. Opening and reading every file is much more expensive than simply scanning directories and matching file names based on wild card patterns, so any include and exclude rules using executable result in slower scan times than those that do not use it.