# SBOM sbom-cve-check tool takes as input a software bill of materials (SBOM). This file provides the list of components (or packages) deployed to the target device. The {term}`SBOM` needs to provide the following component information: - The component version - A way to identify the component: For example, by using a {term}`CPE`, package name, ... For each component listed in the SBOM, the tool searches for applicable CVEs, which may or may not be vulnerable. Then the result of this search can be [exported](export.md) with an associated VEX {term}`assessment` for each CVE. To specify the path to the SBOM, the following mandatory flag needs to be used: `--sbom-path`. Depending on the SBOM format, the path could point to a file, an archive or a directory. ## Supported formats The following SBOM input formats are supported: | Name | Short description | |---------|-------------------------------------| | `spdx2` | SPDX v2.2 Yocto Project SBOM file | | `spdx3` | SPDX v3.0 JSON-LD SBOM file | The SBOM type can be specified by using the `--sbom-type` flag. If this option flag is not specified, *sbom-cve-check* tries to automatically detect the SBOM format based on the file "extension". ### SPDX v2.2 For a {term}`SPDX` v2.2 format, the tool expects to receive the path to either: - a directory containing multiple `.spdx.json` files. - a TAR archive, typically with the following extension: `.spdx.tar.zst`. *sbom-cve-check* was only tested with SBOMs generated by Project. SPDX v2 generated by other tools is not currently supported, but contributions are welcome. ### SPDX v3.0 For a {term}`SPDX` v3.0 format, the tool expects to receive the path to a {term}`JSON-LD` file. The SPDX v3.0.1 provides more information than just a component list. It contains, for example: - {term}`CVE` information. - {term}`CVSS` information associated with a CVE. - {term}`VEX` {term}`assessment` between a package and a CVE. This implies that a SPDX v3.0 can also be seen as an [annotations](#annotations) database, with the following type `spdx3-file`. ## Annotations For some SBOM formats, an SBOM file can also be seen as an [annotations database](database.md). In this case the associated annotation database is automatically created with a default priority of `100`, which is the lowest priority for an annotation database. To configure a custom [priority](database.md#database-priority), for this annotation database, the `--sbom-annotation-priority` flag can be used. The tool can also search for [obsolete assessments](database.md#obsolete-assessment-check) in the annotations contained in the SBOM file. To change the default configuration, the following flags can be used: `--sbom-obsolete-assessment-check`, `--no-sbom-obsolete-assessment-check`. To prevent the automatic creation of an annotation database from the SBOM file, the `--ignore-sbom-annotations` flag needs to be set. ## Yocto Project SBOM ### Yocto Project release compatibility | Codename | Yocto Project Version | Support status | |------------|-----------------------|-------------------------------------------| | Kirkstone | 4.0 | Not supported | | Scarthgap | 5.0 | Supported since 2024-04.14 (yocto-5.0.14) | | Styhead | 5.1 | Not supported, and not tested | | Walnascar | 5.2 | Supported | | Whinlatter | 5.3 | Fully supported | For Yocto Project Scarthgap, the sbom-cve-check is fully usable using the latest revision from `scarthgap` branch. The latest commits include the `vex.bbclass` and allow all CVE annotations to be exported to the SPDX v3.0 file. These improvement will be present in the future 2024-04.14 (yocto-5.0.14) release. ### SPDX v3.0 The Yocto Project is able to generate an SPDX SBOM file in v3.0.1 format. By default, the `create-spdx.bbclass` is inherited: See `meta/conf/distro/defaultsetup.conf`. Since Yocto Project *Styhead* release (5.1), the `create-spdx.bbclass` generates an SPDX v3.0. For older releases, the `create-spdx-3.0.bbclass` needs to be explicitly used: ``` INHERIT:remove = "create-spdx" INHERIT += "create-spdx-3.0" ``` The Yocto Project, by default, generates the SBOM in the `deploy` directory with the following name: `${IMAGE_BASENAME}-${MACHINE}.rootfs.spdx.json`. ### SPDX v2.2 The Yocto Project is able to generate an SPDX SBOM file in v2.2 format. By default, the `create-spdx.bbclass` is inherited: See `meta/conf/distro/defaultsetup.conf`. In Yocto Project *Scarthgap* release (5.0), the `create-spdx.bbclass` generates an SPDX v2.2. For newer releases, the `create-spdx-2.2.bbclass` needs to be explicitly used: ``` INHERIT:remove = "create-spdx" INHERIT += "create-spdx-2.2" ``` The Yocto Project exports very little information about CVE status when using SPDX v2.2. It is recommended to either use SPDX v3.0, or also use the information provided by the manifest generated by `vex.bbclass`. The Yocto Project, by default, generates the SBOM in the `deploy` directory with the following name: `${IMAGE_BASENAME}-${MACHINE}.rootfs.spdx.tar.zst`. ### Yocto Project configuration To be able to extract all Yocto Project annotations specified in the recipes by the `CVE_STATUS` variable, there are 2 options: - Configure `SPDX_INCLUDE_VEX` to `all`, but this is not recommended before Whinlatter (5.3); otherwise, the SPDX generation can be very slow, and the resulting SPDX file can be more than 1GB. It is highly recommended to set `SPDX_INCLUDE_VEX` to `current` (the default value). - Extracts these annotations using the `vex.bbclass` as explained in more detail in the [yocto-vex-manifest](database.md#yocto-vex-manifest) section. This is the recommended method. Note: it is incompatible with `cve-check.bbclass`; only one of these `bbclass` can be enabled at a time. In `local.conf`, the following line needs to be added: ``` INHERIT += "vex" ``` In summary, the following configuration is recommended: - For Scarthgap (5.0): ``` SPDX_INCLUDE_VEX = "current" INHERIT += "vex" ``` - For Whinlatter (5.3) and later: ``` SPDX_INCLUDE_VEX = "all" ``` To be able to exclude CVE if affected source files are not compiled, it is necessary to set `SPDX_INCLUDE_COMPILED_SOURCES` to `1` for recipes that need this extra processing. Typically for the Linux kernel, in `local.conf`, the following line could be added: ``` SPDX_INCLUDE_COMPILED_SOURCES:pn-linux-yocto = "1" ``` For the Linux kernel, the `SPDX_INCLUDE_COMPILED_SOURCES` feature requires the following kernel configuration options to be enabled: ``` CONFIG_DEBUG_KERNEL=y CONFIG_DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT=y CONFIG_DEBUG_INFO=y ``` Yocto relies on debug information to extract the list of compiled source files.