User Guide

Dependencies & installation

This project depends on:

• Python 3.10 or later.

• spdx_python_model for reading and writing SPDX v3.0 file.

It has the following optional dependencies:

• tomli_w for generating TOML configuration file.

• PyYAML for simple CVE annotations stored in YAML files.

• argcomplete for autocompletion support.

It has the following additional dependencies for Python 3.10 (< 3.11):

• python-dateutil

• tomli

This tool is designed for Linux. While Windows support is “available”, it is still experimental and may result in bugs or poor performance.

To avoid polluting your global python namespace, we suggest creating a Python virtual environment and installing the tool inside this environment:

• Create the environment:

$ python3 -m venv .venv

• Once it is created, you can now activate it.

$ source .venv/bin/activate

• Now install sbom-cve-check inside this virtual environment using pip.

To install sbom-cve-check, with only the required dependencies, either:

• From the git sources, run from the root of sbom-cve-check git repository:

(.venv) $ pip install .

• From the Python Package Index (PyPI) repository, run:

(.venv) $ pip install sbom-cve-check

And to install it, with all optional dependencies, execute either:

• From the git sources:

(.venv) $ pip install .[extra]

• From the PyPI repository:

(.venv) $ pip install sbom-cve-check[extra]

After installation, the sbom-cve-check CLI executable will be available in the PATH configured by the virtual environment.

For others ways to install the tool, mainly for development purposes, see the developer guide.

Usage

The sbom-cve-check CLI tool takes as input an SBOM, for example, an SPDX v3.0 JSON-LD file, which may contain CVE annotations, and generate as output one or multiple export files.

The tool can be configured to take various kinds of CVE and annotation databases.

        flowchart TD
    subgraph "SPDX v3.0 JSON-LD"
        SBOM_COMP@{ shape: in-out, label: "SBOM\ncomponents" }
        SBOM_ANNOT@{ shape: db, label: "CVE\nannotations" }
    end

    DB_ANNOT@{ shape: db, label: "OpenVex\nannotations" }
    DB_OTHER@{ shape: db, label: "Other\ndatabase" }
    DB_CVE_LST@{ shape: db, label: "CVE List V5" }
    DB_CVE_NVD@{ shape: db, label: "NVD FKIE" }

    INDEX@{ shape: lin-cyl, label: "Product name -> CVE\nIndex" }

    SBOM_ANNOT -.-> INDEX
    DB_OTHER -.-> INDEX
    DB_ANNOT -.-> INDEX
    DB_CVE_LST -.-> INDEX
    DB_CVE_NVD -.-> INDEX

    PROC@{ shape: procs, label: "Compute\nCVE assessment" }

    CVE_DB@{ shape: docs, label: "Merged CVE databases" }

    DB_CVE_LST --> CVE_DB
    DB_CVE_NVD --> CVE_DB

    SBOM_ANNOT --> PROC
    DB_OTHER --> PROC
    DB_ANNOT --> PROC
    CVE_DB --> PROC
    INDEX --> PROC
    SBOM_COMP --> PROC

    EXPORT1@{ shape: out-in, label: "Export file 1\n(CSV, SPDX, ...)" }
    EXPORT2@{ shape: out-in, label: "Export file 2\n(CSV, SPDX, ...)" }

    PROC --> EXPORT1
    PROC --> EXPORT2

    style SBOM_ANNOT fill:#fadee8
    style DB_ANNOT fill:#fadee8
    style DB_OTHER fill:#fadee8
    style DB_CVE_LST fill:#fadee8
    style DB_CVE_NVD fill:#fadee8
    style SBOM_COMP fill:#fafa69
    style EXPORT1 fill:#a7f8fc
    style EXPORT2 fill:#a7f8fc
    

There are various supported input and output formats, and each of them can be configured using command-line options, as detailed in the following sections:

• SBOM supported formats, represented in yellow on the diagram above.

• CVE and annotation database types, represented in pink.

• Export formats, represented in sky blue.

CVE and annotation databases can also be configured using TOML configuration files.

Custom types can be added by the user thanks to plugin support, for example, to support a new export format, or a new type of annotations database.

The tool loads multiple CVE databases by default, as described in the default configuration section. It is recommended to verify whether the default options meet your needs. If they do not, you can extend or override the default configuration, as explained in the database configuration section.

To understand how this tool identifies vulnerabilities applicable to the components listed in the SBOM, and how the VEX assessment is computed for each vulnerability, refer to the following sections:

• Design: Finding Applicable CVEs

• Design: Compute VEX assessment

Compatibility with Yocto Project

The compatibility with the SBOM generated by the Yocto Project is described in the Yocto Project SBOM subsection.

Examples of invocation

The example below uses as input the SPDX v3.0 SBOM file generated by the Yocto Project, and the additional VEX manifest generated by the vex.bbclass, which contains all the Yocto Project annotations declared in the recipes by the CVE_STATUS variable, as described in the Yocto Project SBOM section.

For example with:

IMAGE_NAME="core-image-minimal-qemuarm"

This example generates as output a JSON file in a similar format, which is generated by the cve-check.bbclass.

sbom-cve-check \
  --sbom-path ${IMAGE_NAME}.rootfs.spdx.json \
  --yocto-vex-manifest ${IMAGE_NAME}.rootfs.json \
  --export-type yocto-cve-check-manifest --export-path out.json

The next example generates a CSV file, with only CVEs that are vulnerable:

sbom-cve-check \
  --sbom-path ${IMAGE_NAME}.rootfs.spdx.json \
  --yocto-vex-manifest ${IMAGE_NAME}.rootfs.json \
  --export-filter-vulnerable \
  --export-type csv --export-path out.csv

The following input files can be found in the Yocto Project deploy directory:

• ${IMAGE_NAME}.rootfs.spdx.json: The SPDX v3.0 SBOM file.

• ${IMAGE_NAME}.rootfs.json: The Yocto Project VEX manifest, generated by the vex.bbclass.

Overview of command-line options

Below is the sbom-cve-check help message that lists available flags. To see an update to date list of option flags, execute:

(.venv) $ sbom-cve-check --help

For detailed documentation of the flags listed in:

• The “Sbom” help section: see SBOM section.

• The “Database configuration” help section: see CVE Databases section.

• The “Export file” and “Export configuration” help sections: see Export section.

For these specific flags:

• --plugins: see the Plugins section.

• --ignore-default-config: see CVE Databases default configuration file subsection.

• --config and --gen-repro-config: see configuration subsection.

• --databases-dir: see CVE Databases database path subsection.

• --no-builtin-products-db: see products database described in configuration subsection.

options:
  -h, --help            show this help message and exit
  --verbose, -v         Increase logging level, can be specified multiple times
  --plugins PATH        Path to plugin module or plugin directory
  --ignore-default-config
                        Do not load default database configuration
  --config, -c PATH     Path to one TOML configuration file
  --databases-dir PATH  Path to the directory containing the databases to be downloaded.
                        Override SBOM_CVE_CHECK_DATABASES_DIR
  --gen-repro-config TOML
                        Path to the TOML config to generate for reproducibility
  --no-builtin-products-db
                        Disable the built-in product database (product name to CPE mappings)
  --version, -V         show program's version number and exit

Sbom:
  --sbom-type, --sbom-format, -F {spdx2,spdx3}
                        Specify the format of the SBOM input file
  --sbom-path, --sbom, -S PATH
                        Path to the SBOM input file
  --ignore-sbom-annotations
                        If set, do not load annotations from the SBOM file
  --sbom-annotation-priority PRIO
                        Priority to use for the annotations read from SBOM input file
  --sbom-obsolete-assessment-check, --no-sbom-obsolete-assessment-check
                        Enable or disable checks of obsolete assessments specified in SBOM

Database configuration:
  --add-db [TYPE PATH KEY=VALUE, ...]
                        Allow to add database from command line
  --set-db-cfg [ID KEY=VALUE, ...]
                        Allow to override database configuration from command line
  --yocto-vex-manifest PATH
                        Shortcut to use a Yocto Project Vex manifest, with default configuration
  --check-obsolete-assessment-by-default
                        If set, by default, check for obsolete assessment
  --disable-auto-updates
                        If set, disable automatic updates for all Git databases

Export file:
  --export-type, --export-format, -f {csv,summary,spdx3,yocto-cve-check-manifest}
                        Export format of generated file
  --export-path, --output, -o PATH
                        Path to the exported file

Export configuration:
  --export-filter-vex-status {under_investigation,affected,not_affected,fixed} ...
                        Only export vulnerabilities with the following VEX status
  --export-filter-vulnerable
                        Only export vulnerabilities which are considered vulnerable
  --export-filter-without-cvss-score
                        If set, do not export vulnerabilities without CVSS score
  --export-filter-min-cvss-score SCORE
                        Only export vulnerabilities with a minimum CVSS score
  --export-filter-without-vers-ranges
                        If set, do not export vulnerabilities without versions
  --export-process-native [{native,target,both}]
                        Process vulnerabilities for native and/or target components
  --export-add-kernel-modules
                        If set, export kernel modules vulnerabilities information
  --export-list-rejected-vuln
                        If set, export vulnerabilities that are rejected
  --export-spdx-pkg-include-vex
                        If set, link VEX information to the binary package in SPDX3

Overview of environment variables

sbom-cve-check is affected by the following environment variables:

• SBOM_CVE_CHECK_DATABASES_DIR: This variable is described in the CVE Databases database path subsection.

• SBOM_CVE_CHECK_PLUGINS: This variable is described in the plugin search locations subsection.

• SBOM_CVE_CHECK_TEST_KEEP_TMP: This variable is described in the developer guide tests section.

• SOURCE_DATE_EPOCH: This variable allows to generate a reproducible export as described in export section.