# User Guide ## Dependencies & installation This project depends on: - Python 3.10 or later. - [spdx_python_model](https://pypi.org/project/spdx-python-model/) for reading and writing SPDX v3.0 file. It has the following optional dependencies: - [tomli_w](https://pypi.org/project/tomli_w/) for generating TOML configuration file. - [PyYAML](https://pypi.org/project/PyYAML/) for simple CVE annotations stored in YAML files. - [argcomplete](https://pypi.org/project/argcomplete/) for autocompletion support. It has the following additional dependencies for Python 3.10 (< 3.11): - [python-dateutil](https://pypi.org/project/python-dateutil/) - [tomli](https://pypi.org/project/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: ```shell (.venv) $ pip install . ``` - From the Python Package Index (PyPI) repository, run: ```shell (.venv) $ pip install sbom-cve-check ``` And to install it, with all optional dependencies, execute either: - From the git sources: ```shell (.venv) $ pip install .[extra] ``` - From the PyPI repository: ```shell (.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](dev-guide.md#tool-installation-for-development). ## Usage The `sbom-cve-check` CLI tool takes as input an [SBOM](sbom.md), for example, an SPDX v3.0 JSON-LD file, which may contain CVE annotations, and generate as output one or multiple [export](export.md) files. The tool can be configured to take various kinds of CVE and annotation [databases](database.md). ```mermaid 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](sbom.md#supported-formats), represented in yellow on the diagram above. - [CVE and annotation database types](database.md#database-type), represented in pink. - [Export formats](export.md#export-formats), represented in sky blue. CVE and annotation databases can also be configured using TOML [configuration](database.md#database-configuration) files. Custom types can be added by the user thanks to [plugin](plugins.md) 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](database.md#default-configuration-file) 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](database.md#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.md#find-applicable-cve) - [Design: Compute VEX assessment](design.md#compute-vex-assessment) ## Compatibility with Yocto Project The compatibility with the SBOM generated by the Yocto Project is described in the [Yocto Project SBOM](sbom.md#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]( sbom.md#yocto-project-sbom) section. For example with: ```shell IMAGE_NAME="core-image-minimal-qemuarm" ``` This example generates as output a JSON file in a [similar format](export.md#yocto-project-cve-check-format), which is generated by the `cve-check.bbclass`. ```shell 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: ```shell 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: ```shell (.venv) $ sbom-cve-check --help ``` For detailed documentation of the flags listed in: - The "*Sbom*" help section: see [SBOM](sbom.md) section. - The "*Database configuration*" help section: see [CVE Databases](database.md) section. - The "*Export file*" and "*Export configuration*" help sections: see [Export](export.md) section. For these specific flags: - `--plugins`: see the [Plugins](plugins.md) section. - `--ignore-default-config`: see CVE Databases [default configuration file](database.md#default-configuration-file) subsection. - `--config` and `--gen-repro-config`: see [configuration](config.md) subsection. - `--databases-dir`: see CVE Databases [database path](database.md#default-configuration-file) subsection. - `--no-builtin-products-db`: see products database described in [configuration](config.md#products) subsection. ```yaml 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](database.md#default-configuration-file) subsection. - `SBOM_CVE_CHECK_PLUGINS`: This variable is described in the plugin [search locations](plugins.md#search-locations) subsection. - `SBOM_CVE_CHECK_TEST_KEEP_TMP`: This variable is described in the developer guide [tests](dev-guide.md#tests) section. - `SOURCE_DATE_EPOCH`: This variable allows to generate a reproducible export as described in [export](export.md#reproducible-output) section.