Test an SBOM document for vulnerabilities
Release status and feature availability
The Snyk REST API is available only for Enterprise plans. For more information, see Plans and pricing.
These endpoints are beta API versions. Some of the functionality may change. For more information, see the Versioning information for the REST API.
Snyk offers a collection of API endpoints to asynchronously test a software bill of materials (SBOM) document. You can use these endpoints to learn more about the vulnerabilities impacting your SBOM and its packages.
Snyk identifies components within the SBOM by their package URL (purl). If a component does not contain a purl or the purl type is not supported, Snyk skips vulnerability analysis for that component. Supported purl types are: apk
, cargo
, cocoapods
, composer
, deb
, gem
, golang
, hex
, maven
, npm
, nuget
, pypi
, rpm
, swift
, and generic
for unmanaged C/C++ dependencies.
How to test an SBOM document
Use the SBOM endpoints to create an SBOM test, check the status, and view the results. Follow these steps:
Create a test by sending an SBOM to Snyk
Testing your SBOM can be a long-running operation. Instead of waiting until the test results are ready, Snyk returns a job_id
after your initial request to send the SBOM and then processes the request asynchronously.
Follow these steps to test an SBOM:
Log in to the Snyk Web UI and retrieve your Organization ID (UUID format), Project ID (UUID), and API key. If you need help in finding these values, see Organization general settings, View and edit Project settings, and Authenticate for the API.
Use any HTTP client, for example,
curl
or Postman, to make a request to the endpoint Create an SBOM test run.
The SBOM document is included as part of the request body as a JSON object. This request creates a test run for your SBOM document.
From the response, get the
job_id
, which is used in the next steps. This is a unique identifier for the test run being performed on your SBOM document.
Check the status of the test (optional)
You can check the status of the test at any time after the initial request.
Using the
job_id
returned from the initial request to the endpoint Create an SBOM test run, make a request to the endpoint Gets an SBOM test run status.A successful request to this endpoint returns the status of your test, which can either be
processing
orfinished
. If the call is not successful, an error will be returned.
View results of the test
When the test is complete, you can view the results for the tested SBOM.
When the status of the test returned is
finished
, make a request to the endpoint Gets an SBOM test run result.View the information returned, which includes summary-level information about the SBOM that was tested and the detailed results.
Troubleshooting for the endpoint Create an SBOM test run
The following response code indicates success.
201 Created
The SBOM test run was successfully created. The response body contains the job ID of the test run.
The following are error states that you may receive when using the API. If you experience issues not covered here or are having trouble resolving these, contact your Solutions Engineer or Technical Success Manager, or submit a request to Snyk Support.
400 Bad Request
The server cannot process the request due to invalid or corrupt data. Review the request and try again.
401 Unauthorized
The authentication method, API token or Bearer token, was invalid. Check that you set the Authorization header correctly.
403 Forbidden
You do not have the permissions required to make the request. This can happen if you are not part of the requested Organization, your Organization is not entitled to use the Snyk API, or you do not have sufficient read access to the requested Project.
429 Too Many Requests
Since the Snyk API is rate-limited, an excessive number of requests will eventually start to be rejected. You need to wait before making any further requests.
500 Internal Server Error
The service encountered an internal system error.
Last updated