Object: osvapiobject.py - Object for querying the OSV API — ppklib - v0.2.0rc3 Documentation

# Object: osvapiobject.py - Object for querying the OSV API

Purpose:

  This module provides the object implementation for interacting with the Open Source Vulnerabilities (OSV) API.

Platform:

  Linux/Windows | Python 3.8+

Developer:

  J Berendt

Email:

  development@s3dev.uk

Comments:

  n/a

References:

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

  > - OSV API

Example:

  Create an instance of the object and query the API to obtain version-specific vulnerabilities:

      >>> from ppklib.objects.osvapiobject import OSVAPIObject

      >>> oapi = OSVAPIObject(name='numpy', version='1.20.0')
      >>> oapi.get()

      >>> # Inspect the raw JSON data.
      >>> oapi.rawjson
      {'not_shown': 'too_big'}

  Create an instance of the object and query the API to obtain version-specific vulnerabilities, and subset the raw API response to frequently used keys:

      >>> from ppklib.objects.osvapiobject import OSVAPIObject

      >>> oapi = OSVAPIObject(name='numpy', version='1.20.0')
      >>> oapi.get_and_filter()

      >>> # View the reported vulnerabilities.
      >>> oapi.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'}]}]

      >>> # View the count of each severity class.
      >>> oapi.counts
      <SeverityCountsObject> C: 0, H: 0, M: 2, L: 0

class OSVAPIObject(name: str = None, version: str = None, wheel: str = None)

  Bases: `object`

  Object designed for interacting with OSV’s API.

  Parameters:

    - name (str, optional) – Name of the package to query. Providing only the name will return the all project-related vulnerabilities. For wheel-specific (release-specific) vulnerabilities, provide the `version` and/or `wheel` arguments too. Defaults to None.

    - version (str, optional) – Query the vulnerabilities specific to this version; otherwise the vulnerabilities for all versions will be returned. Defaults to None.

    - wheel (str, optional) – Wheel filename. Providing only this argument will return version-specific vulnerability information. The project name and version will be parsed from the wheel filename. Defaults to None.

  property counts: SeverityCountsObject

    Accessor to the severity class counts.

  property name: str

    Accessor to the name of the target package.

  property rawjson: dict

    Accessor to the raw JSON data returned by the API.

    This property returns the complete JSON response from the API.

  property status_code: int

    Accessor to the response’s status code.

  property version: str

    Accessor to the version number of the target package.

  property vulns: list

    Accessor to the filtered vulnerabilities as a list of dicts.

    This property returns the filtered response from the API as a list of relatively flat dictionaries. This is to enable easy conversion to a `pandas.Series` or `pandas.DataFrame`.

    If the full response is required, please use the `rawjson` property.

  property wheel: str

    Accessor to the wheel’s filename for the target package.

  get() → bool

    Query the PyPI database using the JSON API.

    Use this method to populate the `_rawjson` attribute, which is accessed through the `rawjson` property.

    Returns:

      True if the request succeeds, otherwise False.

    Return type:

      bool

  get_and_filter()

    Query the OSV database using the API and filter the results.

    This method filters the full JSON response to create a list of (relatively) flattened dictionaries with the ‘frequently used’/’most descriptive’ key/value pairs for the reported vulnerabilities. These are stored into the `vulns` property for access.

    The primary purpose for creating a flattened subset is to facilitate easy conversion to a `pandas.Series` or `pandas.DataFrame`, as these can be created from a simple `dict` object.

    If the full response is required, please use the `rawjson` property.

  _build_request() → dict

    Build the GET request using the available arguments.

    Returns:

      A dictionary containing the parameters required for a `requests.get()` request. Simply pass this dict into the function with double asterisks for unpacking.

    Return type:

      dict

  _flatten_vulnerability_data()

    Filter the ‘frequently used’ vulnerability items into a dict.

    The result of the filter can be accessed via the `vulns` property.

  _getrequest() → bool

    Send the GET request to the API and store the response.

    If successful, the raw JSON response is stored into the `_rawjson` attribute of this class.

    Returns:

      True if the response to the GET request is 200, otherwise False.

    Return type:

      bool

  _test_args() → None

    Verify the appropriate arguments are provided.

    Tasks:

      - Normalise the `name` attribute value.

      - If either the name or version are not provided, and the wheel filename is provided, the name and version are derived from the wheel filename.