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 have name Car Assembly, form this query:

asset.name: “Car Assembly”

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 assets that have order ID 6ES7412-3HJ14-0AB0 for this query:

asset.orderid: '6ES7412-3HJ14-0AB0'

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 traffic.total > 10 MB, the result returns network traffic with total traffic greater than 10 MB  excluding 10 MB.

If your query is traffic.total < 10 GB, the result returns network traffic with total traffic less than 10 GB excluding 10 GB.

If you specify the value as traffic.total = 1048576, the result returns network traffic with total traffic equal to 1048576 Bytes.

But the combination of > and =, like in traffic.total >= 10 KB, the result returns network traffic with total traffic greater than or equal to 10 MB.

Also, the combination of < and =, like in traffic.total <= 10 MB, the result returns network traffic with total traffic less than or equal to 10 MB.

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

Query A : vulnerabilities.vulnerability.criticality: CRITICAL or vulnerabilities.vulnerability.criticality: HIGH

Instead of using complex query, you can use  a better query for range.

Query B: vulnerabilities.vulnerability.criticality: [CRITICAL, HIGH]

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 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.

 

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 asset created within last 90 days, form the query asset.created > now-90d instead of asset.created:[now-90d .. now].

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

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

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