SBOM Manager API

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

Import

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

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 (on your client machine)

curl -i -u <UserToken>:<TokenPassword> -F file="@/path/example-bom.xml" -F applicationId=c9920b0b240f405a8fc11c897864e2e5 -X POST "https://<tenant>/platform/api/v2/sbom/import"

Use the returned status URL to check the import status.

{"statusUrl":"api/v2/sbom/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
}

Export

Read permissions are required to export the SBOM.

GET api/v2/sbom/{applidationId}/version/{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.5 (default) or spdx2.3

Example

curl -i -u <UserToken>:<TokenPassword> "https://<tenant>/platform/api/v2/sbom/c9920b0b240f405a8fc11c897864e2e5/version/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 "https://<tenant>/platform/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 a 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}

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

curl -i -u <UserToken>:<TokenPassword> -X GET "https://sbom-test-1.ci-1.mtiq.sonatype.dev/platform/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

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

curl -i -u <UserToken>:<TokenPassword> -X GET "https://<tenant>/platform/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.

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

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

Example

curl -i -u <UserToken>:<TokenPassword> -X DELETE "https://<tenant>/platform/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 packageURL
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"}}' "https://sbom-test-1.ci-1.mtiq.sonatype.dev/platform/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 been already 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 Sonatype 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"}' "https://sbom-test-1.ci-1.mtiq.sonatype.dev/platform/api/v2/sbom/applications/f5dc55cbec7b47a4a21d59140b7c1934/versions/20240312111234920/vulnerability/CVE-2017-7525/analysis"