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

Fully supported

Whinlatter

5.3

Should be functional, not tested (yet)

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