Table of contents

WQLSet

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 WQLSet element describes a result set from a Windows Management Instrumentation WQL query statement. WQL allows SQL-like queries to be made against many different object classes, with the results forming a table of rows where each row represents an object and each column represents the value of a specific attribute of the object.

Many WMI queries consume a large amount of time and computer resources. It is easy to inadvertently issue a query that takes several minutes to complete and returns thousands of rows. It is highly recommended that all queries be tested before use in a WQLSet using a program like Powershell or WMI Explorer.

Attribute Description Required Default Value Allowed Values
namespace Sets the namespace of the WMI query. Yes N/A String values representing a valid WMI namespace.

The "root\cimv2" namespace is the one most commonly used when querying Windows operating system objects, but others such as "root\directory\LDAP" and "root\Microsoft\SqlServer\ComputerManagement" can be used. See here for a small script called GetNamespaces.vbs that enumerates the available WMI namespaces on a given computer.
wql A WQL query string. Yes N/A A valid WQL string.

The query must include the __Path attribute for each returned object; the Agent uses the __Path attribute as the entity key when storing and reporting results, so each returned WMI object must include a __Path. If using a query string such as "SELECT \* FROM ..., the __Path attribute is available, but if using a more selective query such as SELECT Name FROM ..., you must explicitly include __Path by writing the query as SELECT __Path,Name FROM ...
onChange Whether or not the files returned should be monitored in real time. No false true, false
provider Optionally specifies an alternative WMI namespace provider to use. No none RsopLoggingModeProvider

Currently, this is only required or supported for group policy queries, and RsopLoggingModeProvider is the only supported value. Group policy queries are special since it is recommended that the RsopLoggingModeProvider be used to create a snapshot of the policy data that is present on a computer. If you create a snapshot of the policy data, the query can be performed against a consistent set of data before the system overwrites or deletes it during a refresh of policy. Creating a snapshot actually creates a new WMI namespace, so when using provider="RsopLoggingModeProvider" in a WQLSet, the namespace attribute should specify the suffix to be added to the created namespace. For example, a typical temporary namespace created by the RsopLoggingModeProvider would be "\\.\Root\Rsop\NS71EF4AA3_FB96_465F_AC1C_DFCF9A3E9010". Specify namespace="Computer" to query "\\.\Root\Rsop\NS71EF4AA3_FB96_465F_AC1C_DFCF9A3E9010\Computer".

Since the temporary namespace is a one-time value, it hampers the ability of the Agent to detect changes since the value appears in the entity key. To avoid this, the Agent removes the portion of the returned __Path value after \Rsop\ and up to the next backslash when the RsopLoggingModeProvider is used. Entity keys therefore have prefixes such as "\\.\Root\Rsop\Computer" rather than "\\.\Root\Rsop\NS71EF4AA3_FB96_465F_AC1C_DFCF9A3E9010\Computer"
timeout Specifies a per-row timeout in milliseconds. No 5000 1-60000

The WMI query is performed in semisynchronous mode, where result rows are fetched one at a time and there is a timeout on the fetching of a single row. If this parameter is not specified, 5000 (5 seconds) is used as the timeout value.

Entity set attributes

Each row returned by the WQL query is treated as a single Entity for Integrity Monitoring purposes, with the returned columns representing the attributes of the entity. Since WMI/WQL is an open-ended specification, there is no set list of available or supported attributes. The query and the schema of the WMI object being queried determines the attributes being monitored.

For example, the following WQLSet

<WQLSet namespace="Computer" wql="select * from RSOP_SecuritySettings where precedence=1" provider="RsopLoggingModeProvider" />

returns attributes of

ErrorCode, GPOID, KeyName, SOMID, Setting, Status, id, precedence

whereas a WQLSet that queries network adapters such as

<WQLSet namespace="root\cimv2" wql="select * from Win32_NetworkAdapter where AdapterTypeId = 0" />

Returns the following attributes:

AdapterType, AdapterTypeId, Availability, Caption, ConfigManagerErrorCode, ConfigManagerUserConfig, CreationClassName Description, DeviceID, Index, Installed, MACAddress, Manufacturer, MaxNumberControlled, Name, PNPDeviceID, PowerManagementSupported, ProductName, ServiceName, SystemCreationClassName, SystemName, TimeOfLastReset

In order to reduce the load on the agent, it is advisable to explicitly include only the attributes that require monitoring rather than use select * ... in queries. This also has the benefit that changes to the WMI schema to add or remove attributes are not reported as changes to the object unless the attributes are part of the set being monitored. With select * from Win32_Foobar, a patch to Windows that adds a new attribute to the Win32_Foobar object class would result in the next integrity scan reporting a change for every object of that class since a new attribute has appeared.

The following are some example WMI queries which return desirable Windows system entities:

Query for Windows mounted storage devices (selecting for * typically results in 80% returned attributes being null or duplicate values):

<WQLSet namespace="root\cimv2" wql="SELECT __Path,DeviceID,VolumeName,VolumeSerialNumber,DriveType,FileSystem,Access,MediaType,Size,FreeSpace FROM Win32_LogicalDisk" />

To further the preceding query, the DriveType can be specified to isolate only certain types of mounted logical storage devices, such as type 2 which is a Removable Disk (similar to a removable USB storage drive):

<WQLSet namespace="root\cimv2" wql="SELECT __Path,DeviceID,VolumeName,VolumeSerialNumber,DriveType,FileSystem,Access,MediaType,Size,FreeSpace FROM Win32_LogicalDisk WHERE DriveType=2" />

See the Microsoft documentation for details on the Win32_LogicalDisk class.

About USB storage devices

U3 USB devices mount both a type 2 Removable Disk device and a type 3 Compact Disc device. Also, the above query is for storage devices only. USB non-storage devices are not included. USB memory card adapters may appear as a type 1 No Root Directory device. A badly or Windows incompatible USB storage device may appear as a type 1 Unknown device.

Query for all known System Directories where the Drive is F: for relevant attributes:

<WQLSet namespace="root\cimv2" wql="SELECT __Path,CreationDate,LastAccessed,LastModified,Drive,Path,FileName,Caption,FileType,Readable,Writeable FROM Win32_Directory WHERE Drive='F:'" />

Query for all known System Files where the Drive is F: for relevant attributes:

<WQLSet namespace="root\cimv2" wql="SELECT __Path,CreationDate,LastAccessed,LastModified,Drive,Path,FileName,Name,FileType,Readable,Writeable FROM CIM_DataFile WHERE Drive='F:'" />

Meaning of key

The key is the __Path attribute of the returned WMI object, which is generally of the form:

SystemName\Namespace:WmiObjectClass.KeyAttribute=Value[,KeyAttribute=Value...]

For example:

\TEST-DESK\root\cimv2:Win32_QuickFixEngineering.HotFixID="KB958215-IE7",ServicePackInEffect="SP0"
\TEST-DESK\ROOT\Rsop\NSF49B36AD_10A3_4F20_9541_B4C471907CE7\Computer:RSOP_RegistryValue.
Path="MACHINE\Software\Microsoft\Windows\CurrentVersion\Policies\System\LegalNoticeText",precedence=1
\TEST-DESK\root\cimv2:BRCM_NetworkAdapter.DeviceID="8"

Include and exclude

See Integrity monitoring rules language for a general description of include and exclude for their allowed attributes and sub elements.

For WQLSet, include and exclude subelements should typically not be required. It is preferable to use WQL to specify the exact set of objects to be monitored since that limits the amount of work done by both the agent and the computer's WMI implementation.

The use of any include or exclude sub elements can only reduce the set of objects returned by the query; the WQL must be changed in order to return additional objects. If it is necessary to use include or exclude elements to further restrict the WQL results, * and ? characters can be used as simple wildcards to match against values of the entity key.