Yocto SBOM Generation

The meta-runsafe-sbom layer generates a CycloneDX v1.6 compatible Software Bill of Materials for a yocto build.

Prerequisites

This layer currently requires RunSafe Identify to be configured for the repository generating the SBOM. If you have not setup the RunSafe Platform, have not enabled Identify for the repository, or do not plan to use the RunSafe Platform, please contact [email protected] for instructions.

Installation

1. Download the latest meta-runsafe-sbom layer to the proper directory in your Yocto project, such as the top level of the poky directory.

$ git clone -b master https://gitlab.com/runsafe-foss/meta-runsafe-sbom.git

2. Add the meta-runsafe-sbom layer to your bblayers.conf file.

$ bitbake-layers add-layer meta-runsafe-sbom

3. Add the RunSafe CI Templates to your CI/CD configuration file:

GitLab: In your .gitlab-ci.yml, add the following to the script section of the job that builds your yocto image:

- !reference [.runsafe-gremlin, setup_script_yocto]

GitHub: In your workflow yml, add the following to the steps section of the job that builds your yocto image:

- uses: runsafesecurity/github-actions/yocto-setup@v1
    with:
      license_key: ${{ secrets.RUNSAFE_LICENSE_KEY }}

Note: The GitHub integration still requires users to create a RUNSAFE_LICENSE_KEY secret, with the license key from the Platform. See the Platform documentation for details on obtaining your license key.

SBOM File Location

The SBOM is generated in build/tmp/deploy/runsafe-sbom/target_sbom.cdx.json.

Configuration

Environment variables are read from the shell environment when bitbake is invoked. Export them before starting your build:

export RUNSAFE_SBOM_METADATA_COMPONENT_NAME="my-firmware"
bitbake my-image

At the start of each build, the layer prints a diagnostic report listing the active RunSafe configuration.

SBOM metadata

These variables configure the top-level metadata component in the generated CycloneDX SBOM.

Variable	Default	Description
RUNSAFE_SBOM_METADATA_COMPONENT_NAME	yocto-image	Name of the software or firmware being built.
RUNSAFE_SBOM_METADATA_COMPONENT_VERSION	1.0.0	Version of the software or firmware being built.
RUNSAFE_SBOM_METADATA_COMPONENT_SUPPLIER	Organization: OpenEmbedded ()	Name of the supplier.
RUNSAFE_SBOM_METADATA_COMPONENT_PREVIOUS_VERSION	(none)	Previous version of the software or firmware being built. When set, stored as a previous_version property on the metadata component.

Offline mode

Variable	Default	Description
RUNSAFE_OFFLINE_ONLY	0	When set to 1, SBOM generation completes locally (with no data sent anywhere from the build system) and upload to the RunSafe Platform is skipped. Use this when you only need the SBOM file on disk and do not want your SBOM uploaded to the RunSafe Platform.

Recipe variables

Per-recipe BitBake variables control how each package appears in the SBOM. Set them in the recipe (.bb) or a .bbappend. Native recipes are skipped and do not appear in the SBOM.

Component identity and CPE

These variables determine each component's name, version, and CPE identifiers used for vulnerability matching.

Variable	Default	Description
CVE_PRODUCT	${BPN}	Product name(s) used for the component name and CPE. Space-separated values create one SBOM component (and CPE) per product. Use vendor:product to set the CPE vendor; otherwise the vendor is *. Example: tiff.bb sets CVE_PRODUCT = "libtiff".
CVE_VERSION	${PV}	Version embedded in each CPE. Defaults to the recipe's package version.
PV	(recipe)	Component version written into the SBOM. Usually identical to CVE_VERSION, but may differ with some recipes.
LICENSE	(recipe)	License recorded on the component. SPDX expressions are stored as CycloneDX license expressions; values containing PD (Public Domain) are stored as a named license.
SPDX_SUPPLIER	Organization: ${SPDX_ORG}	Supplier name written on each collected component.

Example .bbappend overriding product identity for accurate CPE matching:

# recipes-support/curl/curl_%.bbappend
CVE_PRODUCT = "haxx:curl"
CVE_VERSION = "${PV}"
SPDX_SUPPLIER = "Organization: curl"

Multiple products from one recipe:

CVE_PRODUCT = "flex_project:flex westes:flex"

License

This layer is licensed under the MIT license. See LICENSE for more information. The layer was forked and modified from the bgnetworks/meta-dependency-track repo.