For AI agents: A markdown version of this page is available at https://dnd37xeb23o8n.cloudfront.net/stefon.simmons/docs-astro-web-10435/api/latest/security-monitoring/import-security-vulnerabilities.md. A documentation index is available at /llms.txt.
homeHomedocsDocsapiAPI
Language
Datadog site

Import security vulnerabilities

WARNINGNote: This endpoint is in preview and is subject to change. If you have any feedback, contact Datadog support.
POSThttps://api.datadoghq.com/api/v2/security/vulnerabilitieshttps://api.us3.datadoghq.com/api/v2/security/vulnerabilitieshttps://api.us5.datadoghq.com/api/v2/security/vulnerabilitieshttps://api.datadoghq.eu/api/v2/security/vulnerabilitieshttps://api.ap1.datadoghq.com/api/v2/security/vulnerabilitieshttps://api.ap2.datadoghq.com/api/v2/security/vulnerabilitieshttps://api.uk1.datadoghq.com/api/v2/security/vulnerabilitieshttps://api.ddog-gov.com/api/v2/security/vulnerabilitieshttps://api.us2.ddog-gov.com/api/v2/security/vulnerabilities

Overview

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.

This endpoint requires the security_monitoring_findings_write permission.

OAuth apps require the security_monitoring_findings_write authorization scope to access this endpoint.

Request

Body Data (required)

Field
Type
Description
bomFormat [required]
string

The BOM format identifier. Must be CycloneDX.

components [required]
[object]

The list of scanned software components. Cannot be empty.

metadata [required]
object

Metadata about the BOM, including the scanned asset and the scanner tool.

specVersion [required]
string

The CycloneDX specification version. Must be 1.5.

version
int64

The version number of the BOM document.

vulnerabilities [required]
[object]

The list of detected vulnerabilities. Cannot be empty.

Response

Vulnerabilities accepted successfully.

Code Example

# Set your Datadog site and credentials
export DD_SITE="datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/security/vulnerabilities" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "bomFormat": "CycloneDX",
  "components": [
    {
      "bom-ref": "a3390fca-c315-41ae-ae05-af5e7859cdee",
      "name": "lodash",
      "purl": "pkg:npm/lodash@4.17.21",
      "type": "library",
      "version": "4.17.21"
    }
  ],
  "metadata": {
    "component": {
      "name": "i-12345",
      "type": "operating-system"
    },
    "tools": {
      "components": [
        {
          "name": "my-scanner",
          "type": "application"
        }
      ]
    }
  },
  "specVersion": "1.5",
  "version": 1,
  "vulnerabilities": [
    {
      "affects": [
        {
          "ref": "a3390fca-c315-41ae-ae05-af5e7859cdee"
        }
      ],
      "description": "Sample vulnerability detected in the application.",
      "id": "CVE-2021-1234",
      "ratings": [
        {
          "score": 9,
          "severity": "high",
          "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N"
        }
      ]
    }
  ]
}
EOF
# Set your Datadog site and credentials
export DD_SITE="us3.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/security/vulnerabilities" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "bomFormat": "CycloneDX",
  "components": [
    {
      "bom-ref": "a3390fca-c315-41ae-ae05-af5e7859cdee",
      "name": "lodash",
      "purl": "pkg:npm/lodash@4.17.21",
      "type": "library",
      "version": "4.17.21"
    }
  ],
  "metadata": {
    "component": {
      "name": "i-12345",
      "type": "operating-system"
    },
    "tools": {
      "components": [
        {
          "name": "my-scanner",
          "type": "application"
        }
      ]
    }
  },
  "specVersion": "1.5",
  "version": 1,
  "vulnerabilities": [
    {
      "affects": [
        {
          "ref": "a3390fca-c315-41ae-ae05-af5e7859cdee"
        }
      ],
      "description": "Sample vulnerability detected in the application.",
      "id": "CVE-2021-1234",
      "ratings": [
        {
          "score": 9,
          "severity": "high",
          "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N"
        }
      ]
    }
  ]
}
EOF
# Set your Datadog site and credentials
export DD_SITE="us5.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/security/vulnerabilities" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "bomFormat": "CycloneDX",
  "components": [
    {
      "bom-ref": "a3390fca-c315-41ae-ae05-af5e7859cdee",
      "name": "lodash",
      "purl": "pkg:npm/lodash@4.17.21",
      "type": "library",
      "version": "4.17.21"
    }
  ],
  "metadata": {
    "component": {
      "name": "i-12345",
      "type": "operating-system"
    },
    "tools": {
      "components": [
        {
          "name": "my-scanner",
          "type": "application"
        }
      ]
    }
  },
  "specVersion": "1.5",
  "version": 1,
  "vulnerabilities": [
    {
      "affects": [
        {
          "ref": "a3390fca-c315-41ae-ae05-af5e7859cdee"
        }
      ],
      "description": "Sample vulnerability detected in the application.",
      "id": "CVE-2021-1234",
      "ratings": [
        {
          "score": 9,
          "severity": "high",
          "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N"
        }
      ]
    }
  ]
}
EOF
# Set your Datadog site and credentials
export DD_SITE="datadoghq.eu"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/security/vulnerabilities" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "bomFormat": "CycloneDX",
  "components": [
    {
      "bom-ref": "a3390fca-c315-41ae-ae05-af5e7859cdee",
      "name": "lodash",
      "purl": "pkg:npm/lodash@4.17.21",
      "type": "library",
      "version": "4.17.21"
    }
  ],
  "metadata": {
    "component": {
      "name": "i-12345",
      "type": "operating-system"
    },
    "tools": {
      "components": [
        {
          "name": "my-scanner",
          "type": "application"
        }
      ]
    }
  },
  "specVersion": "1.5",
  "version": 1,
  "vulnerabilities": [
    {
      "affects": [
        {
          "ref": "a3390fca-c315-41ae-ae05-af5e7859cdee"
        }
      ],
      "description": "Sample vulnerability detected in the application.",
      "id": "CVE-2021-1234",
      "ratings": [
        {
          "score": 9,
          "severity": "high",
          "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N"
        }
      ]
    }
  ]
}
EOF
# Set your Datadog site and credentials
export DD_SITE="ap1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/security/vulnerabilities" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "bomFormat": "CycloneDX",
  "components": [
    {
      "bom-ref": "a3390fca-c315-41ae-ae05-af5e7859cdee",
      "name": "lodash",
      "purl": "pkg:npm/lodash@4.17.21",
      "type": "library",
      "version": "4.17.21"
    }
  ],
  "metadata": {
    "component": {
      "name": "i-12345",
      "type": "operating-system"
    },
    "tools": {
      "components": [
        {
          "name": "my-scanner",
          "type": "application"
        }
      ]
    }
  },
  "specVersion": "1.5",
  "version": 1,
  "vulnerabilities": [
    {
      "affects": [
        {
          "ref": "a3390fca-c315-41ae-ae05-af5e7859cdee"
        }
      ],
      "description": "Sample vulnerability detected in the application.",
      "id": "CVE-2021-1234",
      "ratings": [
        {
          "score": 9,
          "severity": "high",
          "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N"
        }
      ]
    }
  ]
}
EOF
# Set your Datadog site and credentials
export DD_SITE="ap2.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/security/vulnerabilities" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "bomFormat": "CycloneDX",
  "components": [
    {
      "bom-ref": "a3390fca-c315-41ae-ae05-af5e7859cdee",
      "name": "lodash",
      "purl": "pkg:npm/lodash@4.17.21",
      "type": "library",
      "version": "4.17.21"
    }
  ],
  "metadata": {
    "component": {
      "name": "i-12345",
      "type": "operating-system"
    },
    "tools": {
      "components": [
        {
          "name": "my-scanner",
          "type": "application"
        }
      ]
    }
  },
  "specVersion": "1.5",
  "version": 1,
  "vulnerabilities": [
    {
      "affects": [
        {
          "ref": "a3390fca-c315-41ae-ae05-af5e7859cdee"
        }
      ],
      "description": "Sample vulnerability detected in the application.",
      "id": "CVE-2021-1234",
      "ratings": [
        {
          "score": 9,
          "severity": "high",
          "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N"
        }
      ]
    }
  ]
}
EOF
# Set your Datadog site and credentials
export DD_SITE="uk1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/security/vulnerabilities" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "bomFormat": "CycloneDX",
  "components": [
    {
      "bom-ref": "a3390fca-c315-41ae-ae05-af5e7859cdee",
      "name": "lodash",
      "purl": "pkg:npm/lodash@4.17.21",
      "type": "library",
      "version": "4.17.21"
    }
  ],
  "metadata": {
    "component": {
      "name": "i-12345",
      "type": "operating-system"
    },
    "tools": {
      "components": [
        {
          "name": "my-scanner",
          "type": "application"
        }
      ]
    }
  },
  "specVersion": "1.5",
  "version": 1,
  "vulnerabilities": [
    {
      "affects": [
        {
          "ref": "a3390fca-c315-41ae-ae05-af5e7859cdee"
        }
      ],
      "description": "Sample vulnerability detected in the application.",
      "id": "CVE-2021-1234",
      "ratings": [
        {
          "score": 9,
          "severity": "high",
          "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N"
        }
      ]
    }
  ]
}
EOF
# Set your Datadog site and credentials
export DD_SITE="ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/security/vulnerabilities" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "bomFormat": "CycloneDX",
  "components": [
    {
      "bom-ref": "a3390fca-c315-41ae-ae05-af5e7859cdee",
      "name": "lodash",
      "purl": "pkg:npm/lodash@4.17.21",
      "type": "library",
      "version": "4.17.21"
    }
  ],
  "metadata": {
    "component": {
      "name": "i-12345",
      "type": "operating-system"
    },
    "tools": {
      "components": [
        {
          "name": "my-scanner",
          "type": "application"
        }
      ]
    }
  },
  "specVersion": "1.5",
  "version": 1,
  "vulnerabilities": [
    {
      "affects": [
        {
          "ref": "a3390fca-c315-41ae-ae05-af5e7859cdee"
        }
      ],
      "description": "Sample vulnerability detected in the application.",
      "id": "CVE-2021-1234",
      "ratings": [
        {
          "score": 9,
          "severity": "high",
          "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N"
        }
      ]
    }
  ]
}
EOF
# Set your Datadog site and credentials
export DD_SITE="us2.ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/security/vulnerabilities" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "bomFormat": "CycloneDX",
  "components": [
    {
      "bom-ref": "a3390fca-c315-41ae-ae05-af5e7859cdee",
      "name": "lodash",
      "purl": "pkg:npm/lodash@4.17.21",
      "type": "library",
      "version": "4.17.21"
    }
  ],
  "metadata": {
    "component": {
      "name": "i-12345",
      "type": "operating-system"
    },
    "tools": {
      "components": [
        {
          "name": "my-scanner",
          "type": "application"
        }
      ]
    }
  },
  "specVersion": "1.5",
  "version": 1,
  "vulnerabilities": [
    {
      "affects": [
        {
          "ref": "a3390fca-c315-41ae-ae05-af5e7859cdee"
        }
      ],
      "description": "Sample vulnerability detected in the application.",
      "id": "CVE-2021-1234",
      "ratings": [
        {
          "score": 9,
          "severity": "high",
          "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N"
        }
      ]
    }
  ]
}
EOF