Configure a WMI Query Check Control (Windows)

Configure a WMI Query Check control to use a WMI query to check compliance on Windows hosts. You tell us the namespace to be evaluated and the WMI query you want to use. We'll report compliance posture at scan time.

 

The statement you provide is like the control name that describes what it is and how it should be implemented in the environment. You'll also need to decide which category the control belongs to. This is important because users can search and filter controls by category, they can also search by keywords in the statement.

The scan parameters are used to gather data needed for compliance evaluation at scan time.

Click Add Parameters, and make these settings:

File/Directory path - This is the path to the Unix file or directory to be evaluated.

Tell me about the namespaceTell me about the namespace

Enter a WMI namespace. This value is case sensitive and can have a maximum of 1000 characters. These characters may be included:  a-z, A-Z, 0-9, \ (backslash), and _ (underscore). The namespace cannot include the hostname of a local or remote machine.

Tell me about the queryTell me about the query

Enter a WMI query to be used for this control. This value can have a maximum of 4000 characters. WQL syntax is fully supported with these restrictions: 1) wildcard queries are not supported, and 2) REFLECTORS OF and ASSOCIATORS OF keywords are not supported.

Tell me about the data typeTell me about the data type

You'll see that "string list" is selected as the data type for this control type. This means the scan will return a list of string values.

Tell me about the descriptionTell me about the description

The control description will appear in compliance policies and reports. If you change the description at a later time, the description will be updated for all controls that use the same set of parameters.

Your control may apply to many technologies. Select each technology you're interested in and provide a rationale statement and expected value.

Time Saving Tip: If you plan to enter the same settings for each technology you only need to do it once. Make your selections in the "Default Values for Control Technologies" section first and then select the check box for each technology you want. You'll see that the settings get copied automatically to each technology that you select.

Make these settings:

Rationale - Enter a rationale statement describing how the control should be implemented for each technology.

Cardinality - Select a cardinality for the control. Tell me about cardinality optionsTell me about cardinality options

Several cardinality options appear as shown in the table below. X represents the value returned by the scanning engine and Y represents the expected value defined for the control.

Cardinality

You are compliant when

contains

X contains all of Y

does not contain

X does not contain any of Y

matches

all strings in X match all strings in Y (listed in any order)

intersects

any string in X matches any string in Y

is contained in

all strings in X are contained in Y

Operator - (View only) The operator "regular expression list" is used to compare the results to the default value, which is specified as a regular expression.

Default Value - Enter the expected value for each technology as a regular expression. A list of strings returned in the scan results will be compared to the regular expression using the selected cardinality.

Knowing the format of the permissions information returned, you can write a regular expression that will match your pass/fail conditions. Learn more

Add up to 10 references for the control. These may be references to internal policies, documents and web sites. For each reference, enter a description, a URL or both. When providing a URL, you must start the URL with http://, https:// or ftp://.  For example, enter http://www.qualys.com to link to the Qualys web site. Once added users have the option to include references in policy reports..

Quick Links

User-Defined Controls | Regular Expressions (PCRE) | UDC FAQs

Using Agents? Jump to a section below

The help below applies when using Cloud Agents.

Examples of Common Namespace and WQL Query Combinations

Data Types Supported in WQL Queries by Cloud Agent

Important Notes

Best Practices

 

Examples of Common Namespace and WQL Query Combinations

See the following examples:

1) Get name and filesystem type for removable and fixed disks on system

namespace: root\cimv2

query: "SELECT Caption, FileSystem from Win32_LogicalDisk"

2) Network information

namespace: root\cimv2

query: "SELECT * from Win32_NetworkAdapterConfiguration"

3) Windows QFE patches information

namespace: root\cimv2

query: "SELECT HotFixID FROM Win32_QuickFixEngineering"

4) Windows process information

namespace: root\cimv2

query: "SELECT Name from Win32_Process"

Data Types Supported in WQL Queries by Cloud Agent

The following data types are supported by cloud agents:

sint8, sint16, sint32, real32, real64, uint8, uint16, uint32, uint64, real32, real64, uint8, uint16, uint32, char16, string, boolean, string array 

Qualys continues to add support for additional data types at regular intervals.

Important Notes

Please note the following:

1) To optimize performance, the report limit is set to 5000 records. 

2) WMI queries could have a significant impact on your domain controllers when using cloud agents. Starting with agent version 3.0 we'll skip calls to these WMI providers:

- Win32_NetworkLoginProfile (2008 Server R2 only)

- Win32_UserProfile (2008 Server R2 only)

- Win32_QuickFixEngineering – skipped starting in 3.1 unless “SELECT HotFixId FROM” is present

- Win32_UserAccount - This is the only query for Win32_UserAccount that will be handled by the agent. 

Example: SELECT Description, Name from Win32_UserAccount WHERE LocalAccount='true'

3) We don't support references, objects, maps, datetime, other types of arrays, etc. 

4) WMI providers are not created or suported by Qualys. The UDC feature merely gives a convenient way to execute the queries and gather the data.

Best Practices

Please note the following best practices:

1) WQL Queries should be valid queries. Please refer to the following for guidance: https://docs.microsoft.com/en-us/windows/win32/wmisdk/wql-sql-for-wmi

2) DOS/shell/VB scripts should not be added in UDC controls. 

‘select [valid item] from [existing namespace]’ is supported. 

It's specifically a Command control rather than file/registry/wmi collection. This is valid for all agent versions.

3) It is always recommended to use an optimized query. The more constrained the requested dataset is (selecting specific object/data and using WHERE clauses) the less impact it has on the system.

4) It is very strongly recommended NOT to use any WQL query whose WMI provider needs to reach out to network resources to gather the data. Doing so on many endpoints can cause excessive traffic to, from, and on the systems providing the information. Use a tool such as Wireshark to determine if this is the case. (This is the reason behind the limitation on the Win32_UserAccount provider).

5) WMI queries typically run in the wmiprvse.exe process. Some queries will cause this process to heavily use system resources. We recommend ensuring your queries aren't causing problems in this process.

6) Before creating UDCs, please test your WQL queries out using WbemTest.exe. This tool can be found in the %windir%\system32\wbem directory on Windows systems.

7) When executing the query to the custom providers, it is entirely up to whomever created that provider (quite often Microsoft) to determine how it will operate. If there appears to be an issue with a specific provider, check the WQL query with WbemTest. If it works in WbemTest.exe but not in the agent, contact Qualys. If it fails in WbemTest, you probably need to troubleshoot the query for problems (and/or contact the author of the provider).

8) On occasion WMI itself can cause problems. WMI is part of Windows, Qualys is leveraging it to execute the requested UDC WQL queries. There are issues that can crop up, such as the WMI repository becoming corrupt, WMI providers becoming unregistered, and other issues. Again, try out WbemTest.exe with the WQL query. If it works there, but not in the agent, contact Qualys. If it doesn't work there, it is being caused by a source other than Qualys.

9) Logging can be turned on for WMI in Windows. It is not recommended to turn this on unless absolutely needed. It can consume system resources quickly, particularly disk space.