---
title: "Import security vulnerabilities"
method: POST
path: "/api/v2/security/vulnerabilities"
tags: ["Security Monitoring"]
---

# Import security vulnerabilities

`POST /api/v2/security/vulnerabilities`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/security/vulnerabilities`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `security_monitoring_findings_write`

Import security vulnerabilities from an external scanner in CycloneDX 1.5 format.

The payload is validated against the CycloneDX 1.5 JSON schema and the following
additional constraints:

- `metadata`, `metadata.component`, and `metadata.component.name` are required.
- `metadata.tools.components` must contain exactly one element with a `name` field.
- `components` cannot be empty. Each component requires `bom-ref`, `type`, `name`, and `version`.
- When `type` is `library`, `purl` is required and must be a valid PURL.
- When `type` is `operating-system`, `name` must be one of the supported OS values:
  `alma`, `alpine`, `amazon`, `azurelinux`, `bottlerocket`, `cbl-mariner`, `chainguard`,
  `centos`, `debian`, `fedora`, `opensuse`, `opensuse-leap`, `opensuse-tumbleweed`,
  `oracle`, `photon`, `redhat`, `rocky`, `slem`, `sles`, `ubuntu`, `wolfi`, `windows`, `macos`.
- `vulnerabilities` cannot be empty. Each vulnerability requires `id`, exactly one `ratings` entry,
  and at least one `affects` entry.
- Each `affects[].ref` must match a `bom-ref` value in `components`.

## Request body

- CycloneDXBom: A CycloneDX 1.5 Bill of Materials (BOM) document containing vulnerability data.
  - `bomFormat` string, required: The BOM format identifier. Must be `CycloneDX`.
  - `components` CycloneDXComponent[], required: The list of scanned software components. Cannot be empty.
    - `bom-ref` string, required: A unique reference identifier used to link vulnerabilities to this component.
    - `name` string, required: The name of the component.
    - `purl` string: The Package URL (PURL) of the component. Required when `type` is `library`.
    - `type` 'library' | 'application' | 'operating-system', required: The type of the scanned component.
    - `version` string, required: The version of the component.
  - `metadata` CycloneDXMetadata, required: Metadata about the BOM, including the scanned asset and the scanner tool.
    - `component` CycloneDXMetadataComponent, required: The asset that was scanned (for example, a host or container image).
      - `bom-ref` string: A unique reference identifier for this metadata component. If set, must match a `bom-ref` in `components`.
      - `name` string, required: The name or identifier of the scanned asset (for example, an instance ID or hostname).
      - `type` string: The type of the scanned asset.
    - `tools` CycloneDXMetadataTools, required: Information about the scanner tool that produced this BOM.
      - `components` CycloneDXToolComponent[], required: The scanner tool components. Must contain exactly one element.
        - `name` string, required: The name of the scanner tool.
        - `type` string: The type of the tool component.
  - `specVersion` string, required: The CycloneDX specification version. Must be `1.5`.
  - `version` integer: The version number of the BOM document.
  - `vulnerabilities` CycloneDXVulnerability[], required: The list of detected vulnerabilities. Cannot be empty.
    - `advisories` CycloneDXVulnerabilityAdvisory[]: External advisory references for the vulnerability.
      - `url` string: The URL of the advisory.
    - `affects` CycloneDXVulnerabilityAffects[], required: The components affected by this vulnerability. Must be non-empty. Each `ref` must match a `bom-ref` in `components`.
      - `ref` string, required: The `bom-ref` of the affected component.
    - `analysis` CycloneDXVulnerabilityAnalysis: The exploitability analysis for the vulnerability. When `state` is set to `resolved` or `resolved_with_pedigree`, the vulnerability is closed in Datadog. Other state values are accepted but have no effect on the vulnerability status.
      - `state` string: The vulnerability analysis state.
    - `cwes` integer[]: CWE identifiers associated with the vulnerability.
    - `description` string: A short description of the vulnerability.
    - `detail` string: Detailed information about the vulnerability.
    - `id` string, required: The vulnerability identifier (for example, a CVE ID).
    - `ratings` CycloneDXVulnerabilityRating[], required: The severity ratings for the vulnerability. Must contain exactly one element.
      - `score` number, double: The CVSS score.
      - `severity` string: The severity level.
      - `vector` string: The CVSS vector string.
    - `references` CycloneDXVulnerabilityReference[]: External reference identifiers for the vulnerability.
      - `id` string: The identifier of the external reference (for example, a GHSA ID).
      - `source` CycloneDXVulnerabilityReferenceSource: The source of an external vulnerability reference.
        - `url` string: The URL of the reference source.

## Response `200`

Vulnerabilities accepted successfully.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `429`: Too many requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/da68bf029e4c?raw)