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:

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)[source]

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[source]

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()[source]

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[source]

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()[source]

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

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

_getrequest() bool[source]

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[source]

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.