Generate SBOMs at build time

Trace a build with eBPF to create an SBOM that includes the OS packages and toolchain the build used.

A build-time SBOM lists what a build used, including the compilers, linkers, and OS packages that no package manifest mentions. Observer CLI records every file the build opens or executes, using eBPF, and turns those records into a CycloneDX SBOM.

When to use it

Use a build-time SBOM for C and C++ projects, whose dependencies come from OS packages rather than a package manifest, and for projects that compile native code, such as Go with CGO or Node.js modules built with node-gyp.

Prerequisites

A Linux host with eBPF support. Tracing currently supports apt- and rpm-based distributions; Windows and FreeBSD are not yet supported.
Observer CLI installed. No access token is needed to generate the SBOM, only to upload it.
Root privileges to run the tracer. Run it with sudo and pass -u <user> so the build itself runs as a normal user.

Trace a build and generate the SBOM

Trace the build

sudo observer build -u cicd -- make

This runs make as the user cicd and writes every file the build opened or executed to build-observations.json.

Generate the SBOM

Run observer fs in the same directory. It reads build-observations.json together with any package manifests, such as go.mod or package.json, and writes one SBOM with both:

observer fs -o sbom.cdx.json .

If the project has no package manifest, you can skip this step and write the SBOM during the trace instead, with -b:

sudo observer build -u cicd -b sbom.cdx.json -- make

Either way, dependencies the built software doesn't load at runtime, such as the compiler, get scope: excluded.

Key flags

-o, --output <file>: output file for build observations (default build-observations.json).
-b, --sbom <file>: also write a CycloneDX SBOM from the observations.
-u, --user <name>: run the build as this user instead of root.
-c, --config <observer.yaml>: metadata overrides used when generating SBOMs.
-e, --exclude <pattern>: exclude files or globs from the observation results.

The tracer is build-observer. It resolves each observed file to the OS package that owns it. Files no package owns are listed separately, which can point to dependencies that were copied in outside the package manager.

Next steps

Generate and upload SBOMs for upload options.
Enforce policies in CI/CD to check build-time SBOMs in a pipeline.
CLI reference for every command and flag.