QQL Best Practices

It’s a good practice to enclose the token value in double-quotation marks especially when the character string value contains blank space.

For example, to look for assets that are running Windows 7, form this query:

operatingSystem: “Windows 7”

When you enclose a phrase within double quotation marks, the QQL search returns only the items wherein the words in your phrase are located next to one another.

If you don’t use double quotation marks, the search returns related terms.

For exact string matching, enclose the query value in the grave accent mark, also known as backtick characters. The result returns all the findings having the exact match with the value that you specify.

For example, to find a host with the sensor UID “cbcb5ef6-1c49-3ba0-91c1-5462ffbd26af,” for this query:

host.sensorUid: `cbcb5ef6-1c49-3ba0-91c1-5462ffbd26af`

When a search is restricted to a certain range, for example a date range or an IP address range, you must enclose the range values within brackets and parentheses.

If you use parentheses, the result includes all the values that fall between the lower limit value and the upper limit value in the range excluding both these values.

For example, to find out the open ports in your asset inventory, you create the following query:

openPorts.port:(123 .. 1234)

In this case, the result returns all the values that are greater than but not equal to 123 and less than but not equal to 1234.

If you use brackets, the result includes all the values that fall between the lower limit value and the upper limit value in the range including both these values.

For example, to find out the open ports in your asset inventory, you create the following query:

openPorts.port:[123 .. 1234]

In this case, the result returns all the values that are greater than or equal to 123 and less than or equal to 1234.

The following combinations of a parenthesis and a bracket in a query value fetch different results. Let’s see how:

Combination	Result
openPorts.port:(123 .. 1234]	Returns all the values that are greater than but not equal to 123 and less than or equal to 1234.
openPorts.port:[123 .. 1234)	Returns all the values that are greater than or equal to 123 and less than but not equal to 1234.

You use the greater than (>) sign or the less than (<), or the equal sign (=) instead of a colon between the search token and its value.  

Thus, if you form a query openPorts.port > 123, the result returns all the open port values that are greater than 123 excluding 123.

If your query is openPorts.port<123, the result returns all the open port values that are less than 123 excluding 123.

If you specify the value as openPorts.port=123, the result returns all the assets that have the port 123 open.

But the combination of > and =, like in openPorts.port>=123, gives you all the values that are greater than or equal to port 123.

Also, the combination of < and =, like in openPorts.port<=123, gives you all the values that are less than or equal to port 123.

Let us understand the usage of comma versus usage of logical OR operator ins a search query with an example.

Query A :activatedforModules: [VM, PC]

Query B: activatedforModules: VM OR PC

The query A searches for all assets and returns assets that are activated either for VM or for PC.

Whereas, the OR in query B splits it into two separate queries.

Query 1: activatedforModules: VM (Assets activated for VM )

OR

Query 2: PC (Assets that include PC in the fields listed on Asset Details page)

Thus, the search result for query A is different than search result for query B as the search engine functions differently in each case. Depending on the data you need to query, you need to choose comma or logical OR operator appropriately in your search query.

Refrain from using a range search query when it is possible or rather manageable to mention all the values. For example, while looking for host assets based on the vulnerability severities 3, 4, and 5, create the query vulnerabilities.vulnerability.severity:[3,4,5] and not vulnerabilities.vulnerability.severity:[3..5]. Even though both the query results are going to be same, the first query will be completed quicker than the range query.

When you want to search for host assets that fall within a particular IP range, it may not be a good idea to mention all the IP addresses in the query value field. In such you must go for a range search.

Try to reduce or eliminate the use of NOT operator in a query. Usage of NOT operator may create complexities and could result in inaccurate results.

So, instead of creating the NOT vulnerability.typeDetected:`Information Gathered` to exclude vulnerabilities of the type “Information Gathered” from search, form the following query to include the other two types instead: vulnerabilities.typeDetected:[Confirmed, Potential]

Similarly, instead of creating the query NOT vulnerabilities.status:FIXED, go for vulnerabilities.status:[NEW,ACTIVE,REOPENED].

Instead of creating an exclude search NOT vulnerabilities.vulnerability.severity:[1,2], create an explicit include search vulnerabilities.vulnerability.severity:[3,4,5]

This helps you improve the accuracy of your query results. This is applicable more to the queries created for the Vulnerability category. It is okay to use the NOT operator in queries for the Asset category.

However, even in Asset queries, avoid using NOT as much as possible.

For example, to find the agents that last checked in to the Qualys platform before the last 30 days, don't form a query

NOT lastCheckedIn:[now-30d...now-2s].

Instead, go for lastCheckedIn<now-30d.

Instead of using brackets for date range search, we recommend using the greater-than sign or the less-than sign in a date range search.  

For example, to list vulnerability detections within last 90 days, form the query lastVMScanDate > now-90d instead of lastVMScanDate:[now-90d .. now].

To include day 90 in search results, go for lastVMScanDate >= now-90d.

To list vulnerability detections older than past 90 days, form the query lastVMScanDate < now-90d instead of lastVMScanDate:[2020-01-01 .. now-90d].

To include day 90 in search results, go for lastVMScanDate <= now-90d.

You can now use alternate operators (such as AND operator) instead of nesting the queries. For example, let us consider the following nested query:

vulnerabilities: (vulnerability.severity:[3,4,5] and typeDetected:[Confirmed]) and vulnerabilities.vulnerability.vendors.vendorName:Cisco

Alternately, you can create a query as follows:

vulnerabilities.vulnerability.severity:[3,4,5] and vulnerabilities.typeDetected:[Confirmed] and vulnerabilities.vulnerability.vendors.vendorName:Cisco