OSS Index Python Library documentation

OSS Index is a free catalogue of open source components and scanning tools to help developers identify vulnerabilities, understand risk, and keep their software safe.

This library provides an interface to OSS Index in Python.

This module is not designed for standalone use (i.e. it is not executable on it’s own). If you’re looking for a tool that can sacn your Python applications and utilise OSS Index data, why not check out these tools:

Installation

Install from pypi.org as you would any other Python module using your preferred package manager:

pip install ossindex-lib

Usage

ossindex-lib is designed to be included into other Python projects, not used as a standalone application.

Library Configuration

There are two key configurations that are possible:

  1. Caching of response from OSS Index

  2. Authentication for OSS Index

Caching of OSS Index Responses

By default, caching is enabled and the cache will be stored in $HOME/.ossindex/.

You can disable caching as follows:

ossi = OssIndex(enable_cache=False)

You can control the base directory where the cache directory .ossindex is created by supplying a directory as follows:

ossi = OssIndex(cache_location='/my/other/directory')

In this last example, caching will be enabled and the cache will be stored in /my/other/directory/.ossindex.

Authenticating to OSS Index

By default, this library will attempt authenticated calls to OSS Index if authentication credentials exist in $HOME/.oss-index.config.

.oss-index.config is a YAML formatted file and the example below shows how a username and password can be added to enable authenticated calls to OSS Index:

username: my-oss-index-username
password: my-oss-index-password

Support

If you run into issues utilising this library, please raise a GitHub Issue. When raising an issue please include as much detail as possible including:

  • Version of ossindex-lib you have installed

  • Input(s)

  • Expected Output(s)

  • Actual Output(s)

Python Version Support

We endeavour to support all functionality for all current actively supported Python versions. However, some features may not be possible/present in older Python versions due to their lack of support - which are noted below.

Changelog

v1.1.1 (2022-09-12)

Fix

v1.1.0 (2022-07-12)

Feature

v1.0.0 (2022-03-10)

Feature

Fix

Breaking

v0.2.1 (2021-09-16)

Fix

v0.2.0 (2021-09-15)

Feature

Fix

v0.1.1 (2021-09-13)

Fix

API Reference

This page contains auto-generated API reference documentation 1.

ossindex

Submodules

ossindex.exception
Module Contents
exception ossindex.exception.OssIndexException[source]

Bases: Exception

Base exception which all exceptions raised by this library extend.

exception ossindex.exception.AccessDeniedException[source]

Bases: OssIndexException

Raised if supplied credentials for Oss Index are invalid.

ossindex.model
Module Contents
Classes

Vulnerability

Model class that represents a Vulnerability as received back from OSS Index.

OssIndexComponent

Model class that represents a Component Report as received back from OSS Index.
class ossindex.model.Vulnerability(*, id_: str, display_name: str, title: str, description: str, cvss_score: Optional[float] = None, cvss_vector: Optional[str] = None, cve: Optional[str] = None, cwe: Optional[str] = None, version_ranges: Optional[Iterable[str]] = None, reference: str, external_references: Optional[Iterable[str]] = None)[source]

Model class that represents a Vulnerability as received back from OSS Index.

property id → str[source]

OSS Index’s unique UUID for this Vulnerability.

Returns:

str

property display_name → str[source]

displayName returned by OSS Index

Returns:

str

property title → str[source]

title returned by OSS Index

Returns:

str

property description → str[source]

description returned by OSS Index.

Returns:

str

property cvss_score → Optional[float][source]

CVSS Score returned from OSS Index.

Returns:

float if set else None

property cvss_vector → Optional[str][source]

CVSS Vector returned from OSS Index

Returns:

str if set else None

property cwe → Optional[str][source]

CWE returned from OSS Index.

Returns:

str if set else None

property cve → Optional[str][source]

CVE returned from OSS Index.

Returns:

str if set else None

property reference → str[source]

Reference URL to OSS Index for this Vulnerability.

Returns:

str

property version_ranges → Set[str][source]

Range of versions which are impacted by this Vulnerability.

Returns:

Set of str

property external_references → Set[str][source]

List of external references that provide additional information about the vulnerability.

Returns:

Set of str

__eq__(other: object) → bool[source]

Return self==value.

__hash__() → int[source]

Return hash(self).

__repr__() → str[source]

Return repr(self).

class ossindex.model.OssIndexComponent(*, coordinates: str, description: Optional[str] = None, reference: str, vulnerabilities: Optional[Iterable[Vulnerability]] = None)[source]

Model class that represents a Component Report as received back from OSS Index.

property coordinates → str[source]

PackageURL formatted coordinates of this Component.

Returns:

str

property description → Optional[str][source]

Description of the Component from OSS Index.

Returns:

str if set else None

property reference → str[source]

URL to this Component on OSS Index.

Returns:

str

property vulnerabilities → Set[Vulnerability][source]

Known vulnerabilities that relate to this Component.

Returns:

Set of Vulnerability

__eq__(other: object) → bool[source]

Return self==value.

__hash__() → int[source]

Return hash(self).

__repr__() → str[source]

Return repr(self).

get_package_url() → packageurl.PackageURL[source]

Get a PURL representation of this components coordinates.

Returns:

PackageURL

get_max_cvss_score() → float[source]

Get the maximum CVSS Score across all Vulnerabilities known for this Component.

Returns:

float

static _reduce_on_max_cvss_score(v: Vulnerability, current_max: float) → float[source]
ossindex.ossindex
Module Contents
Classes

OssIndex

Attributes

logger

ossindex_lib_version

ossindex_lib_version

ossindex.ossindex.logger[source]
ossindex.ossindex.ossindex_lib_version :str = TBC[source]
ossindex.ossindex.ossindex_lib_version[source]
class ossindex.ossindex.OssIndex(*, enable_cache: bool = True, cache_location: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None)[source]
DEFAULT_CONFIG_FILE = .oss-index.config[source]
_caching_enabled :bool = False[source]
_cache_directory :str = .ossindex[source]
_cache_ttl_in_hours :int = 12[source]
_oss_index_api_version :str = v3[source]
_oss_index_host :str = https://ossindex.sonatype.org[source]
_oss_max_coordinates_per_request :int = 128[source]
_oss_index_authentication :Optional[requests.auth.HTTPBasicAuth][source]
has_ossindex_authentication() → bool[source]
_attempt_config_load() → None[source]
get_component_report(packages: List[packageurl.PackageURL]) → List[ossindex.model.OssIndexComponent][source]
purge_local_cache() → None[source]
_chunk_packages_for_oss_index(packages: List[packageurl.PackageURL]) → List[List[packageurl.PackageURL]][source]

Splits up the list of packages into lists that are of a size consumable by OSS Index APIs.

Parameters

packages – List[PackageURL]

Returns

List[List[PackageURL]]

_get_api_url(api_uri: str) → str[source]
_get_cached_results(packages: List[packageurl.PackageURL]) → Tuple[List[packageurl.PackageURL], List[ossindex.model.OssIndexComponent]][source]
Takes a list of packages and returns two Lists:

  1. Packages without cached results

  2. Cached results for those packages where they exist

Parameters

packages – List[PackageURL]

Returns

(List[PackageURL], List[OssIndexComponent])

static _get_headers() → Dict[str, str][source]
_get_results(packages: List[packageurl.PackageURL]) → List[ossindex.model.OssIndexComponent][source]
_make_oss_index_component_report_call(packages: List[packageurl.PackageURL]) → List[ossindex.model.OssIndexComponent][source]
_upsert_cache_with_oss_index_responses(oss_components: List[ossindex.model.OssIndexComponent]) → None[source]
_get_cache_db() → tinydb.TinyDB[source]
_setup_cache(cache_location: Optional[str] = None) → None[source]
ossindex.serializer
Module Contents
Classes

OssIndexJsonEncoder

Extensible JSON <http://json.org> encoder for Python data structures.
Functions

pythonify_key_names(→ Dict[Any, Any])

json_decoder(→ object)

Attributes

_HYPHENATED_ATTRIBUTES

_PYTHON_TO_JSON_NAME

ossindex.serializer.pythonify_key_names(d: Dict[str, Any]) → Dict[Any, Any][source]
ossindex.serializer.json_decoder(o: object) → object[source]
ossindex.serializer._HYPHENATED_ATTRIBUTES = ['bom_ref', 'mime_type', 'x_trust_boundary'][source]
ossindex.serializer._PYTHON_TO_JSON_NAME[source]
class ossindex.serializer.OssIndexJsonEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Bases: json.JSONEncoder

Extensible JSON <http://json.org> encoder for Python data structures.

Supports the following objects and types by default:

Python

JSON

dict

object

list, tuple

array

str

string

int, float

number

True

true

False

false

None

null

To extend this to recognize other objects, subclass and implement a .default() method with another method that returns a serializable object for o if possible, otherwise it should call the superclass implementation (to raise TypeError).

default(o: Any) → Any[source]

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

Package Contents

ossindex.logger[source]
ossindex.formatter[source]
1

Created with sphinx-autoapi