An SBOM is most useful when it is generated as part of the release process, checked against the software that was actually built, and distributed with enough context for others to use it. This guide provides a reusable workflow for creating, validating, storing, comparing, and reviewing SPDX or CycloneDX software bills of materials across source repositories, container images, and release artifacts.
Overview
A software bill of materials (SBOM) is a machine-readable inventory of the components included in a software product. Depending on how it is generated, that inventory may include direct and transitive dependencies, package versions, licenses, hashes, suppliers, build information, and relationships between components.
For an open-source project, an SBOM supports several collaboration tasks. Maintainers can see what enters a release, contributors can review dependency changes, downstream users can assess exposure to a newly reported issue, and security teams can compare inventories across versions. It is not a substitute for testing or vulnerability analysis. It is a structured input to those activities.
Two common exchange formats are SPDX and CycloneDX. The best choice depends on the tools and consumers in your workflow. SPDX is often selected when license and compliance data are central to the use case, while CycloneDX is commonly used for component, service, and dependency relationship data. Treat the format as an interface: select one that your generators, scanners, reviewers, and release systems can consistently read and write.
A practical SBOM lifecycle
- Define scope: decide whether the inventory covers source dependencies, a built application, a container image, infrastructure packages, or all of them.
- Generate: create the SBOM from lockfiles, package manifests, build output, or the final image.
- Validate: check that the document is well-formed, identifies the product and version, and contains the expected components.
- Review: compare it with the previous release and investigate additions, removals, version changes, and unexpected packages.
- Store and distribute: preserve the SBOM with the release or image and make it available to the people who need it.
- Monitor: use the inventory in vulnerability triage and regenerate it when relevant inputs change.
Tool categories to compare
| Tool category | Best input | Useful output | Review point |
|---|---|---|---|
| Manifest or lockfile generator | Package manifests and lockfiles | Declared and resolved dependencies | May not show files installed outside the package manager |
| Filesystem or build scanner | Built application directory | Components detected in the artifact | Can identify what shipped, but may need help mapping names and versions |
| Container image scanner | Final image | Operating-system and application components | Scan the exact image digest released, not only the source tree |
| CI/CD integration | Pull requests, builds, and releases | Automated SBOM files and review results | Confirm artifacts are retained and linked to the right commit |
| Vulnerability and license analyzer | SPDX or CycloneDX document | Findings for components and licenses | Validate identifiers, versions, and severity context before acting |
Checklist by scenario
For a library or source repository
- List every supported package ecosystem and identify its manifest and lockfile.
- Generate an SBOM from the resolved dependency state used by the build, not only from a hand-maintained list.
- Record the repository URL, commit or tag, release version, generation time, and SBOM format.
- Separate development, test, optional, and runtime dependencies when the format and tooling support those distinctions.
- Review the generated document during pull requests that change dependency files.
- Publish the SBOM with the source release or generated package, using a predictable filename and media type.
For a container image
- Generate an inventory for the final image after build steps, cleanup steps, and installation steps have completed.
- Record the image name, immutable digest, tag used for release, base image reference, and source commit.
- Include both operating-system packages and application dependencies where the scanner supports them.
- Keep the SBOM associated with the same image digest that users will pull.
- Scan the image in CI before publication, then repeat the review when the base image or build inputs change.
- Do not assume that a source-repository SBOM represents the contents of the container.
For a release pipeline
- Place SBOM generation after dependency resolution and, where practical, after packaging or image creation.
- Fail the pipeline only on explicitly defined conditions, such as an invalid document or an approved policy violation.
- Store the SBOM as a release artifact and retain the source commit, build identifier, and artifact checksum beside it.
- Generate the same format consistently unless there is a documented reason to provide both SPDX and CycloneDX.
- Make review results visible to maintainers without blocking ordinary contributors from understanding the change.
- Test the publication path so users can actually find and download the document.
For a vulnerability review
- Identify the affected component and compare its package name, ecosystem, version, and qualifier with the SBOM entry.
- Confirm that the finding applies to the shipped product, rather than only to a development dependency or unused image layer.
- Check whether the component is direct, transitive, bundled, vendored, or supplied by the operating system.
- Record the affected release, fixed version if known, exposure, owner, and proposed action.
- Choose an action: upgrade, rebuild, remove, configure, document a justified exception, or investigate further.
- Regenerate and review the SBOM after remediation so the inventory demonstrates the resulting state.
What to double-check
SBOM metadata template
Use a small, consistent metadata block for every generated document. Adapt field names to the selected format and tool:
Product name: example-project
Product version: 2.4.0
Release type: source package | binary | container image
Source repository: https://example.invalid/project
Source commit or tag: v2.4.0
Build identifier: ci-12345
Artifact digest: sha256:...
SBOM format: SPDX or CycloneDX
Format version: [record the version used]
Generated at: [UTC timestamp]
Generator: [tool and version]
Primary contact: [team or issue tracker]
Check that the document has a unique identity, a meaningful version, and an accurate creation timestamp. A document without provenance is harder to trust and difficult to compare with later releases. If the artifact is signed or checksummed by your release process, link the SBOM to that same release evidence.
CycloneDX versus SPDX
Do not choose solely on familiarity. Compare the formats against the consumers in your project:
- Which format can your dependency and container tools generate reliably?
- Which format can your vulnerability, license, repository, and customer workflows ingest?
- Do you need detailed dependency relationships, package properties, services, or composition data?
- Do you need strong alignment with an existing license or compliance process?
- Can contributors validate and diff the files without specialized access?
Whichever format you choose, document the decision in the repository and retain the format version with each artifact. Avoid silently changing formats during a release series; downstream automation may depend on the structure.
Diff review questions
- Did a direct dependency become transitive, or the reverse?
- Did a lockfile update change more packages than expected?
- Did a base image introduce or remove operating-system packages?
- Are new components licensed or sourced in a way the project accepts?
- Does the SBOM contain an unexpected tool, test package, bundled library, or duplicate component?
- Does the release SBOM differ from the artifact built in CI?
Common mistakes
- Generating only from manifests: manifests describe intended dependencies, while the built artifact may contain vendored, bundled, generated, or operating-system components.
- Scanning the wrong object: a source tree, build directory, and final container image can have different inventories. Match the scan target to the distribution channel.
- Publishing without provenance: an unlabelled SBOM cannot easily be connected to a commit, release, image digest, or build.
- Treating every finding as an emergency: validate reachability, product exposure, dependency role, and affected version before assigning an action.
- Ignoring generated-file review: automate generation, but reserve a human review step for unexpected changes and release exceptions.
- Keeping the SBOM only in CI logs: logs can expire or become difficult for users to access. Store the document beside the release artifact.
- Mixing formats without a plan: offering multiple formats can help consumers, but it also increases validation and maintenance work.
- Failing to update tool assumptions: package managers, scanners, schemas, and CI integrations change. Record versions and test upgrades deliberately.
When to revisit
Review this workflow before a new release process is adopted, when the project adds a package ecosystem, when the build moves to a new container base, or when CI/CD runners and artifact storage change. Revisit it whenever a dependency-management tool, SBOM generator, scanner, or schema receives a major update.
At minimum, schedule a periodic maintenance review before seasonal planning cycles and after significant workflow changes. Confirm supported ecosystems, export commands, schema versions, scanner integrations, retention settings, and distribution paths rather than assuming they remain unchanged.
Release-day action list
- Resolve and lock dependencies.
- Build the exact release artifact.
- Generate an SPDX or CycloneDX SBOM for that artifact.
- Validate syntax, metadata, component count, and artifact identity.
- Diff the result against the previous release.
- Investigate unexpected additions, removals, and version changes.
- Run vulnerability and license review using the generated inventory.
- Publish the SBOM beside the release and record its checksum or signature when available.
- Archive the build context needed to reproduce or explain the document.
Use this list as a starting point, then tailor the gates to the project’s release model. The goal is not to produce a decorative file; it is to create a dependable shared record that helps maintainers and users understand what the open-source software release contains.