Metadata-Version: 2.4
Name: buildstream-sbom
Version: 1.1
Summary: A tool to generate SPDX SBoMs from buildstream projects
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pyyaml

<!--
SPDX-FileCopyrightText: 2025 Codethink Limited

SPDX-License-Identifier: Apache-2.0
-->

# 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](https://spdx.dev/) 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](https://docs.buildstream.build/2.5/buildstream.source.html#generating-sourceinfo-for-provenance-information)
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](https://docs.buildstream.build/2.5/buildstream.downloadablefilesource.html#core-downloadable-source-builtins)
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](https://spdx.github.io/spdx-spec/v2.3/package-information/#713-concluded-license-field) |
| copyright-text | [copyrightText](https://spdx.github.io/spdx-spec/v2.3/package-information/#717-copyright-text-field) |
| declared-license | [licenseDeclared](https://spdx.github.io/spdx-spec/v2.3/package-information/#715-declared-license-field) |
| description | [summary](https://spdx.github.io/spdx-spec/v2.3/package-information/#718-package-summary-description-field) |
| homepage | [homepage](https://spdx.github.io/spdx-spec/v2.3/package-information/#711-package-home-page-field) |
| name | [name](https://spdx.github.io/spdx-spec/v2.3/package-information/#71-package-name-field) |
| originator | [originator](https://spdx.github.io/spdx-spec/v2.3/package-information/#76-package-originator-field) |
| supplier | [supplier](https://spdx.github.io/spdx-spec/v2.3/package-information/#75-package-supplier-field) |

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](https://docs.buildstream.build/master/buildstream.source.html#built-in-functionality).

### 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](https://docs.buildstream.build/master/using_commands.html#bst-source-track),
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`](https://docs.astral.sh/uv/#tools) or
[`pipx`](https://pipx.pypa.io/stable/) 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](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/)
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](https://gitlab.com/freedesktop-sdk/freedesktop-sdk/-/blob/master/include/install-extra.yml?ref_type=heads). 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).
