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

# Import security vulnerabilities

`POST /api/v2/security/vulnerabilities`

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.net/datadog/apis/api-v2.md) · [All operations](https://skmtc.net/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datadog/api-v2/versions/da68bf029e4c/schema)