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 SBOM needs to provide the following component information:

  • The component version

  • A way to identify the component: For example, by using a 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 with an associated VEX 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 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 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 Yocto. SPDX v2 generated by other tools is not currently supported, but contributions are welcome.

SPDX v3.0

For a SPDX v3.0 format, the tool expects to receive the path to a JSON-LD file.

The SPDX v3.0.1 provides more information than just a component list. It contains, for example:

  • CVE information.

  • CVSS information associated with a CVE.

  • VEX assessment between a package and a CVE.

This implies that a SPDX v3.0 can also be seen as an annotations database, with the following type spdx3-file.

Annotations

For some SBOM formats, an SBOM file can also be seen as an annotations database. 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, for this annotation database, the --sbom-annotation-priority flag can be used.

The tool can also search for obsolete assessments 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 SBOM

Yocto release compatibility

Codename

Yocto Version

Support status

Kirkstone

4.0

Not supported, and not functional

Scarthgap

5.0

Partially functional. See below

Styhead

5.1

Not supported, and not tested

Walnascar

5.2

Fully supported

Whinlatter

5.3

Should be functional, not tested (yet)

For Yocto Scarthgap, the sbom-cve-check is usable using the latest revision from scarthgap branch. But various CVE annotations are not exported, and the vex.bbclass is missing. Various patches currently in review provide all the missing information needed by sbom-cve-check.

SPDX v3.0

Yocto 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 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"

Yocto, by default, generates the SBOM in the deploy directory with the following name: ${IMAGE_BASENAME}-${MACHINE}.rootfs.spdx.json.

SPDX v2.2

Yocto 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 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"

Yocto 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.

Yocto, by default, generates the SBOM in the deploy directory with the following name: ${IMAGE_BASENAME}-${MACHINE}.rootfs.spdx.tar.zst.

Yocto configuration

To be able to extract all Yocto 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; 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 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"

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"