vulnerabilities
Creates, updates, deletes, gets or lists a vulnerabilities resource.
Overview
| Name | vulnerabilities |
| Type | Resource |
| Id | datadog.security.vulnerabilities |
Fields
The following fields are returned by SELECT queries:
- list_vulnerabilities
| Name | Datatype | Description |
|---|---|---|
id | string | The unique ID for this vulnerability. (example: 3ecdfea798f2ce8f6e964805a344945f) |
attributes | object | The JSON:API attributes of the vulnerability. |
relationships | object | Related entities object. |
type | string | The JSON:API type. (vulnerabilities) (example: vulnerabilities) |
Methods
The following methods are available for this resource:
| Name | Accessible by | Required Params | Optional Params | Description |
|---|---|---|---|---|
list_vulnerabilities | select | page[token], page[number], filter[type], filter[cvss.base.score][, filter[cvss.base.severity], filter[cvss.base.vector], filter[cvss.datadog.score][, filter[cvss.datadog.severity], filter[cvss.datadog.vector], filter[status], filter[tool], filter[library.name], filter[library.version], filter[advisory.id], filter[risks.exploitation_probability], filter[risks.poc_exploit_available], filter[risks.exploit_available], filter[risks.epss.score][, filter[risks.epss.severity], filter[language], filter[ecosystem], filter[code_location.location], filter[code_location.file_path], filter[code_location.method], filter[fix_available], filter[repo_digests], filter[origin], filter[running_kernel], filter[asset.name], filter[asset.type], filter[asset.version.first], filter[asset.version.last], filter[asset.repository_url], filter[asset.risks.in_production], filter[asset.risks.under_attack], filter[asset.risks.is_publicly_accessible], filter[asset.risks.has_privileged_access], filter[asset.risks.has_access_to_sensitive_data], filter[asset.environments], filter[asset.teams], filter[asset.arch], filter[asset.operating_system.name], filter[asset.operating_system.version] | Get a list of vulnerabilities.<br /><br />### Pagination<br /><br />Pagination is enabled by default in both vulnerabilities and assets. The size of the page varies depending on the endpoint and cannot be modified. To automate the request of the next page, you can use the links section in the response.<br /><br />This endpoint will return paginated responses. The pages are stored in the links section of the response:<br /><br />JSON<br />{<br /> "data": [...],<br /> "meta": {...},<br /> "links": {<br /> "self": "https://.../api/v2/security/vulnerabilities",<br /> "first": "https://.../api/v2/security/vulnerabilities?page[number]=1&page[token]=abc",<br /> "last": "https://.../api/v2/security/vulnerabilities?page[number]=43&page[token]=abc",<br /> "next": "https://.../api/v2/security/vulnerabilities?page[number]=2&page[token]=abc"<br /> }<br />}<br /><br /><br /><br />- links.previous is empty if the first page is requested.<br />- links.next is empty if the last page is requested.<br /><br />#### Token<br /><br />Vulnerabilities can be created, updated or deleted at any point in time.<br /><br />Upon the first request, a token is created to ensure consistency across subsequent paginated requests.<br /><br />A token is valid only for 24 hours.<br /><br />#### First request<br /><br />We consider a request to be the first request when there is no page[token] parameter.<br /><br />The response of this first request contains the newly created token in the links section.<br /><br />This token can then be used in the subsequent paginated requests.<br /><br />Note: The first request may take longer to complete than subsequent requests.<br /><br />#### Subsequent requests<br /><br />Any request containing valid page[token] and page[number] parameters will be considered a subsequent request.<br /><br />If the token is invalid, a 404 response will be returned.<br /><br />If the page number is invalid, a 400 response will be returned.<br /><br />The returned token is valid for all requests in the pagination sequence. To send paginated requests in parallel, reuse the same token and change only the page[number] parameter.<br /><br />### Filtering<br /><br />The request can include some filter parameters to filter the data to be retrieved. The format of the filter parameters follows the [JSON:API format](https://jsonapi.org/format/#fetching-filtering): filter[$prop_name], where prop_name is the property name in the entity being filtered by.<br /><br />All filters can include multiple values, where data will be filtered with an OR clause: filter[title]=Title1,Title2 will filter all vulnerabilities where title is equal to Title1 OR Title2.<br /><br />String filters are case sensitive.<br /><br />Boolean filters accept true or false as values.<br /><br />Number filters must include an operator as a second filter input: filter[$prop_name][$operator]. For example, for the vulnerabilities endpoint: filter[cvss.base.score][lte]=8.<br /><br />Available operators are: eq (==), lt (<), lte (<=), gt (>) and gte (>=).<br /><br />### Metadata<br /><br />Following [JSON:API format](https://jsonapi.org/format/#document-meta), object including non-standard meta-information.<br /><br />This endpoint includes the meta member in the response. For more details on each of the properties included in this section, check the endpoints response tables.<br /><br />JSON<br />{<br /> "data": [...],<br /> "meta": {<br /> "total": 1500,<br /> "count": 18732,<br /> "token": "some_token"<br /> },<br /> "links": {...}<br />}<br /><br />### Extensions<br /><br />Requests may include extensions to modify the behavior of the requested endpoint. The filter parameters follow the [JSON:API format](https://jsonapi.org/extensions/#extensions) format: ext:$extension_name, where extension_name is the name of the modifier that is being applied.<br /><br />Extensions can only include one value: ext:modifier=value. | |
import_security_vulnerabilities | insert | bom_format, spec_version, metadata, components, vulnerabilities | Import security vulnerabilities from an external scanner in CycloneDX 1.5 format.<br /><br />The payload is validated against the CycloneDX 1.5 JSON schema and the following<br />additional constraints:<br /><br />- metadata, metadata.component, and metadata.component.name are required.<br />- metadata.tools.components must contain exactly one element with a name field.<br />- components cannot be empty. Each component requires bom-ref, type, name, and version.<br />- When type is library, purl is required and must be a valid PURL.<br />- When type is operating-system, name must be one of the supported OS values:<br /> alma, alpine, amazon, azurelinux, bottlerocket, cbl-mariner, chainguard,<br /> centos, debian, fedora, opensuse, opensuse-leap, opensuse-tumbleweed,<br /> oracle, photon, redhat, rocky, slem, sles, ubuntu, wolfi, windows, macos.<br />- vulnerabilities cannot be empty. Each vulnerability requires id, exactly one ratings entry,<br /> and at least one affects entry.<br />- Each affects[].ref must match a bom-ref value in components. |
Parameters
Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.
| Name | Datatype | Description |
|---|---|---|
site | string | The Datadog site (region) for your organization, for example datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com, ap2.datadoghq.com, datadoghq.eu, ddog-gov.com. Resolved from the DD_SITE environment variable when set. Optional: defaults to datadoghq.com, or the value of the DD_SITE environment variable when set; a WHERE value overrides both. |
filter[advisory.id] | string | Filter by advisory ID. (example: CVE-2023-0615) |
filter[asset.arch] | string | Filter by asset architecture. (example: arm64) |
filter[asset.environments] | string | Filter by asset environments. (example: staging) |
filter[asset.name] | string | Filter by asset name. This field supports the usage of wildcards (*). (example: datadog-agent) |
filter[asset.operating_system.name] | string | Filter by asset operating system name. (example: ubuntu) |
filter[asset.operating_system.version] | string | Filter by asset operating system version. (example: 24.04) |
filter[asset.repository_url] | string | Filter by the repository url associated to the asset. (example: github.com/DataDog/datadog-agent.git) |
filter[asset.risks.has_access_to_sensitive_data] | boolean | Filter whether the asset has access to sensitive data or not. (example: false) |
filter[asset.risks.has_privileged_access] | boolean | Filter whether the asset is publicly accessible or not. (example: false) |
filter[asset.risks.in_production] | boolean | Filter whether the asset is in production or not. (example: false) |
filter[asset.risks.is_publicly_accessible] | boolean | Filter whether the asset is publicly accessible or not. (example: false) |
filter[asset.risks.under_attack] | boolean | Filter whether the asset is under attack or not. (example: false) |
filter[asset.teams] | string | Filter by asset teams. (example: compute) |
filter[asset.type] | string | Filter by asset type. |
filter[asset.version.first] | string | Filter by the first version of the asset this vulnerability has been detected on. (example: v1.15.1) |
filter[asset.version.last] | string | Filter by the last version of the asset this vulnerability has been detected on. (example: v1.15.1) |
filter[code_location.file_path] | string | Filter by vulnerability file path. (example: src/Class.java:100) |
filter[code_location.location] | string | Filter by vulnerability location. (example: com.example.Class:100) |
filter[code_location.method] | string | Filter by method. (example: FooBar) |
filter[cvss.base.score][`$op`] | number (double) | Filter by vulnerability base (i.e. from the original advisory) severity score. (example: 5.5) |
filter[cvss.base.severity] | string | Filter by vulnerability base severity. |
filter[cvss.base.vector] | string | Filter by vulnerability base CVSS vector. (example: CVSS:3.0/AV:L/AC:L/PR:L/UI:N/S:U/C:N/I:N/A:H) |
filter[cvss.datadog.score][`$op`] | number (double) | Filter by vulnerability Datadog severity score. (example: 4.3) |
filter[cvss.datadog.severity] | string | Filter by vulnerability Datadog severity. |
filter[cvss.datadog.vector] | string | Filter by vulnerability Datadog CVSS vector. (example: CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:N/I:N/A:H/E:U/RL:X/RC:X/CR:X/IR:X/AR:X/MAV:L/MAC:H/MPR:L/MUI:N/MS:U/MC:N/MI:N/MA:H) |
filter[ecosystem] | string | Filter by ecosystem. (example: Deb) |
filter[fix_available] | boolean | Filter by fix availability. (example: false) |
filter[language] | string | Filter by language. (example: ubuntu) |
filter[library.name] | string | Filter by library name. (example: linux-aws-5.15) |
filter[library.version] | string | Filter by library version. (example: 5.15.0) |
filter[origin] | string | Filter by origin. (example: agentless-scanner) |
filter[repo_digests] | string | Filter by vulnerability repo_digest (when the vulnerability is related to Image asset). (example: sha256:0ae7da091191787229d321e3638e39c319a97d6e20f927d465b519d699215bf7) |
filter[risks.epss.score][`$op`] | number (double) | Filter by vulnerability [EPSS](https://www.first.org/epss/) severity score. (example: 0.00042) |
filter[risks.epss.severity] | string | Filter by vulnerability [EPSS](https://www.first.org/epss/) severity. |
filter[risks.exploit_available] | boolean | Filter by public exploit availability. (example: false) |
filter[risks.exploitation_probability] | boolean | Filter by exploitation probability. (example: false) |
filter[risks.poc_exploit_available] | boolean | Filter by POC exploit availability. (example: false) |
filter[running_kernel] | boolean | Filter for whether the vulnerability affects a running kernel (for vulnerabilities related to a Host asset). (example: true) |
filter[status] | string | Filter by the status of the vulnerability. |
filter[tool] | string | Filter by the tool of the vulnerability. |
filter[type] | string | Filter by vulnerability type. |
page[number] | integer (int64) | The page number to be retrieved. It should be equal or greater than 1 (example: 1) |
page[token] | string | Its value must come from the links section of the response of the first request. Do not manually edit it. (example: b82cef018aab81ed1d4bb4xb35xxfc065da7efa685fbcecdbd338f3015e3afabbbfa3a911b4984_721ee28a-zecb-4e45-9960-c42065b574f4) |
SELECT examples
- list_vulnerabilities
Get a list of vulnerabilities.<br /><br />### Pagination<br /><br />Pagination is enabled by default in both vulnerabilities and assets. The size of the page varies depending on the endpoint and cannot be modified. To automate the request of the next page, you can use the links section in the response.<br /><br />This endpoint will return paginated responses. The pages are stored in the links section of the response:<br /><br />JSON<br />{<br /> "data": [...],<br /> "meta": {...},<br /> "links": {<br /> "self": "https://.../api/v2/security/vulnerabilities",<br /> "first": "https://.../api/v2/security/vulnerabilities?page[number]=1&page[token]=abc",<br /> "last": "https://.../api/v2/security/vulnerabilities?page[number]=43&page[token]=abc",<br /> "next": "https://.../api/v2/security/vulnerabilities?page[number]=2&page[token]=abc"<br /> }<br />}<br /><br /><br /><br />- links.previous is empty if the first page is requested.<br />- links.next is empty if the last page is requested.<br /><br />#### Token<br /><br />Vulnerabilities can be created, updated or deleted at any point in time.<br /><br />Upon the first request, a token is created to ensure consistency across subsequent paginated requests.<br /><br />A token is valid only for 24 hours.<br /><br />#### First request<br /><br />We consider a request to be the first request when there is no page[token] parameter.<br /><br />The response of this first request contains the newly created token in the links section.<br /><br />This token can then be used in the subsequent paginated requests.<br /><br />Note: The first request may take longer to complete than subsequent requests.<br /><br />#### Subsequent requests<br /><br />Any request containing valid page[token] and page[number] parameters will be considered a subsequent request.<br /><br />If the token is invalid, a 404 response will be returned.<br /><br />If the page number is invalid, a 400 response will be returned.<br /><br />The returned token is valid for all requests in the pagination sequence. To send paginated requests in parallel, reuse the same token and change only the page[number] parameter.<br /><br />### Filtering<br /><br />The request can include some filter parameters to filter the data to be retrieved. The format of the filter parameters follows the [JSON:API format](https://jsonapi.org/format/#fetching-filtering): filter[$prop_name], where prop_name is the property name in the entity being filtered by.<br /><br />All filters can include multiple values, where data will be filtered with an OR clause: filter[title]=Title1,Title2 will filter all vulnerabilities where title is equal to Title1 OR Title2.<br /><br />String filters are case sensitive.<br /><br />Boolean filters accept true or false as values.<br /><br />Number filters must include an operator as a second filter input: filter[$prop_name][$operator]. For example, for the vulnerabilities endpoint: filter[cvss.base.score][lte]=8.<br /><br />Available operators are: eq (==), lt (<), lte (<=), gt (>) and gte (>=).<br /><br />### Metadata<br /><br />Following [JSON:API format](https://jsonapi.org/format/#document-meta), object including non-standard meta-information.<br /><br />This endpoint includes the meta member in the response. For more details on each of the properties included in this section, check the endpoints response tables.<br /><br />JSON<br />{<br /> "data": [...],<br /> "meta": {<br /> "total": 1500,<br /> "count": 18732,<br /> "token": "some_token"<br /> },<br /> "links": {...}<br />}<br /><br />### Extensions<br /><br />Requests may include extensions to modify the behavior of the requested endpoint. The filter parameters follow the [JSON:API format](https://jsonapi.org/extensions/#extensions) format: ext:$extension_name, where extension_name is the name of the modifier that is being applied.<br /><br />Extensions can only include one value: ext:modifier=value.
SELECT
id,
attributes,
relationships,
type
FROM datadog.security.vulnerabilities
WHERE page[token] = '{{ page[token] }}'
AND page[number] = '{{ page[number] }}'
AND filter[type] = '{{ filter[type] }}'
AND filter[cvss.base.score][`$op`] = '{{ filter[cvss.base.score][`$op`] }}'
AND filter[cvss.base.severity] = '{{ filter[cvss.base.severity] }}'
AND filter[cvss.base.vector] = '{{ filter[cvss.base.vector] }}'
AND filter[cvss.datadog.score][`$op`] = '{{ filter[cvss.datadog.score][`$op`] }}'
AND filter[cvss.datadog.severity] = '{{ filter[cvss.datadog.severity] }}'
AND filter[cvss.datadog.vector] = '{{ filter[cvss.datadog.vector] }}'
AND filter[status] = '{{ filter[status] }}'
AND filter[tool] = '{{ filter[tool] }}'
AND filter[library.name] = '{{ filter[library.name] }}'
AND filter[library.version] = '{{ filter[library.version] }}'
AND filter[advisory.id] = '{{ filter[advisory.id] }}'
AND filter[risks.exploitation_probability] = '{{ filter[risks.exploitation_probability] }}'
AND filter[risks.poc_exploit_available] = '{{ filter[risks.poc_exploit_available] }}'
AND filter[risks.exploit_available] = '{{ filter[risks.exploit_available] }}'
AND filter[risks.epss.score][`$op`] = '{{ filter[risks.epss.score][`$op`] }}'
AND filter[risks.epss.severity] = '{{ filter[risks.epss.severity] }}'
AND filter[language] = '{{ filter[language] }}'
AND filter[ecosystem] = '{{ filter[ecosystem] }}'
AND filter[code_location.location] = '{{ filter[code_location.location] }}'
AND filter[code_location.file_path] = '{{ filter[code_location.file_path] }}'
AND filter[code_location.method] = '{{ filter[code_location.method] }}'
AND filter[fix_available] = '{{ filter[fix_available] }}'
AND filter[repo_digests] = '{{ filter[repo_digests] }}'
AND filter[origin] = '{{ filter[origin] }}'
AND filter[running_kernel] = '{{ filter[running_kernel] }}'
AND filter[asset.name] = '{{ filter[asset.name] }}'
AND filter[asset.type] = '{{ filter[asset.type] }}'
AND filter[asset.version.first] = '{{ filter[asset.version.first] }}'
AND filter[asset.version.last] = '{{ filter[asset.version.last] }}'
AND filter[asset.repository_url] = '{{ filter[asset.repository_url] }}'
AND filter[asset.risks.in_production] = '{{ filter[asset.risks.in_production] }}'
AND filter[asset.risks.under_attack] = '{{ filter[asset.risks.under_attack] }}'
AND filter[asset.risks.is_publicly_accessible] = '{{ filter[asset.risks.is_publicly_accessible] }}'
AND filter[asset.risks.has_privileged_access] = '{{ filter[asset.risks.has_privileged_access] }}'
AND filter[asset.risks.has_access_to_sensitive_data] = '{{ filter[asset.risks.has_access_to_sensitive_data] }}'
AND filter[asset.environments] = '{{ filter[asset.environments] }}'
AND filter[asset.teams] = '{{ filter[asset.teams] }}'
AND filter[asset.arch] = '{{ filter[asset.arch] }}'
AND filter[asset.operating_system.name] = '{{ filter[asset.operating_system.name] }}'
AND filter[asset.operating_system.version] = '{{ filter[asset.operating_system.version] }}'
;
INSERT examples
- import_security_vulnerabilities
- Manifest
Import security vulnerabilities from an external scanner in CycloneDX 1.5 format.<br /><br />The payload is validated against the CycloneDX 1.5 JSON schema and the following<br />additional constraints:<br /><br />- metadata, metadata.component, and metadata.component.name are required.<br />- metadata.tools.components must contain exactly one element with a name field.<br />- components cannot be empty. Each component requires bom-ref, type, name, and version.<br />- When type is library, purl is required and must be a valid PURL.<br />- When type is operating-system, name must be one of the supported OS values:<br /> alma, alpine, amazon, azurelinux, bottlerocket, cbl-mariner, chainguard,<br /> centos, debian, fedora, opensuse, opensuse-leap, opensuse-tumbleweed,<br /> oracle, photon, redhat, rocky, slem, sles, ubuntu, wolfi, windows, macos.<br />- vulnerabilities cannot be empty. Each vulnerability requires id, exactly one ratings entry,<br /> and at least one affects entry.<br />- Each affects[].ref must match a bom-ref value in components.
INSERT INTO datadog.security.vulnerabilities (
bom_format,
components,
metadata,
spec_version,
version,
vulnerabilities
)
SELECT
'{{ bom_format }}' /* required */,
'{{ components }}' /* required */,
'{{ metadata }}' /* required */,
'{{ spec_version }}' /* required */,
{{ version }},
'{{ vulnerabilities }}' /* required */
;
# Description fields are for documentation purposes
- name: vulnerabilities
props:
- name: bom_format
value: "{{ bom_format }}"
description: |
The BOM format identifier. Must be `CycloneDX`.
- name: components
description: |
The list of scanned software components. Cannot be empty.
value:
- bom-ref: "{{ bom-ref }}"
name: "{{ name }}"
purl: "{{ purl }}"
type: "{{ type }}"
version: "{{ version }}"
- name: metadata
description: |
Metadata about the BOM, including the scanned asset and the scanner tool.
value:
component:
bom-ref: "{{ bom-ref }}"
name: "{{ name }}"
type: "{{ type }}"
tools:
components:
- name: "{{ name }}"
type: "{{ type }}"
- name: spec_version
value: "{{ spec_version }}"
description: |
The CycloneDX specification version. Must be `1.5`.
- name: version
value: {{ version }}
description: |
The version number of the BOM document.
- name: vulnerabilities
description: |
The list of detected vulnerabilities. Cannot be empty.
value:
- advisories: "{{ advisories }}"
affects: "{{ affects }}"
analysis:
state: "{{ state }}"
cwes: "{{ cwes }}"
description: "{{ description }}"
detail: "{{ detail }}"
id: "{{ id }}"
ratings: "{{ ratings }}"
references: "{{ references }}"