Get a vulnerability report

You’ve got software in your organization. That software is built on open source. You want to know what vulnerability risks are in the open source you have, and you want to prioritize that risk so you can fix it.

Using Tidelift makes it easy; all it takes is an API key . With Tidelift, you can examine your dependencies and discover:

• All vulnerabilities present in the software release (or SBOM - software bill of materials)
• Detailed recommendations from the software’s maintainers where available, including:
  • Whether it’s a false positive
  • How likely a user is to be affected, so you can prioritize
  • Any workaround that is available for your developers

You can then take this information, import it into your own tooling, and use it to:

• Prioritize risk
• Give recommended actions to developers
• Burn down risk in your organization

For this example, we’re going to focus on risk from vulnerabilities. But these same APIs will pull out other forms of risk.

Checking vulnerabilities in a single dependency

To check vulnerabilities in a single software dependency, use Tidelift’s release API.

For example, to determine risk in the use of version 1.26.12 of the python package urllib3, access the Tidelift releases API via a GET request at:

https://api.tidelift.com/external-api/packages/pypi/urllib3/releases/1.26.12

This returns JSON information on the release. To see vulnerabilities, you would look for entries in the “violations” array that have a ‘vulnerability’ field.

For example, to access the data with curl and to filter vulnerabilities with jq, you would do:

curl https://api.tidelift.com/external-api/packages/pypi/urllib3/releases/1.26.12 | jq '.violations[].vulnerability'

This would give this vulnerability information:

Checking vulnerabilities in multiple dependencies

To check risk in multiple software dependencies, use Tidelift’s bulk release API

For example, to determine vulnerabilities in the use of version 1.26.12 of the python package urllib3 and 2.28.1 of the python package requests, access the Tidelift bulk releases API via a POST request at:

https://api.tidelift.com/external-api/releases/lookup

using the following JSON payload:

{
  "releases": [
    { "platform": "pypi", "name": "urllib3", "version": "1.26.12" },
    { "platform": "pypi", "name": "requests", "version": "2.28.1" }
  ]
}

For example, to access the data with curl and to filter vulnerabilities with jq, you would put that JSON payload in a file named `query.json`, and call the API this way, and process the results:

curl https://api.tidelift.com/external-api/releases/lookup -X POST --json @query.json | jq 'releases[].violations[].vulnerability'

This would give this vulnerability information:

This returns a JSON result that includes information on each passed release, including the same vulnerability information as the original release.

Checking vulnerabilities on all your dependencies at once

You may want to find vulnerabilities on all your software dependencies at once. 

This can easily be done by:

• Getting a Software Bill of Materials (SBOM) that enumerates your dependencies. An example tool that can create a SBOM is Syft
• Getting a list of dependencies from that SBOM
• Using Tidelift’s API to assess them

An example of doing so is available in the https://github.com/tidelift/sbom-to-api-tools. This repository includes Go code that takes a CycloneDX SBOM, and returns JSON on vulnerabilities that are present.

Given a “foo.sbom” file, what you would do is run:

tidelift-sbom-vulnerability-reporter foo.sbom

This yields output such as the following vulnerability info:

Next steps

Use this information to prioritize work for your development team.

You can:

• Import this data into BI, to drive your prioritization
• Import this data into a ticketing system such as JIRA, to distribute work to your developers