Components of a QQL query

A QQL query is comprised of the following elements:

Search token

Operator

Token value

Search token

We provide you thousands of search tokens to select from. All you need to do is click the Search bar wherein you are going to create your query, start typing, and the auto-suggest feature will list down all the possible tokens that you can use. Help on token and syntax usage is available in the right pane.

Operator

An operator is a mandatory character, or a word reserved in a database query. In QQL, operators are used to perform operations for the search conditions that you set in a query. In QQL, we mainly use the logical or Boolean operators such as AND, OR and NOT, and the operators used in comparisons such as a colon (:), greater than sign (>), less than sign (<), and their several combinations. Let’s know more:

Operator

Result

AND

Returns query results that include all the free-text values and values with restricted searches that you combine with the AND operator in your query.

For example, to find host assets with both the Shellshock vulnerability and the Heartbleed vulnerability, form the following query:

vulnerabilities.vulnerability.title:shellshock AND vulnerabilities.vulnerability.title:heartbleed

NOT

Returns query results that don't include the free-text values or values with restricted search that you combine with the NOT operator in your query. So, when you use the NOT operator, you are telling the database to exclude the value that follows the NOT operator from search.

For example, to exclude assets with the Windows tag from search, you form the following query:

NOT tags.name: Windows

Note: We recommend that you reduce, or eliminate, the use of the NOT operator in a query. So, to exclude vulnerabilities of the type “Information Gathered” from search, form the following query instead: vulnerabilities.typeDetected:[Confirmed, Potential]

See Avoid_usage_of_NOT.

OR

Returns query results that include one or more of the free-text values or values with search restrictors that you conditionalize with the OR operator in your query.

For example, to find host assets running Windows 2008 R2  or Windows 2012 R2, form the following query:

operatingSystem: “windows 2008 R2” OR operatingSystem: “windows 2012 R2”

Note: It’s a good practice to use double-quote characters around your character string values especially those that contain blank space.

:

A colon (:) separates a query search token from token value. After the colon, you can use various search restrictors with the token value and conditionalize your search query to get the most relevant results.

=

Returns results where the property value stored in the database is equal to the search token value that you specify in your query. You must use the = operator with the < or the > operator. For example, if you build a query vulnerabilities.severity>4, you get all the results that have the vulnerability severity 5. But if you build a query vulnerabilities.severity>=4, the results are of both severity 4 and 5. We don't recommend using the = independently. Use the : operator instead.

<

Returns all the results where the property value stored in the database is less than the search token value that you specify in your query. You must replace the : operator after the token with <.

For example, to find out vulnerabilities that are older than last 30 days, form a query as vulnerabilities.lastFound<now-30d.

>

Returns all the results where the property value stored in the database is greater than the search token value that you specify in your query. You must replace the : operator after the token with >.

For example, to find out vulnerabilities that were detected in the last 30 days, form a query as vulnerabilities.lastFound>now-30d.

<=

Returns all the results that have the stored values less than or equal to the search token value that you specify in your query. You must replace the : operator after the token with <=.

For example, to find out vulnerabilities that were first detected on or before May 21, 2020, for a query as vulnerabilities.firstFound<=2020-05-21

>=

 

Returns all the results that have the stored values greater than or equal to the search token value that you specify in your query. You must replace the : operator after the token with >=.

For example, to find out vulnerabilities that were first detected on or after May 21, 2020, for a query as vulnerabilities.firstFound>=2020-05-21 .

 

Token Value

For the database query to return results, you must specify some value of the search token. You enter the token value after an operator. For some tokens, for example vulnerabilities.severity, which accept values from a fixed and finite set, you can select values from the available options.

Maximum character limit (including alphanumeric, special characters and spaces)

The length limit of a QQL query is 4096 characters. This length limit includes strings that are added when you select a filter. Additionally, for VMDR module widgets, the 4096 character limits also includes the token activatedForModules: VM added by the system.

Maximum limit of a query field value is 256 characters. If your query exceeds the character limit, you see an error message. Spaces in between characters are counted as characters.

We've implemented controls in query parsing for queries containing the operators “AND” and “OR”. The maximum depth allowed for an AND/OR query cannot exceed 1000 levels. If you run a query having more than 1000 levels of depth, you see an error.

• A simple query like this has a level of depth 2

asset: (lastBoot: '2018-10-10' AND cpuCount: 2)

• A more complex query like this has a level of depth 5

(operatingSystem: "Windows 7 SP2 Enterprise" OR operatingSystem: "Windows 2002") AND (hardware: "Dell Latitude e7470" OR hardware: "Dell Inspiron") AND NOT asset.lastBoot <= "2018-11-01"

Use the following characters as a part of your token value to narrow down your search:

Character

Result

..

Returns the results where the token value falls within the range that you specify. Ranges can be specified with the [lower .. upper] syntax using parentheses and brackets.

This is supported for numeric and date fields.

See Range Searches.

*

When you use the wildcard operator (*) with a part of a word in your query value, you get the results based on the exact matches.

If you type a part of a word followed by the wildcard operator, you enable the prefix matching.

For example,

interfaces.hostname: xp*

interfaces.hostname: com-pa30*

If you use the wildcard operator followed a part of a word, you enable the suffix matching.

For example,

interfaces.hostname: *111

interfaces.hostname: *lys.com

`<value>`

Returns all the results that contain the exact value string that you enclose in the grave accent marks (also called backticks) in your query.

You can also look for case-sensitive matches by using backticks.

For example,

To find out the asset with the name “ACMENVT7,” form the following query:

asset.name: `ACMENVT7`

“<value string>”

Returns all the results that contain the value string that you enclose in the double quotation marks in your query.

For example,

To list the vulnerabilities that contain “Remote” or “Code” or both in their title, form the following query:

vulnerabilities.vulnerability.title: “Remote Code”

[<lower limit> .. <upper limit>]

Square brackets are typically used in range searches such as date ranges or IP address ranges. 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.

(<lower limit>.. <upper limit>)

Round brackets (parentheses) are also used in range searches.  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.

See Use brackets […] and parentheses (…) smartly

 

Additionally, you can also refer to the several Help topics in which we discuss various ways of using tokens.

See How to Search | Boolean Queries | Nested Search.