osv.py - Wrappers for querying the OSV API — ppklib - v0.2.0rc3 Documentation

# 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:

  > - OSV API

Comments:

  n/a

class OSVQuery

  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

    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