Asset V2 Search Guide#

This guide will only cover the >Asset-Service v2 search APIs.

To view up to date documentation for the v1 search APIs and all others, please review the >Swagger API documentation

Currently, the v2 API supports searching for assets, asset groups, and vulnerabilities by their respective data fields and relationships.

Some basic cross data model search is supported with more advanced support planned for later implementation.

In the meantime it’s possible to simply chain queries and their results together to, for example, search for Asset Groups containing Assets vulnerable to Vulnerabilities with a certain severity by:

  • First searching for vulnerabilities by severity

  • The Vulnerability results each contain an Asset ID, which can be inserted into an Asset Group search request to retrieve the Assets’ parent groups

Core Concepts#

Like any other search endpoint, the Asset v2 search accepts field and match strategies. In a nutshell:

  • KeywordFieldStrategies - Defines which fields against which to perform keyword search

  • TimeFieldStrategies - Defines which timestamp fields to use when filtering by start/endTimestamp

  • Keyword/TimeMatchStrategies - Defines the search logic behaviour i.e. how AND/ORs are chained when multiple fields are defined by the respective strategy

  • UserFieldStrategies - Defines which user fields to use when filtering by user id or shortname

Filtering by start/endTimestamps supports relative time format.

Asset#

The V2 search API supports the majority of the Asset v2 data model as part of the search domain.

In addition to Asset data model fields the API supports searching for Assets by Group properties:

  • Parent - Return Assets belong to the group(s) listed here by their id or shortname

  • Ancestor - Return all assets in the hierarchy below this starting Asset Group

Group#

The V2 search API supports the majority of the Asset Group v2 data model as part of the search domain.

In addition to Group data model fields the API supports searching for Groups by Asset properties:

  • Asset - Return groups that contain any of the assets listed here by their id or shortname

Vulnerabilities#

The V2 search API supports the majority of the Vulnerabiltiy v2 data model as part of the search domain.

Vulnerabilities remain searchable up to 90 days since they were last detected by a scanner, after which they are removed from the search index.

In addition to Vulnerability data model fields the API supports searching for Vulnerabilities by Asset properties:

  • Asset - Returns Vulnerabilities linked to these Assets identified by their id or shortnames