Integrity monitoring rules language

The Integrity Monitoring Rules language is a declarative XML-based language that describes the system components and associated attributes that should be monitored by Deep Security. It also provides a means to specify what components within a larger set of components should be excluded from monitoring.

There are two ways to create a new Integrity Monitoring Rule: if you simply want to monitor files for unauthorized changes you can use the "Basic Rule" template. Instructions for using the Basic Rule template can be found in Define an integrity monitoring rule for use in policies.

If you want to create a rule that will monitor other Entities on the computer (directories, registry values, services, etc.) you will have to write a rule using the Integrity Monitoring Rules language. (To create a new Integrity Monitoring Rule using the Integrity Monitoring Rules language, go to Policies > Common Objects > Rules > Integrity Monitoring Rules > New> New Integrity Monitoring Rule > Content and select "Custom (XML)".)

Entity Sets

System components included in an Integrity Monitoring Rule are referred to as "Entities". Each type of component is a class of Entity. For example, files, registry keys, and processes are each a class of Entity. The Integrity Monitoring Rules language provides a tag for describing a set of Entities (an Entity Set) for each class of Entity. The following Entity Set types are available to be used in a rule:

• DirectorySet: rules will scan the integrity of directories
• FileSet: rules will scan the integrity of files
• GroupSet: rules will scan the integrity of groups
• InstalledSoftwareSet: rules will scan the integrity of installed software
• PortSet: rules will scan the integrity of listening ports
• ProcessSet: rules will scan the integrity of processes
• RegistryKeySet: rules will scan registry keys
• RegistryValueSet: rules will scan registry values
• ServiceSet: rules will scan the integrity of services
• UserSet: rules will scan the integrity of users
• WQLSet: rules will monitor the integrity of the results of a Windows Management Instrumentation WQL query statement

A single Integrity Rule can contain multiple Entity Sets. This allows you to, for example, secure an application with a single rule that monitors multiple files and registry entries.

Hierarchies and Wildcards

For Entity Sets that represent a hierarchical data type such as FileSet and RegistryKeySet, section-based pattern matching is supported:

• / (forward slash) : demarcates sections of the pattern to be applied to levels of the hierarchy
• ** (two stars) : matches zero or more sections

The following wildcards are supported:

• ? (question mark) : matches one character
• * (one star) : matches zero or more characters

"Escaping" characters is also supported:

• \ (back slash) : escapes the next character

The pattern is divided into sections using the " / " character, with each section of the pattern being applied to successive levels of the hierarchy as long as it continues to match. For example, if the pattern:

/a?c/123/*.java

is applied to the path:

/abc/123/test.java

Then:

• "a?c " matches "abc"
• "123 " matches "123"
• "*.java " matches "test.java"

When the pattern is applied to the path:

/abc/123456/test.java

Then:

• "a?c " matches "abc"
• " 123 " does not match "123456", and so no more matching is performed

The " ** " notation pattern matches zero or more sections, and so:

/abc/**/*.java

matches both "abc/123/test.java" and "abc/123456/test.java". It would also match "abc/test.java" and "abc/123/456/test.java".

Syntax and Concepts

This section will present some example Integrity Monitoring Rules. The examples will use the FileSet Entity Set but the topics and components described are common to all Entity Sets. A minimal Integrity Monitoring Rule could look like this:

<FileSet base="C:\Program Files\MySQL">
</FileSet>

The "base" attribute specifies the base directory for the FileSet. Everything else about the rule will be relative to this directory. If nothing further is added to the rule, everything (including subdirectories) below the "base" will be monitored for changes.

Within an Entity Set, "include" and "exclude" tags can be used to control pattern matching. These tags have a "key" attribute that specifies the pattern to match against. The source of the key varies by Entity Set. For example, for Files and Directories it is their path, while for Ports it is the unique protocol/IP/portNumber tuple.

Include

The include tag is essentially an allow list. Using it means that only those Entities matched by it (or other include tags) will be included. By adding an include tag, the following rule now only monitors changes to files with the name "*.exe" in the "C:\Program Files\MySQL" folder and sub folders:

<FileSet base="C:\Program Files\MySQL">
<include key="**/*.exe"/>
</FileSet>

"Includes" can be combined. The following rule will monitor changes to files with the names "*.exe" and "*.dll" in the "C:\Program Files\MySQL" folder and sub folders:

<FileSet base="C:\Program Files\MySQL">
<include key="**/*.exe"/>
<include key="**/*.dll"/>
</FileSet>

It is also possible to combine multiple criteria in a single include block, in which case all criteria must be true for a given Entity to be included. The following "include" tag requires that an Entity both end in ".exe" and start with "sample" to be included. Although this requirement could be represented more succinctly, the usefulness of this becomes more apparent as key patterns are combined with other features of the Entity, as described in the "Features" section below.

<include>
<key pattern="**/*.exe"/>
<key pattern="**/sample*"/>
</include>

The following is another way to express the same requirements:

<include key="**/*.exe">
<key pattern="**/sample*"/>
</include>

Exclude

The exclude tag functions as a block list, removing files from the set that would otherwise be returned. The following (unlikely) example would place everything but temp files under watch.

<FileSet base="C:\Program Files\MySQL">
<include key="**"/>
<exclude key="**/*.tmp"/>
</FileSet>

The following rule excludes the "MySQLInstanceConfig.exe" from the set of EXEs and DLLs:

<FileSet base="C:\Program Files\MySQL">
<include key="**/*.exe"/>
<include key="**/*.dll" />
<exclude key="**/MySQLInstanceConfig.exe"/>
</FileSet>

Like the "include" tag, the "exclude" tag can be written to require multiple criteria. The following example shows a multi-criteria "exclude" tag.

<exclude>
<key pattern="**/MySQLInstanceConfig*" />
<key pattern="**/*.exe" />
</exclude>

Case Sensitivity

The case sensitivity of pattern matching for an include or exclude tag may be controlled by the "casesensitive" attribute. The attribute has three allowed values:

• true
• false
• platform

The default value for this attribute is "platform", which means that the case sensitivity of the pattern will match the platform on which it is running. In the following example, both "Sample.txt" and "sample.txt" would be returned on a Windows system, but only "Sample.txt" would be returned on a Unix system:

<FileSet base="C:\Program Files\MySQL">
<include key="**/*Sample*"/>
</FileSet>

In this example, only "Sample.txt" would be returned on Windows and Unix:

<FileSet base="C:\Program Files\MySQL">
<include key="**/*Sample*" casesensitive="true"/>
</FileSet>

Features

The inclusion and exclusion of Entities based on features other than their "key" is also supported for some Entity types. The set of features differs by Entity type. The following example will include all executable files. It does not depend on the file extension as previous examples using file extensions did, but instead will check the first few hundred bytes of the file to determine if it is executable on the given OS.

<FileSet base="C:\Program Files\MySQL">
<include key="**" executable="true"/>
</FileSet>

Feature attributes must appear in an "include" or "exclude" tag. To use them as part of a multi-criteria include or exclude, they must be specified as attributes of the enclosing include or exclude tag. The following example includes all files that contain the string "MySQL" in their name and are also executable:

<include executable="true">
<key pattern="**/*MySQL*"/>
</include>

The previous example can be more succinctly expressed as:

<include key="**/*MySQL*" executable="true"/>

Some feature attributes are simply matches against the value of one of the Entity's attributes. In such cases, wildcard matches using " * " and " ? " are sometimes supported. The help pages for the individual Entity Sets indicate which attributes can be used in include or exclude rules in this way, and whether they support wildcard matching or simple string matching.

The following is an example of a feature match using the "state" attribute:

<ServiceSet>
<include state="running"/>
</ServiceSet>

The following example matches any processes where the path of the binary ends in "\notepad.exe":

<ProcessSet>
<include path="*\notepad.exe"/>
</ProcessSet>

The following example matches any processes where the command-line begins with "/sbin/":

<ProcessSet>
<include commandLine="/sbin/*"/>
</ProcessSet>

ANDs and ORs

It is possible to express logical ANDs and ORs through the use of multi-criteria includes and excludes and multiple includes and excludes.

There are several ways that a multi criteria include or exclude can be used to express an AND. The most straightforward is to include multiple criteria within a single enclosing tag. The following example shows a simple multi-criteria AND-ing:

<include>
<key pattern="**/*MySQL*" />
<key pattern="**/*.exe"/>
</include>

As well, any criteria expressed as an attribute of the including tag will be grouped with the enclosed criteria as part of the multi-criteria requirement. The following example shows the previous multi-criteria "include" re-written in this way:

<include key="**/*.exe">
<key pattern="**/*MySQL*" />
</include>

Finally, if multiple criteria are expressed as attributes of an include or exclude they are treated as an AND:

<include executable="true" key="**/*MySQL*" />

ORs are expressed simply by the inclusion of multiple include or exclude tags. The following code includes files if their extensions are ".exe" OR ".dll":

<include key="**/*.dll" />
<include key="**/*.exe" />

Order of Evaluation

All "includes" are processed first, regardless of order of appearance in the rule. If an object name matches at least one "include" tag, it is then tested against the "exclude" tags. It is removed from the set of monitored objects if it matches at least one "exclude" tag.

Entity Attributes

A given Entity has a set of attributes that can be monitored. If no attributes are specified for an Entity Set (i.e. the attributes wrapper tag is not present) then the STANDARD set of attributes for that Entity is assumed. (See the Shorthand Attributes sections for the individual Entity Sets.)

However, for a given Entity Set only certain attributes of the Entity may be of interest for Integrity Monitoring. For example, changes to the contents of a log file are most likely expected and allowed. However changes to the permissions or ownership should be reported.

The "attributes" tag of the Entity Sets allows this to be expressed. The "attributes" tag contains a set of tags enumerating the attributes of interest. The set of allowed "attribute" tags varies depending on the Entity Set for which they are being supplied.

The following example monitors executable files in "C:\Program Files\MySQL" whose name includes "SQL" for changes to their "last modified", "permissions", and "owner" attributes:

<FileSet base="C:\Program Files\MySQL" >
<include key="**/*SQL*" executable="true"/>
<attributes>
<lastModified/>
<permissions/>
<owner/>
</attributes>
</FileSet>

The following example monitors the "permissions", and "owner" attributes of log files in "C:\Program Files\MySQL":

<FileSet base="C:\Program Files\MySQL" >
<attributes>
<permissions/>
<owner/>
</attributes>
<include key="**/*.log" />
</FileSet>

In the following example, the STANDARD set of attributes will be monitored. (See Shorthand Attributes, below)

<FileSet base="C:\Program Files\MySQL" >
<include key="**/*.log" />
</FileSet>

In the following example, no attributes will be monitored. Only the existence of the Entities will be tracked for change.

<FileSet base="C:\Program Files\MySQL" >
<attributes/>
<include key="**/*.log" />
</FileSet>

Shorthand Attributes

Shorthand attributes provide a way to specify a group of attributes using a single higher level attribute. Like regular attributes the set of allowed values differs based on the Entity Set for which they are being supplied.

Shorthand Attributes are useful in cases where a set of attributes naturally group together, in cases where exhaustively listing the set of attributes would be tedious, and in cases where the set of attributes represented by the high level attribute may change with time or system configuration. An example of each case follows:

Attribute	Description
STANDARD	The set of attributes to monitor for the Entity Set. This is different than "every possible attribute" for the Entity Set. For example, it would not include every possible hash algorithm, just the ones deemed sufficient. For the list of "standard" attributes for each Entity Set, see sections for the individual Entity Sets.
CONTENTS	This is Shorthand for the hash, or set of hashes, of the contents of the file. Defaults to SHA-1.

onChange

An EntitySet may be set to monitor changes in real time. If the onChange attribute of an EntitySet is set to true (the default value) then the entities returned by the EntitySet will be monitored for changes in real time. When a change is detected the Entity is immediately compared against its baseline for variation. If the onChange attribute of an EntitySet is set to false, it will be run only when a baseline is built or when it is triggered via a Scheduled Task or on demand by the Deep Security Manager.

The following sample monitors the MySQL binaries in real time:

<FileSet base="C:\Program Files\MySQL" onChange="true">
<include key="**/*.exe"/>
<include key="**/*.dll" />
</FileSet>

Environment Variables

Environment variables can be included in the base value used in Entity Sets. They are enclosed in "${}". The variable name itself is prefaced with "env.".

The following example sets the base directory of the FileSet to the path stored in the PROGRAMFILES environment variable:

<FileSet base="${env.PROGRAMFILES}"/>

If a referenced environment variable is not found, the Entity Sets referencing it are not scanned or monitored, but the rest of the configuration is used. An Alert is triggered indicating that the variable is not present. The Agent reports an invalid environment variable using Agent Event "Integrity Monitoring Rule Compile Issue". The ID of the Integrity Monitoring Rule and the environment variable name are supplied as parameters to the Event.

Registry values

Registry values can be included in the base value used in Entity Sets. They are enclosed in ${}. The path to the registry value itself is prefaced with "reg.". The following example sets the base directory of the FileSet to the path stored in the "HKLM\Software\Trend Micro\Deep Security Agent\InstallationFolder" registry value:

<FileSet base="${reg.HKLM\Software\Trend Micro\Deep Security Agent\InstallationFolder}"/>

The values of referenced registry values are read when a new or changed rule is received by the Agent. The Agent also checks all rules at startup time and will rebuild the baseline for affected Rules if any referenced registry values change.

If a referenced registry value is not found, the EntitySets referencing it are not scanned or monitored, but the rest of the configuration is used. An Alert notifying that the variable is not present is raised. The Agent reports an invalid environment variable expansion using Agent Event 8012. The ID of the Integrity Monitoring Rule and the registry value path are supplied as parameters to the Event.

Use of ".."

The ".." convention for referencing a parent directory is supported in all current versions of the Agent. The Agent will attempt to normalize base directory names for FileSet and DirectorySet elements by resolving ".." references and converting Windows short names to long names. For example, on some newer versions of WIndows the following FileSet would have a base directory of "C:\Users". On earlier versions of Windows it would be "C:\Documents and Settings".

<FileSet base="${env.USERPROFILE}\..">
<include key="*/Start Menu/Programs/Startup/*"/>
</FileSet>

Best Practices

Rules should be written to only include objects and attributes that are of significance. This will ensure that no events are reported if other attributes of the object change. For example, your change monitoring policy may place restrictions on permission and ownership of files in " /bin ". Your Integrity Monitoring Rule should monitor owner, group, and permissions, but not other attributes like lastModified or hash values.

When using Integrity Monitoring Rules to detect malware and suspicious activity, monitor services, watch for use of NTFS data streams, and watch for executable files in unusual places such as " /tmp " or " ${env.windir}\temp ".

Always be as specific as possible when specifying what objects to include in a rule. The fewer objects you include, the less time it will take to create your baseline and the less time it will take to scan for changes. Exclude objects which are expected to change and only monitor the attributes you are concerned about.

Do not:

• Use " **/... " from a top-level of the hierarchy such as " / ", "C:\", or " HKLM\Software "
• Use more than one content hash type unless absolutely necessary
• Reference user-specific locations such as HKEY_CURRENT_USER , ${env.USERPROFILE} , or ${env.HOME}

Any of these statements in your Integrity Monitoring Rules will cause performance issues as the Deep Security Agent searches through many items in order to match the specified patterns.