# 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](https://help.sonatype.com/en/rest-apis.html#sonatype-apis-for-cloud-environments-305276 "Sonatype APIs for Cloud Environments"). ## [Import an SBOM](https://help.sonatype.com/en/sbom-manager-api.html#import-an-sbom_body) 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](https://help.sonatype.com/en/application-rest-api.html "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](https://help.sonatype.com/en/cyclonedx.html#analyzing-an-sbom-162461 "Analyzing an SBOM") for details. ## [Export an SBOM in a specific format](https://help.sonatype.com/en/sbom-manager-api.html#export-an-sbom-in-a-specific-format_body) 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](https://help.sonatype.com/en/application-rest-api.html "Application REST API") to fetch the internal application ID - **SBOM_version** - use the [Get all SBOM Versions](https://help.sonatype.com/en/sbom-manager-api.html#get-all-sbom-versions "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 : "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](https://help.sonatype.com/en/sbom-manager-api.html#get-all-sbom-versions_body) 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 : -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](https://help.sonatype.com/en/sbom-manager-api.html#get-an-sbom-version_body) 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](https://help.sonatype.com/en/application-rest-api.html "Application REST API") to fetch the internal application ID - **SBOM_version** - use the [Get all SBOM Versions](https://help.sonatype.com/en/sbom-manager-api.html#get-all-sbom-versions "Get all SBOM Versions") to fetch the available versions ``` curl -i -u : -X GET "http://localhost:8070/api/v2/sbom/applications/f5dc55cbec7b47a4a21d59140b7c1934/versions/20240312111234920" ``` ``` Apache org.apache.tomcat tomcat-catalina 9.0.14 3942447fac867ae5cdb3229b658f4d48 e6b1000b94e835ffd37f4c6dcbdad43f4b48a02a f498a8ff2dd007e29c2074f5e4b01a9a01775c3ff3aeaf6906ea503bc5791b7b e8f33e424f3f4ed6db76a482fde1a5298970e442c531729119e37991884bdffab4f9426b7ee11fccd074eeda0634d71697d6f88a460dce0ac8d627a29f7d1282 Apache-2.0 pkg:maven/org.apache.tomcat/tomcat-catalina@9.0.14?type=jar ``` ## [Get components from SBOM](https://help.sonatype.com/en/sbom-manager-api.html#get-components-from-sbom_body) 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 : -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](https://help.sonatype.com/en/sbom-manager-api.html#delete-an-sbom_body) Write permissions for the application are required to delete an SBOM. ``` DELETE /api/v2/sbom/applications/{applicationId}/versions/{sbomVersion} ``` Example ``` curl -i -u : -X DELETE "http://localhost:8070/api/v2/sbom/applications/f5dc55cbec7b47a4a21d59140b7c1934/versions/20240312111234920" ``` ## [Add/Update VEX annotations for an SBOM](https://help.sonatype.com/en/sbom-manager-api.html#add-update-vex-annotations-for-an-sbom_body) 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 : -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](https://help.sonatype.com/en/sbom-manager-api.html#delete-vex-annotations_body) 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](https://help.sonatype.com/en/package-url-and-component-identifiers.html "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 : -X DELETE -d '{"hash": "cf05e1449bccc5dae87b"}' "http://localhost:8070/api/v2/sbom/applications/f5dc55cbec7b47a4a21d59140b7c1934/versions/20240312111234920/vulnerability/CVE-2017-7525/analysis" ``` ## [Get Vulnerability Details](https://help.sonatype.com/en/sbom-manager-api.html#get-vulnerability-details_body) 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](https://help.sonatype.com/en/sbom-manager-api.html#cpe-matching-configuration_body) 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 : \ -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 : \ -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](https://help.sonatype.com/en/sbom-manager-api.html#interactive-swagger-ui-215926_body) ### Interactive Swagger UI Use the in-product Swagger interface to interact with the REST APIs to quickly execute API requests, and validate responses. 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](https://help.sonatype.com/en/experimental-apis.html "Experimental APIs"). The REST APIs are arranged in an alphabetical order, with a brief description on usage. 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.