Skip to main content

SBOM Manager API

We recommend using a user token and token password when using the API.

Examples use the localhost environment. Adjust the referencing service and credentials for your own environment. If you are in Sonatype Cloud, use HTTPS and include /platform in your API calls. See more details in REST APIs.

Import an SBOM

Write permissions for the application are required to import a file. The application will have to be created before importing an SBOM.

Note also that SBOMs cannot use UTF-16; you will need to convert them to UTF-8 for them to be properly ingested.

POST /api/v2/sbom/import

  • applicationId - use the GET Application REST API to fetch the internal application ID.

  • file - Full path to the SBOM file to import (as available on your client machine).

  • enableBinaryImport - optional parameter to analyze a binary and generate an SBOM during the import step.

  • applicationVersion - optional parameter to manually set the version of the imported SBOM.

  • ignoreValidationError - optional parameter to import an SBOM if one or more skippable validation errors occur. The default value is false. When set to true, and skippable validation errors occur, only the SBOM components will be imported.

# Upload an SBOM (JSON or XML) – note the @ in front of the path
curl -u admin:admin123 \
  -F file=@/Users/andrewhaigh/Projects/AzureDevOps/struts2-rce/cyclonedx_1_6.sbom.json \
  -F applicationId=8e43cf2b6cd645a79faab71ff864cb45 \
  -F applicationVersion=my_app_version \
  -X POST 'http://localhost:8070/api/v2/sbom/import?ignoreValidationError=true'

Use the returned status URL to check the import status.

{"statusUrl":"api/v2/sbom/applications/c9920b0b240f405a8fc11c897864e2e5/status/a5bd3587cf7d45f3aaa2c09401a47b27"}

When complete, you will receive the details on your imported SBOM.

{
  "downloadUrl":"api/v2/sbom/c9920b0b240f405a8fc11c897864e2e5/version/20240409105223535?form=original",
  "applicationId":"c9920b0b240f405a8fc11c897864e2e5",
  "version":"20240409105223535",
  "isError":false,
  "errorMessage":null
}

Analyzing a Binary for SBOM Import

Include the optional enableBinaryImport property when analyzing a binary archive on importing. This will analyze the binary and generate an SBOM to import in one step.

POST /api/v2/sbom/import?enableBinaryImport=true

Example

curl -i -u admin:admin123 -H "Content-Type: multipart/form-data" -X POST http://localhost:8070/api/v2/sbom/import?enableBinaryImport=true -F "applicationId={applicationId}" -F "file=@uber.jar" -F "applicationVersion=my_app_version"

When importing binaries containing SBOMs, the SBOMs must follow the required naming conventions of including the bom suffix to be picked up by the scanner.

See the CycloneDX documentation for details.

Export an SBOM in a specific format

Read permissions are required to export the SBOM.

GET api/v2/sbom/applications/{applidationId}/versions/{SBOM_version}?state=original&specification=cyclonedx1.5

  • applicationId - use the GET Application REST API to fetch the internal application ID

  • SBOM_version - use the Get all SBOM Versions to fetch the available versions

  • state (optional) - download either the imported or annotated versions.

    • options include: original or current (default)

  • specification (optional) - Target specification of the SBOM.

    • options include: cyclonedx1.2, cyclonedx1.3, cyclonedx1.4, cyclonedx1.5, cyclonedx1.6 (default), spdx2.2, and spdx2.3

Example

curl -i -u <UserToken>:<TokenPassword> "http://localhost:8070/api/v2/sbom/applications/c9920b0b240f405a8fc11c897864e2e5/versions/20240409105223535?state=original"

When successful, the SBOM is returned in the requested state and format.

Get all SBOM Versions

Returns a list of SBOMS for an application. Read permissions for the application are required.

GET /api/v2/sbom/applications/{applicationId}
Optional query parameters

  • sortByDate: Sort results by import date. Allowed values [asc|desc]. The default value is asc

  • pageSize: Number of items to return by page. The default value is 10

  • page: Current page number. The default value is 1

Example

curl -i -u <UserToken>:<TokenPassword> -X GET "http://localhost:8070/api/v2/sbom/applications/f5dc55cbec7b47a4a21d59140b7c1934"
{
  "totalResultsCount": 1,
  "results": [
    {
      "applicationVersion": "20240412170706311",
      "spec": "CycloneDx",
      "specVersion": "1.1",
      "importDate": "2024-04-12T17:07:06.312-05:00",
      "none": 0,
      "low": 0,
      "medium": 6,
      "high": 3,
      "critical": 0
    }
  ]
}

Get an SBOM Version

Downloads a specific SBOM version in its original or current state. Read permission for the applications are required.

GET /api/v2/sbom/applications/{applicationId}/versions/{sbom_version}
curl -i -u <UserToken>:<TokenPassword> -X GET "http://localhost:8070/api/v2/sbom/applications/f5dc55cbec7b47a4a21d59140b7c1934/versions/20240312111234920"
<?xml version="1.0" encoding="UTF-8"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.1" serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1">
    <components>
        <component type="library">
            <publisher>Apache</publisher>
            <group>org.apache.tomcat</group>
            <name>tomcat-catalina</name>
            <version>9.0.14</version>
            <hashes>
                <hash alg="MD5">3942447fac867ae5cdb3229b658f4d48</hash>
                <hash alg="SHA-1">e6b1000b94e835ffd37f4c6dcbdad43f4b48a02a</hash>
                <hash alg="SHA-256">f498a8ff2dd007e29c2074f5e4b01a9a01775c3ff3aeaf6906ea503bc5791b7b</hash>
                <hash alg="SHA-512">e8f33e424f3f4ed6db76a482fde1a5298970e442c531729119e37991884bdffab4f9426b7ee11fccd074eeda0634d71697d6f88a460dce0ac8d627a29f7d1282</hash>
            </hashes>
            <licenses>
                <license>
                    <id>Apache-2.0</id>
                </license>
            </licenses>
            <purl>pkg:maven/org.apache.tomcat/tomcat-catalina@9.0.14?type=jar</purl>
        </component>
    </components>
</bom>

Get components from SBOM

Lists the components in a specific SBOM version with data about vulnerabilities and licenses. Read permissions for the application are required.

GET /api/v2/sbom/applications/{applicationId}/versions/{SBOM_version}/components
curl -i -u <UserToken>:<TokenPassword> -X GET "http://localhost:8070/api/v2/sbom/applications/f5dc55cbec7b47a4a21d59140b7c1934/versions/20240412170706311/components"
[
  {
    "hash": "e6b1000b94e835ffd37f",
    "packageUrl": "pkg:maven/org.apache.tomcat/tomcat-catalina@9.0.14?type=jar",
    "componentIdentifier": {
      "format": "maven",
      "coordinates": {
        "artifactId": "tomcat-catalina",
        "extension": "jar",
        "groupId": "org.apache.tomcat",
        "version": "9.0.14"
      }
    },
    "displayName": "org.apache.tomcat : tomcat-catalina : 9.0.14",
    "licenses": [
      {
        "licenseId": "Apache-2.0",
        "licenseName": "Apache-2.0"
      },
      {
        "licenseId": "Public Domain",
        "licenseName": null
      }
    ],
    "vulnerabilitySeverityNoneCount": 0,
    "vulnerabilitySeverityLowCount": 0,
    "vulnerabilitySeverityMediumCount": 6,
    "vulnerabilitySeverityHighCount": 3,
    "vulnerabilitySeverityCriticalCount": 0
  }
]

Delete an SBOM

Write permissions for the application are required to delete an SBOM.

DELETE /api/v2/sbom/applications/{applicationId}/versions/{sbomVersion}

Example

curl -i -u <UserToken>:<TokenPassword> -X DELETE "http://localhost:8070/api/v2/sbom/applications/f5dc55cbec7b47a4a21d59140b7c1934/versions/20240312111234920"

Add/Update VEX annotations for an SBOM

Adds or updates a VEX annotation to a given component in a specific SBOM version. Write permissions for the application are required to modify VEX annotation.

PUT /api/v2/sbom/applications/{applicationId}/versions/{sbomVersion}/vulnerability/{vulnerabilityRef}/analysis
{
  "componentLocator": {
    "hash": "cf05e1449bccc5dae87b"
  }, 
  "vulnerabilityAnalysis": {
    "state": "exploitable", 
    "justification": "requires_dependency", 
    "response": "can_not_fix", 
    "detail": "no detail"
  }
}

  • componentLocator (required): Locate the component either by hash (SHA-1) or Package-URL

  • vulnerabilityAnalysis: information about the VEX annotation.

    • state (required): vulnerability analysis state

      resolved, resolved_with_pedigree, exploitable, in_triage, false_positive, not_affected

    • justification: The rationale of why the impact analysis state was asserted

      code_not_present, code_not_reachable, requires_configuration, requires_dependency, requires_environment, protected_by_compiler, protected_at_runtime, protected_at_perimeter, protected_by_mitigating_control

    • response: A response to the vulnerability by the manufacturer, supplier, or project responsible for the affected component or service.

      can_not_fix, will_not_fix, update, rollback, workaround_available

    • detail: Detailed description of the impact including methods used during the assessment

curl -i -u <UserToken>:<TokenPassword> -X PUT -d '{"componentLocator": {"hash": "cf05e1449bccc5dae87b"}, "vulnerabilityAnalysis": {"state": "exploitable", "justification": "requires_dependency", "response": "can_not_fix", "detail": "no detail"}}' "http://localhost:8070/api/v2/sbom/applications/f5dc55cbec7b47a4a21d59140b7c1934/versions/20240312111234920/vulnerability/CVE-2017-7525/analysis"

A summary of the update is returned on a successful response.

{
   "createdOn" : "2024-05-29T12:17:15.526-03:00",
   "detail" : null,
   "justification" : null,
   "lastUpdatedBy" : "jmartin",
   "lastUpdatedOn" : "2024-05-29T12:17:15.526-03:00",
   "response" : "can_not_fix",
   "state" : "exploitable"
}

Update

The annotation is updated when one has already been added. The lastUpdatedOn and lastUpdatedBy fields are modified when VEX annotations are added.

Delete VEX annotations

Write permissions for the application are required to delete VEX annotations for a specific component's vulnerability.

DELETE /api/v2/sbom/applications/{applicationId}/versions/{sbomVersion}/vulnerability/{vulnerabilityRef}/analysis
{
  "hash": "cf05e1449bccc5dae87b",
  "packageUrl": "pkg:maven/org.apache.tomcat/tomcat-catalina@9.0.14?type=jar"
}

Either the component hash or packageUrl is required but not both. See Package URLs (purl) and Component Identifiers to learn more.

  • hash: The component’s truncated SHA1. Found in the URL of the component details view or using the get Components API for a specific SBOM version.

  • packageUrl: Component’s Package-URL

curl -i -u <UserToken>:<TokenPassword> -X DELETE -d '{"hash": "cf05e1449bccc5dae87b"}' "http://localhost:8070/api/v2/sbom/applications/f5dc55cbec7b47a4a21d59140b7c1934/versions/20240312111234920/vulnerability/CVE-2017-7525/analysis"

Get Vulnerability Details

Retrieve detailed vulnerability data for a specific SBOM version by supplying either a component hash or a package‑URL.

GET /api/v2/sbom/applications/{applicationId}/versions/{version}/vulnerability/{refId}?componentHash={hash}&packageUrl={packageUrl}
Path Parameters

  • applicationId - internal application ID.

  • version - SBOM version (e.g. 1.1.2).

  • refId - vulnerability ID (e.g. CVE-2022-23437).

Query Parameters

Note

Only one of componentHash or packageUrl is required; you may supply both but it is not necessary.

  • componentHash - truncated SHA‑1 of the component.

  • packageUrl - component’s Package‑URL.

Example

curl -u admin:admin123 \
  -X GET "http://localhost:8070/api/v2/sbom/applications/0179fb84aaf346209aafae620cae2bdb/versions/1.1.2/vulnerability/CVE-2022-23437?componentHash=f02c844149fd306601f2"
{
    "identifier": "CVE-2022-23437",
    "vulnIds": [
        "CVE-2022-23437"
    ],
    "vulnerabilityLink": "http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2022-23437",
    "source": {
        "shortName": "CVE",
        "longName": "National Vulnerability Database"
    },
    "mainSeverity": {
        "source": "cve_cvss_3",
        "sourceLabel": "CVE CVSS 3",
        "score": 6.5,
        "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:U/C:N/I:N/A:H"
    },
    "severityScores": [
        {
            "source": "cve_cvss_2",
            "sourceLabel": "CVE CVSS 2.0",
            "score": 7.1
        },
        {
            "source": "sonatype_cvss_3",
            "sourceLabel": "Sonatype CVSS 3",
            "score": 7.5
        }
    ],
    "weakness": {
        "cweSource": "CVE",
        "cweIds": [
            {
                "id": "835",
                "uri": "https://cwe.mitre.org/data/definitions/835.html"
            }
        ]
    },
    "categories": [
        "data"
    ],
    "description": "There's a vulnerability within the Apache Xerces Java (XercesJ) XML parser when handling specially crafted XML document payloads. This causes, the XercesJ XML parser to wait in an infinite loop, which may sometimes consume system resources for prolonged duration. This vulnerability is present within XercesJ version 2.12.1 and the previous versions.",
    "explanationMarkdown": "The `xercesImpl` package is vulnerable to Excessive Iteration. The `scanChar()` function in the `XMLEntityScanner.class` and `XML11EntityScanner.class` files contain an iteration with an exit condition that cannot be reached. A remote attacker can exploit this behavior by supplying a specially-crafted XML entity that will result in an infinite loop and cause an unexpected consumption of resources when parsed.",
    "componentExplanationMarkdown": "",
    "detectionMarkdown": "The application is vulnerable by using this component.",
    "componentDetectionMarkdown": "",
    "recommendationMarkdown": "We recommend upgrading to a version of this component that is not vulnerable to this specific issue.\n\nNote: If this component is included as a bundled/transitive dependency of another component, there may not be an upgrade path. In this instance, we recommend contacting the maintainers who included the vulnerable package. Alternatively, we recommend investigating alternative components or a potential mitigating control.",
    "componentRecommendationMarkdown": "",
    "rootCauses": [
        {
            "listOfPaths": [
                "xercesImpl-2.12.0.jar",
                "org/apache/xerces/impl/XML11EntityScanner.class"
            ],
            "versionRange": "[2.3.0 , 2.12.2)"
        },
        {
            "listOfPaths": [
                "xercesImpl-2.12.0.jar",
                "org/apache/xerces/impl/XMLEntityScanner.class"
            ],
            "versionRange": "[2.3.0 , 2.12.2)"
        }
    ],
    "advisories": [
        {
            "referenceType": "PROJECT",
            "url": "https://lists.apache.org/thread/6pjwm10bb69kq955fzr1n0nflnjd27dl"
        },
        {
            "referenceType": "THIRD_PARTY",
            "url": "http://www.openwall.com/lists/oss-security/2022/01/24/3"
        }
    ],
    "vulnerableVersionRanges": [
        "[2.12.0,2.12.1]"
    ],
    "researchType": "DEEP_DIVE",
    "isAdvancedVulnerabilityDetection": true,
    "detectionType": "SECONDARY",
    "kevData": {
        "isKev": false
    },
    "epssData": {
        "currentScore": 7.7E-4
    },
    "identificationSource": "Sonatype"
}

CPE Matching Configuration

With a Sonatype Lifecycle license, you can use the CPE Matching Configuration REST API to configure CPE matching for your organizations and applications.

Get CPE Matching Configuration

Returns the current CPE Matching settings for an application or organization.

Read permissions for the selected owner are required.

GET /api/v2/sbom/applications/{applicationId}/{ownerType}/{internalOwnerId}/configuration/publicSource/cpe
Path Variables

  • ownerType - Type of owner. Allowed values: application | organization

  • internalOwnerId - Internal ID of the application or organization

Example:

curl -i -u <UserToken>:<TokenPassword> \
  -X GET "http://localhost:8070/api/v2/application/3fa85f64e7/configuration/publicSource/cpe"
{
  "inheritedFromOrganizationName": "finance-services",
  "enabledInParent": true,
  "allowOverride": false,
  "enabled": true
}

  • enabled - true if CPE Matching is active for the specified owner

  • allowOverride - true if child applications may override the setting

  • enabledInParent - true if CPE Matching is enabled in any parent organization

  • inheritedFromOrganizationName - parent organization providing the effective setting, or omitted when not inherited.

Set/Update CPE Matching Configuration

Enables or updates CPE Matching for an application or organization.

Write permissions for the selected owner are required.

PUT /api/v2/sbom/applications/{applicationId}/{ownerType}/{internalOwnerId}/configuration/publicSource/cpe
Payload Fields

  • enabled - true if CPE Matching is active for the specified owner

  • allowOverride - true if child applications may override the setting

Example:

curl -i -u <UserToken>:<TokenPassword> \
  -H "Content-Type: application/json" \
  -d '{"allowOverride":false,"enabled":true}' \
  -X PUT "http://localhost:8070/api/v2/application/3fa85f64e7/configuration/publicSource/cpe"
{
  "allowOverride": false,
  "enabled": true
}

Interactive Swagger UI

Interactive Swagger UI

Use the in-product Swagger interface to interact with the REST APIs to quickly execute API requests, and validate responses.

APi_option_in_left_nav.png

The API option in the left navigation bar displays the API page.

Click on the Public tab to access all REST APIs supported by Sonatype for your product.

REST APIs under the Experimental tab are evolving and are not recommended for critical workloads. We strongly recommend using them controlled environments at your own risk. Learn more about Experimental APIs.

The REST APIs are arranged in an alphabetical order, with a brief description on usage.

methods.png

Click on the dropdown arrow at the right end of the method names to expand the method descriptions.

Check the Permissions required to ensure you have the correct permissions to execute/try out the method.

The Swagger interface also enables you to import the REST APIs into any tool that supports OpenAPI (version 3), for downstream application development.