Vexy Documentation

Software Bill of Materials (SBOMs) are gaining traction and are a great way to codify what dependencies your software relies on from the Open Source ecosystems (and internal libraries too!).

The SBOM for a given release of a given piece of software should be static in terms of the components that comprise that release.

CycloneDX, in this authors view - the best Bill of Materials format, also allows for Vulnerability Exploitability Exchange (or VEX) information to be included in your BOM.

Known vulnerabilities change over time - we always know more about the security posture of Open Source components tomorrow than we did today. So how do we keep our BOMs updated with this information?

CycloneDX also allows for BOMs to interlink for the above reason. The best way to manage this scenario is to generate a BOM that describes your software release, excluding VEX data, and then have a tool (perhaps vexy?) produce you a VEX document (in CycloneDX format) that links back to your SBOM.

Did I confuse you? If so - read more about Independent BOM and VEX here.

Installation

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

pip install vexy

Usage

vexy is designed to be run as a standalone application.

Once installed, you can call the tool via the following methods:

$ python3 -m vexy
$ vexy

The full documentation can be issued by running with --help:

$ vexy --help
usage: vexy [-h] -c VEXY_CONFIG [-q] [-X] -i FILE_PATH [--format {xml,json}] [--schema-version {1.4}] [-o FILE_PATH] [--force]

Vexy VEX Generator

options:
  -h, --help            show this help message and exit
  -c VEXY_CONFIG, --config VEXY_CONFIG
                        Configuration file for Vexy defining data sources to use and their configuration.
  -q                    Quiet - no console output
  -X                    Enable debug output

Input CycloneDX BOM:
  Where Vexy shall obtain its input

  -i FILE_PATH, --in-file FILE_PATH
                        CycloneDX BOM to read input from. Use "-" to read from STDIN.

VEX Output Configuration:
  Choose the output format and schema version

  --format {xml,json}   The output format for your SBOM (default: xml)
  --schema-version {1.4}
                        The CycloneDX schema version for your VEX (default: 1.4)
  -o FILE_PATH, --o FILE_PATH, --output FILE_PATH
                        Output file path for your SBOM (set to '-' to output to STDOUT)
  --force               If outputting to a file and the stated file already exists, it will be overwritten.

Configuration

Vexy will query the data sources you configured to obtain current known vulnerability information that relates to the Open Source components included in your input SBOM.

Data Sources are configured in a YAML formatted file which is supplied to vexy using the -c or --config flag at the command line. A configuration file MUST be supplied to run vexy.

Configuration File Format

Currently, the configuration file is used only to describe which data sources you would like vexy to utilise and any configuration that datasource requires - e.g. authentication details.

An example configuration file might look as follows:

sources:
    ossindex:
        username: <your-username>
        password: <your-password>
    osv:

For details of what data sources are available and their specific configuration - see Data Sources.

Data Sources

OSS Index

• See https://ossindex.sonatype.org

• Supports authentication: ✓

• Requires authentication: ✗

Configuration

sources:
    ossindex:
        username: <your-username>
        password: <your-password>

OSV.dev

• See https://osv.dev/

• Supports authentication: ✗

• Requires authentication: ✗

Configuration

sources:
    osv:

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 vexy 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

v0.3.1 (2023-03-03)

Fix

• Handle parsing of BOM more safely (``39d6f78` <https://github.com/madpah/vexy/commit/39d6f78fd517d4cfe53fa07214f69947762d71a0>`_)

• Update to latest contracts with cyclonedx-python-lib (``fda01e0` <https://github.com/madpah/vexy/commit/fda01e047717dc1bf952f07cddd5ad2d551e9e35>`_)

• Bump to latest rc of cyclonedx-python-lib (``8e3d05a` <https://github.com/madpah/vexy/commit/8e3d05a8cc0d1d50d317f7f1eb5dbceb6fe093f1>`_)

• Handle parsing of BOM more safely (``a89862a` <https://github.com/madpah/vexy/commit/a89862a039ad918f278a57b64197fa9009fa28e0>`_)

v0.3.0 (2022-08-02)

Feature

• Added OSV.dev as data source (``402c669` <https://github.com/madpah/vexy/commit/402c669ab3a07a7ca485e860635504789107a0f5>`_)

v0.2.0 (2022-07-14)

Feature

• Add vexy as a Tool to generated VEX documents (``f2378a8` <https://github.com/madpah/vexy/commit/f2378a820b88a6ee10036d4f771b5dd0e11925cb>`_)

• Add vexy as a Tool to generated VEX documents (``70ea250` <https://github.com/madpah/vexy/commit/70ea250609ed8bf673637483691406d6b56f9dd8>`_)

Fix

• Disable mypy warn_unused_ignores to get mypy passing on all variants (``e331e72` <https://github.com/madpah/vexy/commit/e331e72aac0002543066151841bbbeb661d5be97>`_)

v0.1.7 (2022-07-13)

Fix

• Use a known working release pipeline (``c51e613` <https://github.com/madpah/vexy/commit/c51e6132f5a653385486eda5efa54faece7719e7>`_)

v0.1.6 (2022-07-13)

Fix

• Release CI pipeline syntax error (``b5b8529` <https://github.com/madpah/vexy/commit/b5b852955810082009a7c308f91d4a1284aa6368>`_)

v0.1.5 (2022-07-13)

Fix

• Release CI pipeline syntax error (``c0c7846` <https://github.com/madpah/vexy/commit/c0c78461c2e288825214640300917edfe24cb04f>`_)

v0.1.4 (2022-07-13)

Fix

• Remove date parsing from source BOM (``3d1e0d9` <https://github.com/madpah/vexy/commit/3d1e0d94917df6b4b32da06900c846e771720689>`_)

v0.1.3 (2022-07-13)

Fix

• Remove parsing of input BOM timestamp - we do not use it (``8b40f70` <https://github.com/madpah/vexy/commit/8b40f70487f20c4e21f72ed329330226082a31f3>`_)

v0.1.2 (2022-07-13)

Fix

• Pin ci to use python-semantic-release@v7.28.1 as newer breaks CI (``d1a1fe6` <https://github.com/madpah/vexy/commit/d1a1fe6f221fc9f557828188613c0e329a19a881>`_)

v0.1.1 (2022-07-13)

Fix

• Typing broke some use cases (``5965816` <https://github.com/madpah/vexy/commit/59658165a2789b59d93a0e3844b35b5c5fe303dd>`_)

• Typing broke some use cases (``c766507` <https://github.com/madpah/vexy/commit/c766507bcc5a84f61b7371ba8dd1bc51526a0a77>`_)

v0.1.0 (2022-07-13)

Feature

• First alpha release supporting OSS Index as the sole data source (``650bf52` <https://github.com/madpah/vexy/commit/650bf521675524d7869ebc1b8d0ccc0d2175aab7>`_)

API Reference

This page contains auto-generated API reference documentation [1].

vexy

Subpackages

vexy.sources

Submodules

vexy.sources.base

Module Contents

Classes

BaseSource

Helper class that provides a standard way to create an ABC using

class vexy.sources.base.BaseSource(*, config: Dict[str, Any] | None = None)

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

property all_components: Set[cyclonedx.model.component.Component]

property valid_components: Set[cyclonedx.model.component.Component]

process_components(*, components: Iterable[cyclonedx.model.component.Component]) → None

abstract get_vulnerabilities() → Set[cyclonedx.model.vulnerability.Vulnerability]

abstract _component_complete_for_source(*, component: cyclonedx.model.component.Component) → bool

Whether the given Component has enough data (the right fields) for us to query this data source for known vulnerabilities.

Parameters:

component – Component

Returns:

bool

abstract _configure_source(*, config: Dict[str, Any]) → None

Perform any source specific configuration such as authentication.

Parameters:

config – Dict[str, Any]

Returns:

None

abstract static source() → cyclonedx.model.vulnerability.VulnerabilitySource

Instance that represents this data source.

Returns:

VulnerabilitySource

abstract static source_name() → str

Human-friendly name for this data source.

Returns:

str

abstract static source_description() → str

Human-friendly description of this data source.

Returns:

str

abstract static source_ecosystems() → Set[vexy.EcoSystem]

Which ecosystems this source has vulnerability data for.

Returns:

Set[str]

abstract static source_url() → str

Public URL for this data source

Returns:

str

vexy.sources.ossindex

Module Contents

Classes

OssIndexSource

Helper class that provides a standard way to create an ABC using

class vexy.sources.ossindex.OssIndexSource(*, config: Dict[str, Any] | None = None)

Bases: vexy.sources.base.BaseSource

Helper class that provides a standard way to create an ABC using inheritance.

_component_complete_for_source(component: cyclonedx.model.component.Component) → bool

Whether the given Component has enough data (the right fields) for us to query this data source for known vulnerabilities.

Parameters:

component – Component

Returns:

bool

_configure_source(config: Dict[str, Any]) → None

Perform any source specific configuration such as authentication.

Parameters:

config – Dict[str, Any]

Returns:

None

get_vulnerabilities() → Set[cyclonedx.model.vulnerability.Vulnerability]

static source() → cyclonedx.model.vulnerability.VulnerabilitySource

Instance that represents this data source.

Returns:

VulnerabilitySource

static source_name() → str

Human-friendly name for this data source.

Returns:

str

static source_description() → str

Human-friendly description of this data source.

Returns:

str

static source_ecosystems() → Set[vexy.EcoSystem]

Which ecosystems this source has vulnerability data for.

Returns:

Set[str]

static source_url() → str

Public URL for this data source

Returns:

str

vexy.sources.osv

Module Contents

Classes

OsvSource

Helper class that provides a standard way to create an ABC using

class vexy.sources.osv.OsvSource(*, config: Dict[str, Any] | None = None)

Bases: vexy.sources.base.BaseSource

Helper class that provides a standard way to create an ABC using inheritance.

get_vulnerabilities() → Set[cyclonedx.model.vulnerability.Vulnerability]

_component_complete_for_source(*, component: cyclonedx.model.component.Component) → bool

Whether the given Component has enough data (the right fields) for us to query this data source for known vulnerabilities.

Parameters:

component – Component

Returns:

bool

_configure_source(*, config: Dict[str, Any]) → None

Perform any source specific configuration such as authentication.

Parameters:

config – Dict[str, Any]

Returns:

None

static source() → cyclonedx.model.vulnerability.VulnerabilitySource

Instance that represents this data source.

Returns:

VulnerabilitySource

static source_name() → str

Human-friendly name for this data source.

Returns:

str

static source_description() → str

Human-friendly description of this data source.

Returns:

str

static source_ecosystems() → Set[vexy.EcoSystem]

Which ecosystems this source has vulnerability data for.

Returns:

Set[str]

static source_url() → str

Public URL for this data source

Returns:

str

vexy.sources.osvdb

Module Contents

Classes

OsvDbSource

Helper class that provides a standard way to create an ABC using

class vexy.sources.osvdb.OsvDbSource(*, config: Dict[str, Any] | None = None)

Bases: vexy.sources.base.BaseSource

Helper class that provides a standard way to create an ABC using inheritance.

get_vulnerabilities() → Set[cyclonedx.model.vulnerability.Vulnerability]

_component_complete_for_source(*, component: cyclonedx.model.component.Component) → bool

Whether the given Component has enough data (the right fields) for us to query this data source for known vulnerabilities.

Parameters:

component – Component

Returns:

bool

_configure_source(*, config: Dict[str, Any]) → None

Perform any source specific configuration such as authentication.

Parameters:

config – Dict[str, Any]

Returns:

None

static source() → cyclonedx.model.vulnerability.VulnerabilitySource

Instance that represents this data source.

Returns:

VulnerabilitySource

static source_name() → str

Human-friendly name for this data source.

Returns:

str

static source_description() → str

Human-friendly description of this data source.

Returns:

str

static source_ecosystems() → Set[vexy.EcoSystem]

Which ecosystems this source has vulnerability data for.

Returns:

Set[str]

static source_url() → str

Public URL for this data source

Returns:

str

Package Contents

Classes

BaseSource	Helper class that provides a standard way to create an ABC using
OssIndexSource	Helper class that provides a standard way to create an ABC using
OsvSource	Helper class that provides a standard way to create an ABC using

Attributes

ALL_SOURCES

class vexy.sources.BaseSource(*, config: Dict[str, Any] | None = None)

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

property all_components: Set[cyclonedx.model.component.Component]

property valid_components: Set[cyclonedx.model.component.Component]

process_components(*, components: Iterable[cyclonedx.model.component.Component]) → None

abstract get_vulnerabilities() → Set[cyclonedx.model.vulnerability.Vulnerability]

abstract _component_complete_for_source(*, component: cyclonedx.model.component.Component) → bool

Whether the given Component has enough data (the right fields) for us to query this data source for known vulnerabilities.

Parameters:

component – Component

Returns:

bool

abstract _configure_source(*, config: Dict[str, Any]) → None

Perform any source specific configuration such as authentication.

Parameters:

config – Dict[str, Any]

Returns:

None

abstract static source() → cyclonedx.model.vulnerability.VulnerabilitySource

Instance that represents this data source.

Returns:

VulnerabilitySource

abstract static source_name() → str

Human-friendly name for this data source.

Returns:

str

abstract static source_description() → str

Human-friendly description of this data source.

Returns:

str

abstract static source_ecosystems() → Set[vexy.EcoSystem]

Which ecosystems this source has vulnerability data for.

Returns:

Set[str]

abstract static source_url() → str

Public URL for this data source

Returns:

str

class vexy.sources.OssIndexSource(*, config: Dict[str, Any] | None = None)

Bases: vexy.sources.base.BaseSource

Helper class that provides a standard way to create an ABC using inheritance.

_component_complete_for_source(component: cyclonedx.model.component.Component) → bool

Whether the given Component has enough data (the right fields) for us to query this data source for known vulnerabilities.

Parameters:

component – Component

Returns:

bool

_configure_source(config: Dict[str, Any]) → None

Perform any source specific configuration such as authentication.

Parameters:

config – Dict[str, Any]

Returns:

None

get_vulnerabilities() → Set[cyclonedx.model.vulnerability.Vulnerability]

static source() → cyclonedx.model.vulnerability.VulnerabilitySource

Instance that represents this data source.

Returns:

VulnerabilitySource

static source_name() → str

Human-friendly name for this data source.

Returns:

str

static source_description() → str

Human-friendly description of this data source.

Returns:

str

static source_ecosystems() → Set[vexy.EcoSystem]

Which ecosystems this source has vulnerability data for.

Returns:

Set[str]

static source_url() → str

Public URL for this data source

Returns:

str

class vexy.sources.OsvSource(*, config: Dict[str, Any] | None = None)

Bases: vexy.sources.base.BaseSource

Helper class that provides a standard way to create an ABC using inheritance.

get_vulnerabilities() → Set[cyclonedx.model.vulnerability.Vulnerability]

_component_complete_for_source(*, component: cyclonedx.model.component.Component) → bool

Whether the given Component has enough data (the right fields) for us to query this data source for known vulnerabilities.

Parameters:

component – Component

Returns:

bool

_configure_source(*, config: Dict[str, Any]) → None

Perform any source specific configuration such as authentication.

Parameters:

config – Dict[str, Any]

Returns:

None

static source() → cyclonedx.model.vulnerability.VulnerabilitySource

Instance that represents this data source.

Returns:

VulnerabilitySource

static source_name() → str

Human-friendly name for this data source.

Returns:

str

static source_description() → str

Human-friendly description of this data source.

Returns:

str

static source_ecosystems() → Set[vexy.EcoSystem]

Which ecosystems this source has vulnerability data for.

Returns:

Set[str]

static source_url() → str

Public URL for this data source

Returns:

str

vexy.sources.ALL_SOURCES: Dict[str, Type[base.BaseSource]]

Submodules

vexy.__main__

vexy.client

Module Contents

Classes

_CLI_OUTPUT_FORMAT	Generic enumeration.
VexyCmd

Functions

main(→ None)

Attributes

_output_formats
_output_default_filenames
__ThisToolVersion
ThisTool

class vexy.client._CLI_OUTPUT_FORMAT

Bases: enum.Enum

Generic enumeration.

Derive from this class to define new enumerations.

XML = 'xml'

JSON = 'json'

vexy.client._output_formats: Dict[_CLI_OUTPUT_FORMAT, cyclonedx.schema.OutputFormat]

vexy.client._output_default_filenames

vexy.client.__ThisToolVersion: str | None

vexy.client.ThisTool

class vexy.client.VexyCmd(args: argparse.Namespace)

DEFAULT_CONFIG_FILE: str = '.vexy.config'

_DEBUG_ENABLED: bool = False

_arguments: argparse.Namespace

_attempt_source_config_load(config: io.TextIOWrapper) → None

get_cli_output_format() → _CLI_OUTPUT_FORMAT

_get_output_format() → cyclonedx.schema.OutputFormat

_is_quiet() → bool

execute() → None

_get_outputter(output_format: cyclonedx.schema.OutputFormat, bom: cyclonedx.model.bom.Bom) → cyclonedx.output.BaseOutput

static get_arg_parser(*, prog: str | None = None) → argparse.ArgumentParser

_debug_message(message: str) → None

static _error_and_exit(message: str, exit_code: int = 1) → None

vexy.client.main(*, prog_name: str | None = None) → None

Package Contents

Classes

EcoSystemType
EcoSystem	Languages/ecosystems to the PURL type

Attributes

_ALL_ECOSYSTEMS

class vexy.EcoSystemType(*, name: str, purl_type: str, description: str)

property name: str

property purl_type: str

property description: str

vexy._ALL_ECOSYSTEMS

class vexy.EcoSystem

Bases: enum.Enum

Languages/ecosystems to the PURL type

Starting list taken from https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst

BITBUCKET = 'BITBUCKET'

CARGO = 'CARGO'

COCOAPODS = 'COCOAPODS'

COMPOSER = 'COMPOSER'

CONAN = 'CONAN'

CONDA = 'CONDA'

CRAN = 'CRAN'

DART = 'PUB'

DEBIAN = 'DEB'

DOCKER = 'DOCKER'

FLUTTER = 'PUB'

GENERIC = 'GENERIC'

GITHUB = 'GITHUB'

GO = 'GOLANG'

HASKELL = 'HACKAGE'

HEX = 'HEX'

MAVEN = 'MAVEN'

NPM = 'NPM'

NUGET = 'NUGET'

OCI = 'OCI'

PYPI = 'PYPI'

RPM = 'RPM'

RUBY_GEM = 'GEM'

SWIFT = 'SWIFT'

get_info() → EcoSystemType

[1]

Created with sphinx-autoapi