REST API endpoint: 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 versions. Some of the functionality may change. For more information, see Versioning in the Snyk REST API reference documentation.

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.

Supported SBOM formats are CycloneDX 1.4 JSON and SPDX 2.3 JSON.

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.

Follow these steps to create an SBOM test run and view the results.

1. Create the test by sending an SBOM to Snyk.

2. Check the status of the test.

3. View the test results when the test is complete.

How to test an SBOM document

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:

1. 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 Group and Organization navigation, View Project settings, and Authentication for API.

2. 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.

HTTP request

curl --request POST \
    -H "Authorization: token <SNYK_TOKEN>" \
    -H "Content-Type: application/vnd.api+json" \
    --data-binary '@request_body.json' \
    'https://api.snyk.io/rest/orgs/<ORG_ID>/sbom_tests?version=2023-08-31~beta'

request_body.json

{
    "data": {
        "type": "sbom_test",
        "attributes":{ 
            "sbom": {
            <SBOM_CONTENTS>
            }
        }
    }
}

3. 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.

JSON response body

{
    "data": {
        "id": "<JOB_ID>",
        "type": "sbom_tests"
    },
    "jsonapi": {
        "version": "1.0"
    },
    "links": {
        "self": "/rest/orgs/<ORG_ID>/sbom_tests?version=2023-08-31~beta",
        "related": "/rest/orgs/<ORG_ID>/sbom_tests/<JOB_ID>?version=2023-08-31~beta"
    }
}

Check the status of the test (optional)

You can check the status of the test at any time after the initial request.

1. Using the job_id returned from the initial request to the Create an SBOM test run endpoint, make a request to another endpoint to get the SBOM test run status.

2. A successful request to this endpoint returns the status of your test, which can either be processing or finished. If the call is not successful, an error will be returned.

  curl --get \
      -H "Authorization: token <SNYK_TOKEN>" \
      'https://api.snyk.io/rest/orgs/<ORG_ID>/sbom_tests/<TEST_ID>?version=2023-08-31~beta'

View results of the test

When the test is complete, you can view the results for the tested SBOM.

1. When the status of the test returned isfinished, make a request to get an SBOM test result.

2. View the information that the request returns: summary-level information about the SBOM that was tested, as well as the detailed results.

curl --get \
    -H "Authorization: token <SNYK_TOKEN>" \
    'https://api.snyk.io/rest/orgs/<ORG_ID>/sbom_tests/<TEST_ID>/results?version=2023-08-31~beta'

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.