API for CVE Events

Table of Contents

API V2
API V1
- Request Parameters
  - Example Request
  - Example Response

Need help?

Schedule a consultation with an Azul performance expert.

The CVE Events API allows you to retrieve events for a given VM instance, which returns the detected CVEs in components on that instance.

API V2

Request Parameters

You can extend the request with a filter for one or more fields.

Argument	Default	Description
reportName	string	Name of the report.
from	string	Relative or absolute time that will be applied to the firstSeen timestamp of the AppEnv. See API Date Filter Format.
to	string	Relative or absolute time that will be applied to the lastSeen timestamp of the AppEnv. See API Date Filter Format.
filter	list	List of filters as described in the Filter Rules.
sortBy	list	List of sorting conditions as described in the Sorting Rules.

Argument

Default

Description

reportName

string

Name of the report.

from

string

Relative or absolute time that will be applied to the firstSeen timestamp of the AppEnv. See API Date Filter Format.

string

Relative or absolute time that will be applied to the lastSeen timestamp of the AppEnv. See API Date Filter Format.

filter

list

List of filters as described in the Filter Rules.

sortBy

list

List of sorting conditions as described in the Sorting Rules.

Filter Rules

Operand Applicable Fields Description

Operand	Applicable Fields	Description
`=`	AppEnv, componentName, componentVersion, cveId, score, cveState, tags.A, tags.B, tags.xxx	Filters on exact equality. Returns a list of all AppEnv(s)/components containing, e.g., the tag `{tag.xxx:value}`.
`!=`	AppEnv, componentName, componentVersion, cveId, score, cveState, tags.A, tags.B, tags.xxx	Filters on exact inequality. Returns a list of all AppEnv(s)/components that do not contain the tag, e.g., `{tag.xxx:value}`.
`= null`	cveId, tags.A, tags.B, tags.xxx	Returns a list of all unaffected components, and a list of all AppEnv(s)/components that do not contain, e.g., the tag `tag.xxx`.
`!= null`	cveId, tags.A, tags.B, tags.xxx	Returns a list of all vulnerable components, and a list of all AppEnv(s)/components containing the tag, e.g., `tag.xxx`.
`IN ('A', …)`	AppEnv, componentName, componentVersion, cveId, score, cveState, tags.A, tags.B, tags.xxx	Filters on exact equality.
`<=`, `>=`, `<`, `>`	score, componentVersion	Use this filter to compare numbers (`score`) or the string representation of versions (`componentVersion`).
`CONTAINS '…'`	AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx	Filters on the fields containing the given value.

=

AppEnv, componentName, componentVersion, cveId, score, cveState, tags.A, tags.B, tags.xxx

Filters on exact equality. Returns a list of all AppEnv(s)/components containing, e.g., the tag {tag.xxx:value}.

!=

AppEnv, componentName, componentVersion, cveId, score, cveState, tags.A, tags.B, tags.xxx

Filters on exact inequality. Returns a list of all AppEnv(s)/components that do not contain the tag, e.g., {tag.xxx:value}.

= null

cveId, tags.A, tags.B, tags.xxx

Returns a list of all unaffected components, and a list of all AppEnv(s)/components that do not contain, e.g., the tag tag.xxx.

!= null

cveId, tags.A, tags.B, tags.xxx

Returns a list of all vulnerable components, and a list of all AppEnv(s)/components containing the tag, e.g., tag.xxx.

IN ('A', …)

AppEnv, componentName, componentVersion, cveId, score, cveState, tags.A, tags.B, tags.xxx

Filters on exact equality.

<=, >=, <, >

score, componentVersion

Use this filter to compare numbers (score) or the string representation of versions (componentVersion).

CONTAINS '…'

AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx

Filters on the fields containing the given value.

Sorting Rules

It is possible to sort by AppEnv, componentName, componentVersion, cveId, score, cveState, firstSeen, lastSeen. The default sort is:

 "sortBy": [
    "AppEnv=ASC",
    "componentName=ASC",
    "componentVersion=DESC"
    "cveState=DESC",
    "cveId=DESC"
]

Response Structure

 {
  "reportName": "<string>",
  "reportId": "<string>",
  "state": "<string>",
  "userId": "<string>",
  "params": {
    "resolvedFrom": "<date & time ISO 8601 string>",
    "resolvedTo": "<date & time ISO 8601 string>",
    "from": "<date & time string>",
    "to": "<date & time string>",
    "filter": [<List of "field cindition value">],
    "sortBy": [<List of "field = direction">]
  },
  "stateMessages": [<List of string>],
  "requestTime": "<date & time ISO 8601 string>",
  "startTime": "<date & time ISO 8601 string>",
  "finishTime": <date & time ISO 8601 string>,
  "data": [ <List of "Vulnerability Detection" objects:
    {
      "AppEnv": "<string>",
      "componentName": "<string>",
      "componentVersion": "<string>",
      "cveId": "<string>",
      "score": <decimal>,
      "cveState": "<string>",
      "firstSeen": "<date & time ISO 8601 string>",
      "lastSeen": "<date & time ISO 8601 string>",
      "tags": {
        "<string>": ["<string>", "<string>", "<string>"]
        "<string>": ["<string>", "<string>"],
        "<string>": ["<string>"],
        ...
      }
    }
  >],
  "totalCount": <numeric>,
  "afterToken": "<string>"
}

API V1

Request Parameters

You can extend the request with a filter for one or more fields.

Argument Default Description

Argument	Default	Description
hostName	string	Filter by host name.
vmId	string	Filter by VM ID.
startTime	string	Relative or absolute time for the VM start time. See API Date Filter Format.
endTime	string	Relative or absolute time for the VM end time (lastHeardTime). See API Date Filter Format.
cveAnalysisStartTime	string	Filter results with CVE analysis time greater than of equal to the provided parameter value. Format: `2023-01-01T00:00:00`
cveAnalysisEndTime	string	Filter results with CVE analysis time less than of equal to the provided parameter value. Format: `2023-01-01T00:00:00`
afterToken	string	Token representing the offset to get the next page of data. For correct pagination, need to use the 'afterToken' returned in the current response to get the next page of data.
limit	integer	Number of items per data page with results. For correct pagination, need to use the 'limit' returned in the current response to get the next page of data. Default value: `100`
tags.TAG_KEY	object	A custom user tag that can be assigned when a VM starts up. Results can be filtered by tags. `# Format { "TAG_KEY_NAME_1": "TAG_VALUE_1", "TAG_KEY_NAME_2": "TAG_VALUE_2", "TAG_KEY_NAME_3": "TAG_VALUE_3", ... } # For example { "tags.team": "credit-team", "tags.service": "credit-service" }`
showNotImpacted	boolean	The flag specifies whether detected components with no CVEs attached are returned in the response. By default, only impacted components are shown. Default value: `false`

hostName

string

Filter by host name.

vmId

string

Filter by VM ID.

startTime

string

Relative or absolute time for the VM start time. See API Date Filter Format.

endTime

string

Relative or absolute time for the VM end time (lastHeardTime). See API Date Filter Format.

cveAnalysisStartTime

string

Filter results with CVE analysis time greater than of equal to the provided parameter value.

Format: 2023-01-01T00:00:00

cveAnalysisEndTime

string

Filter results with CVE analysis time less than of equal to the provided parameter value.

Format: 2023-01-01T00:00:00

afterToken

string

Token representing the offset to get the next page of data. For correct pagination, need to use the 'afterToken' returned in the current response to get the next page of data.

limit

integer

Number of items per data page with results. For correct pagination, need to use the 'limit' returned in the current response to get the next page of data.

Default value: 100

tags.TAG_KEY

object

A custom user tag that can be assigned when a VM starts up. Results can be filtered by tags.

 # Format

{
  "TAG_KEY_NAME_1": "TAG_VALUE_1",
  "TAG_KEY_NAME_2": "TAG_VALUE_2",
  "TAG_KEY_NAME_3": "TAG_VALUE_3",
  ...
}

# For example

{
  "tags.team": "credit-team",
  "tags.service": "credit-service"
}

showNotImpacted

boolean

The flag specifies whether detected components with no CVEs attached are returned in the response. By default, only impacted components are shown.

Default value: false

Example Request

 curl -X 'GET' \
  'https://YOUR_ENDPOINT.azul.com/public/cve/events?vmId=<VM_ID>&startTime=2022-01-01T00%3A00%3A00&endTime=2023-01-01T23%3A59%3A59&tags.owner=owner&tags.team=team&showNotImpacted=false' \
    -H 'accept: application/json' \
    -H 'x-api-key: <API_KEY>' \
    -H 'Content-Type: application/json'

Example Response

 {
  "limit": 100,
  "afterToken": "100",
  "data": [
    {
      "componentName": "spring-context",
      "componentVersion": "5.1.9.RELEASE",
      "cveId": "CVE-2020-5398",
      "score": 7.5,
      "cveState": "USED",
      "cveAnalysisTime": 1687758788095,
      "hostName": "vkvashin-thinkpad",
      "startTime": 1687758339283,
      "lastHeardTime": 1687758639283,
      "vmId": "99f4abdf-3329-454d-93d3-0f18a3bef50b",
      "tags": null
    },
    ....
  ],
  "summary": {
    "warnings": [
      "the exact result count unknown; it is not less than 10000"
    ],
    "totalCount": 10000
  },
  "size": 100,
  "hasNext": true
}