Answering common questions with Tidelift's data APIs

Whether you want to see whether a package is a good long-term candidate to build on, find a safer alternative to build on, or inform your developers about vulnerability details so they can describe whether they're affected, you can answer many common questions about the software you use with Tidelift's data APIs.

You do not need a software bill of materials (SBOM), or to upload anything to Tidelift; all you need is an API key.

Here are a number of questions you can use Tidelift’s data APIs to answer.

What is the supplier risk of a package I use?

You’ve likely already figured out how to check your software for vulnerabilities. (If you haven’t, Tidelift can do that too!) What you are looking for now is deeper, supplier-based risk, asking yourself:

• What things that I use are deprecated, end-of-life, or don’t have maintenance activity?
• What things that I use aren’t maintained to secure standards, or only have a single maintainer?
• What items have funding sources and therefore are a better long-term bet?

How to: use the Tidelift package API, and look at the “tidelift_recommendation” and “quality_checks” fields.

Example using curl and jq:

curl -H "Accept: application/json" -H "Authorization: bearer <your Tidelift API key>" https://api.tidelift.com/external-api/v1/packages/pypi/urllib3 | jq '.tidelift_recommendation, .quality_checks'

"recommended"
{
  "discoverable_security_policy": {
    "status": "passed",
    "recommendation_status": "success",
    "additional_data": null
  },
  "no_known_issues_in_dependencies_for_latest_release": {
    "status": "passed",
    "recommendation_status": "success",
    "additional_data": null
  },
  "no_known_vulnerabilities_on_latest_release": {
    "status": "passed",
    "recommendation_status": "success",
    "additional_data": null
  },
  "package_appears_maintained": {
    "status": "passed",
    "recommendation_status": "success",
    "additional_data": {
      "reason": "package_is_lifted"
    }
  },
  "package_has_a_stable_release_greater_than_two_years_old": {
    "status": "passed",
    "recommendation_status": "success",
    "additional_data": null
  },
  "package_has_multiple_active_maintainers": {
    "status": "passed",
    "recommendation_status": "success",
    "additional_data": null
  },
  "package_is_not_deprecated": {
    "status": "passed",
    "recommendation_status": "success",
    "additional_data": null
  },
  "package_is_not_eol": {
    "status": "passed",
    "recommendation_status": "success",
    "additional_data": {
      "eol_reference_found": false,
      "effective_on": null,
      "reference_url": null,
      "package_renamed_to": [],
      "no_planned_maintenance": false,
      "reason": "package_has_no_known_end_of_life"
    }
  },
  "release_managers_are_reviewed": {
    "status": "passed",
    "recommendation_status": "success",
    "additional_data": null
  },
  "releases_are_discoverable_upstream": {
    "status": "passed",
    "recommendation_status": "success",
    "additional_data": null
  },
  "two_factor_authentication_at_source_repository": {
    "status": "passed",
    "recommendation_status": "success",
    "additional_data": null
  },
  "two_factor_authentication_for_package_manager": {
    "status": "passed",
    "recommendation_status": "success",
    "additional_data": null
  }
}
  

Here you can see that urllib3 is "recommended", and that it passes all available checks. It's a good bet to use for long-term development.

For more information, see Evaluating package risk and Quality assurance report.

The package API is also available as a bulk API that can be used to query information for multiple packages at once.

What are options for this deprecated/end-of-life/unmaintained package that I am currently using?

Knowing you’re using something that you need to replace is the first step. But without a recommendation for your developers, it can be hard for them to start the process of addressing their technical debt.

How to: use the Tidelift package API, and look at the “alternative_packages” field.

alternative_packages is an array of alternative packages. Each alternative has one of the following types:

• rename: a “rename” was when a package was renamed. A “rename” alternative likely is an easier migration
• alternative: an “alternative” is a different package that supplies similar functionality. An “alternative” may be either a simple or complex migration.

Example using curl and jq:

curl -H "Accept: application/json" -H "Authorization: bearer <your Tidelift API key>" https://api.tidelift.com/external-api/v1/packages/maven/log4j:log4j | jq '.alternative_packages'

[
  {
    "name": "org.apache.logging.log4j:log4j-api",
    "type": "alternative"
  },
  {
    "name": "org.apache.logging.log4j:log4j-core",
    "type": "alternative"
  }
]
  

In this case, the end-of-life package "log4j:log4j" has two recommended alternatives, which are newer projects maintained by Apache Logging.

The package API is also available as a bulk API that can be used to query information for multiple packages at once.

What is the nearest “clean” version of a package compared to what I am using?

You may have scanners that tell you that version 1.2.3 of a package has a vulnerability. And you know the vulnerability is fixed in the latest release. But you want to give your developers information on what the smallest, most risk-free, upgrade is available that does not have any issues or vulnerabilities, not just the immediate issue you’re trying to fix.

How to: use the Tidelift release API, and look at the “nearest_recommended_release” field. The nearest_recommended_release field is a dictionary with two fields:

• version: the version of the closest release with no detected issues
• published_at: when the version was published

If there is no release without issues, nearest_recommended_release will be null.

Example using curl and jq:

curl -H "Accept: application/json" -H "Authorization: bearer <your Tidelift API key>" https://api.tidelift.com/external-api/v1/packages/maven/org.springframework.boot:spring-boot/releases/3.0.4 | jq .nearest_recommended_releasedation, .quality_checks'

{
  "version": "3.0.13",
  "published_at": "2023-11-23T09:49:20.000Z"
}
  

Here, we are on version 3.0.4 of spring-boot, a popular Java framework library. This release has multiple vulnerabilities, so we want to find the easiest upgrade that does not have issues, and will provide the simplest migration path. Tidelift recommends version 3.0.13, which was released in November 2023.

The release API is also available as a bulk API that can be used to query information for multiple packages at once.

How can I tell whether I am using a package in a vulnerable way?

There are too many vulnerabilities to just say “patch everything until there are zero scanner results”. Depending on whether your software is using a dependency as a build or test dependency, or only using certain functionality or methods, may mean you are not vulnerable and don’t need to patch. But figuring out this information is time-consuming work. Having insights directly from the maintainer will help you do this analysis faster, and help you document your exposure in formats like VEX.

How to: use the Tidelift vulnerability API, and look at the “recommendation” and “recommendation_details” fields under "affected_packages"

“recommendation” has one of the following values:

• upgrade: upgrade to a fixed release
• upgrade_or_workaround: upgrade to a fixed release, or use the documented workaround
• ignore: ignore the issue, as it is a false positive

The “recommendation_details” data structure has the following relevant fields to making a decision:

• real_issue: whether this is a real issue, or a false positive
• impact_score: A score from 0-10 on how likely a typical user is to be affected
• impact_description: A reason for that score
• includes_dev: whether the vulnerability applies if this is only used a dev or test dependency
• specific_methods_description: any specific methods that are affected by the vulnerability
• other_conditions_description: any other conditions necessary for the vulnerability
• workaround_description: details of any available workaround

Example using curl and jq:

curl -H "Accept: application/json" -H "Authorization: bearer <your Tidelift API key>" https://api.tidelift.com/external-api/v1/vulnerabilities/CVE-2024-27306 | jq '.affected_packages[].recommendation, .affected_packages[].recommendation_details'

"upgrade_or_workaround"
{
  "id": "6c67b7a0-d0ef-4e39-b121-1edab5a7d3af",
  "impact_score": 1,
  "impact_description": "Most users will not use aiohttp for static assets or allow custom filename uploads to the static directory.",
  "real_issue": true,
  "false_positive_reason": null,
  "includes_dev": false,
  "specific_methods_affected": true,
  "specific_methods_description": "web.static(..., show_index=True)",
  "other_conditions": true,
  "other_conditions_description": "Only relevant if not using a reverse proxy etc. for static assets and allowing users to upload files with arbitrary filenames.",
  "workaround_available": true,
  "workaround_description": "Don't enable show_index.",
  "visibility": "external",
  "created_at": "2024-04-18T20:13:48.653Z",
  "updated_at": "2024-04-18T20:46:39.599Z"
}
  

In this example, we were told of a vulnerability in the python library "aiohttp". However, we see from the maintainer:

• that this won't affect most people in practice
• that you specifically need to have certain behaior enabled around static assets to be vulnerable
• that there is a workaround that can be applied

Our development teams can then apply the workaround, or document how they are not using the library in a vulnerable manner.

Go deeper with Tidelift

If you're interested in more example on how to use Tidelift's data APIs, or you've got a specific question you'd like to know how to answer with our APIs, contact us. We're happy to walk Tidelift customers through our data, and help with sample code.