osv.py - Wrappers for querying the OSV API

Purpose:

This module provides functionality for collecting vulnerability metrics from Open Source Vulnerabilities (OSV); specifically, through the OSV API.

Platform:

Linux/Windows | Python 3.8+

Developer:

J Berendt

Email:

development@s3dev.uk

References:

The following links provide the requirements (specification) on which this module’s logic and API interactions are based:

Comments:

n/a

class OSVQuery[source]

Bases: object

Class for querying the OSV API.

Examples:

Query a project’s vulnerabilities via the OSV API, for a specific version:

>>> from ppklib import OSVQuery

>>> oquery = OSVQuery.vulnerabilities(name='numpy',
                                      version='1.20.0')

>>> # Inspect the retrieved vulnerabilities.
>>> oquery.vulns
[{'id': 'GHSA-6p56-wp2h-9hxr',
  'summary': 'NumPy Buffer Overflow (Disputed)',
  'aliases': ['CVE-2021-33430', 'PYSEC-2021-854'],
  'published': '2022-01-07T00:09:39Z',
  'modified': '2024-09-26T15:01:21.525444Z',
  'severity': 'MODERATE',
  'vectors': [{'CVSS_V3': 'CVSS:3.1/AV:N/AC:H/PR:L/UI:N/S:U/C:N/I:N/A:H'},
   {'CVSS_V4': 'CVSS:4.0/AV:N/AC:H/AT:N/PR:L/UI:N/VC:N/VI:N/VA:H/SC:N/SI:N/SA:N'}]},
 {'id': 'GHSA-fpfv-jqm9-f5jm',
  'summary': 'Incorrect Comparison in NumPy',
  'aliases': ['CVE-2021-34141', 'PYSEC-2021-855'],
  'published': '2021-12-18T00:00:41Z',
  'modified': '2023-11-08T04:06:07.388275Z',
  'severity': 'MODERATE',
  'vectors': [{'CVSS_V3': 'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L'}]}]
classmethod vulnerabilities(name: str = None, *, version: str = None, wheel: str = None) OSVAPIObject | None[source]

Query a project’s vulnerabilities.

Parameters:
  • name (str, optional) – Name of the project to be queried. Defaults to None.

  • version (str, optional) – Return vulnerabilities specific to this version. Defaults to None.

  • wheel (str, optional) – Return version specific vulnerabilities. Passing only this argument performs the same query as providing both the name and version arguments. Defaults to None.

Tip

  1. If only the name argument is provided, all vulnerabilities for the project are queried. However, as pagination is not automatically implemented, the actual response may be more than what is returned on the first page.

    It is recommended to narrow the search to a specific version. Keep reading …

  2. If the name and version arguments are provided, only the vulnerabilities specific to this version are returned.

  3. If the wheel argument is used, this performs the same query as providing both the name and version arguments. (Preferred)

    This is the preferred method because if only the wheel filename is provided, the package name and version are parsed from the filename - this enables a simple function call with only a single argument (the wheel filename).

Returns:

Object containing the project vulnerability details, per OSV. On error, None is returned.

Return type:

OSVAPIObject | None