![]() |
NoteThe 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 Deep Security 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.
![]() |
Note
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 will be 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 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 At present this is only required/supported for group policy
queries, and "RsopLoggingModeProvider" is the only supported value. Group policy queries
are special since it's 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
will remove the portion of the returned __Path value after \Rsop\ and up to the next
backslash when the RsopLoggingModeProvider is used. Entity keys will therefore have
prefixes like "\\.\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
will
determine the attributes being monitored.
For example, the WQLSet:
<WQLSet namespace="Computer" wql="select * from RSOP_SecuritySettings where
precedence=1" provider="RsopLoggingModeProvider" />
will return 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" />
will return attributes such as:
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 will not
be
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 * will typically result
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":
(like 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 here for details on the Win32_LogicalDisk class)
USB Storage Device notes: U3 USB devices will 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 will not be 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...]
Some examples:
\\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 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" sub elements 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.