User Guide

Dependencies & installation

This project depends on:

  • Python 3.11 or later

  • spdx_python_model

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:

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.

Compatibility with Yocto

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

Examples of invocation

The example below uses as input the SPDX v3.0 SBOM file generated by Yocto, and the additional VEX manifest generated by the vex.bbclass, which contains all the Yocto annotations declared in the recipes by the CVE_STATUS variable, as described in the Yocto 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 deploy directory:

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

  • ${IMAGE_NAME}.rootfs.json: The Yocto 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:

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 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
  --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 CVE or annotation database from command line
  --yocto-vex-manifest PATH
                        Shortcut to specify a Yocto Vex manifest, with default configuration
  --check-obsolete-assessment-by-default
                        If set, by default, check for obsolete assessment

Export file:
  --export-type, --export-format, -f {csv,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 add, in exported file, CVEs with the following VEX status
  --export-filter-vulnerable
                        Only add, in exported file, CVEs which are considered vulnerable
  --export-filter-cve-without-cvss-score
                        If set, do not add CVE without CVSS score, in exported file
  --export-filter-cve-min-cvss-score EXPORT_FILTER_CVE_MIN_CVSS_SCORE
                        Only add, in exported file, CVEs with a minimum CVSS score
  --export-filter-cve-without-versions
                        If set, do not add CVE without versions, in exported file
  --export-add-kernel-modules
                        If set, add CVE information to kernel modules, in exported file
  --export-list-rejected-cve
                        If set, list CVEs that are rejected, in exported file

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.