Query Syntax Changes June 2020

What is Changing and Why Does It Have to Change?

Infrastructure upgrades being implemented will result in more stringent checking of search syntax on the Explore page. This change will not impact anything selected via checkboxes in the right hand search panel. Ambiguous searches will require updating to meet the new requirements, resulting in more accurate search results. 

Timelines

Required Change Examples

No Search Terms Provided

Invalid: windows

• Previously, free text was allowed and used to automatically search the cve_description field. 

Valid: cve_description:windows 

• Values always need to be preceded by a search term, which is the name of the field to be searched followed by a colon.

Missing Parentheses for Multiple Values

Invalid: tag:a b c

• In this example the second 2 terms would be passed as cve_description searches

Fixed: tag:(a b c)

• This now correctly returns any asset documents that have tag:a, tag:b or tag:c. You can also explicitly use the contraction OR - tag:(a OR b OR c).

Missing Parentheses for Multiple Values with a Conjunction

Invalid: tag:priority AND urgent

• This brings up any asset documents that have priority as a tag and also urgent in any cve_description.

Fixed: tag:(priority AND urgent)

• This now correctly brings up asset documents that have both priority and urgent in the tag field

Missing Quotations on Phrases

Invalid: os:Microsoft Windows

• This brings up asset documents with the operating systems Microsoft and then using OR, adds to that pile any asset document matching Windows in the cve_description.

Fixed: os:"Microsoft Windows”

• This now correctly searches for the value ”Microsoft Windows” on the os field. 

Lowercase Conjunctions

Invalid: tag:(priority and urgent)

• This brings up all asset documents with the tag priority OR urgent in the tag field.

Fixed: tag:(priority AND urgent)

• This now correctly brings up asset documents that have both priority AND urgent in the tag field.

Incorrect Boolean Searches for CVEs

Invalid: cve:(2020-1234 AND 2020-5678)

• This searches for CVEs for asset documents that match BOTH 2020-1234 and 2020-5678, which is not possible so no results are retuned.

Fixed: cve:(2020-1234 OR 2020-5678)

• This now returns asset documents that have CVE 2020-1234 OR have CVE 2020-5678. When surrounded in parentheses, ElasticSearch will combine these values with OR.

Testing Via the API

New endpoints have been added to the API to assist in validating query strings - Vuln Query Check and Asset Query Check. These endpoints check the “q=” portion of the API calls or searches built in the text search box.

NOTE: The query must be encoded to be passed to this endpoint. There are a number of free tools available online which can do the encoding for you.

Example: 

To check query = os:solaris AND tag:chicago

API Call: https://api.kennasecurity.com/assets/validate_search?q=os%3Asolaris%20AND%20tag%3Achicago"

API Response:

{

  "valid": true,

  "query": "os:solaris AND tag:chicago",

  "suggested_query": null

}

If the query is invalid - tag:production AND chicago - the endpoint will attempt correction

API Call: https://api.kennasecurity.com/assets/validate_search?q=tag%3Aproduction%20AND%20chicago"

API Response:

{

  "valid":false,

  "query":"tag:production AND chicago",

  "suggested_query":"tag:(production AND chicago)"

} 

In Line Testing

 US customers can use the API documentation tool to execute the endpoint.