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:
- 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/orwheel
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
orpandas.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 therawjson
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
orpandas.DataFrame
, as these can be created from a simpledict
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.