buildstream-sbom 1.1

A tool to generate SPDX SBoMs from buildstream projects

BuildStream SBOM generator

This tool can be used to produce an SBoM (Software Bill of Materials) describing a BuildStream element and its dependencies. It currently generates SPDX version 2.3.

The manifest contains useful information, such as the package name, version, source locations and dependencies.

Source provenance data

This tool relies on the Source Provenance API introduced in BuildStream 2.5. This API is implemented by buildstream-plugins version 2.5.0 and buildstream-plugins-community 2.1.0. Please make sure your project is using those (or more recent) versions. If your project uses custom source plugins, please make sure that they also implement this API.

Version guessing is handled by individual source plugins, please check the individual plugin documentation for details. Most plugins that implement it do something similar to what DownloadableFileSource does, so it is a good starting point for understanding how this works.

The list of currently supported source provenance attributes that can be specified and used for a Buildstream project is as follows:

Attribute name	Corresponding SPDX attribute
concluded-license	licenseConcluded
copyright-text	copyrightText
declared-license	licenseDeclared
description	summary
homepage	homepage
name	name
originator	originator
supplier	supplier

These can be used in projects by use of the source-provenance-attributes field in the project.conf, this is described in the provenance section of the BuildStream documentation.

source-provenance-attributes snippet

# project.conf

source-provenance-attributes:
  concluded-license: The license as determined by the evidence provided by the source project
  copyright-text: Copyright text defined by the source project
  declared-license: The license of the source project as decided by the authors
  description: Description of the source project
  homepage: The URL of the source project's homepage
  name: The name of the source project
  originator: The name of the person or organisation that created the source package originally
  supplier: The name of the person or organisation that provided the source package

Should any BuildStream plugins implement tracking for source provenance attributes, similar to source tracking, it is recommended for all projects and plugins to use the attribute names exactly as seen above. This ensures the source provenance attributes are always generated identically between different plugins and makes sure they align with projects' definitions in the same way.

Usage

To install, clone this repository and install it using pip (or preferably a tool like uv tool or pipx which install it in a virtual environment).

To use, run buildstream-sbom in a buildstream project passing in the name of elements like you would pass to bst. There are two additional required arguments --spdx-name and --spdx-namespace, to set the SPDX document name and document namespace respectively. See the SPDX specification for details.

buildstream-sbom also accepts some buildstream options, notably -o/--option to set buildstream options, -C/--directory to set the directory containing the buildstream project, and --deps to choose whether to include only runtime dependencies or all dependencies.

On the topic of runtime dependencies, two BuildStream core plugins are treated specially: filter and compose. All build dependencies of elements using these plugins are considered runtime dependencies. You can set the depends-on key in the sbom public domain data to a list of build dependencies to have buildstream-sbom treat these build dependencies as runtime dependencies. This is useful for a script or manual element that copies artifacts from a build dependency into its own artifact.

You can also include licenses that have been extracted from the element's artifacts using --include-licenses. This uses license information installed with tooling such as Freedesktop-SDK's install-extra script. This option can also be used in conjunction with --artifact-checkout-directory (-A), to control where element artifacts are checked out to during processing; useful for if you are checking out larger artifacts and want to specify a different part of a filesystem with more available space (note that artifacts are removed once processed anyway to minimise required storage space).