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

NB: To access results beyond the default 10k result window limit currently requires access to specific permissions. Please contact mnemonic if you need to stream beyond the 10k limit.

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 Vulnerability V2 data model as part of the search domain.

Vulnerabilities remain searchable up to one year since they were last updated, after which they can still be retrieved by dedicated endpoints e.g.:

  • Get vulnerability Observation by ID

  • Get Observations by asset/vulnerability

However, neither the list nor search endpoints will return them.

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

  • Asset components - search for vulnerabilities observed on assets with these component values

Vulnerability definition properties:

  • name

  • description

  • conclusion

  • references

  • vulnerability ID, composed of the underlying scanner’s identifier and the vulnerability’s scanner assigned ID e.g. MV101-123456

  • vulnerability UUID

  • exploit availability timestamp

Compact View#

In addition to returning individual observations in search results the API supports grouping observation results by their vulnerability definitions via the compact view endpoint. While supporting the exact same search criteria as the regular vulnerability observation search endpoint, the vulnerability compact endpoint returns vulnerability definitions along with the count of observations of said vulnerability that match the submitted search criteria. Limit and offset affect the resulting vulnerability/count elements rather than the observations. Refer to >Swagger for the most up-to-date documentation.