# 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:
```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](cve-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](cve-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](cve-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.

## Compatibility with Yocto

The compatibility with the SBOM generated by Yocto is described in the
[Yocto SBOM](sbom.md#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](sbom.md#yocto-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-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 `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:
```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](cve-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](cve-database.md#default-configuration-file)
   subsection.
 - `--config`: see CVE Databases
   [database configuration](cve-database.md#default-configuration-file)
   subsection.
 - `--databases-dir`: see CVE Databases
   [database path](cve-database.md#default-configuration-file) 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 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](cve-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.