To diff two SBOMs, run a comparison tool on the old and new files and read three lists: components added, removed, and changed in version. The CycloneDX command line tool does this for CycloneDX files and prints text or JSON. The useful work is deciding which differences deserve a human look.
Steps
- Generate both SBOMs the same way. Same tool, same version, same options. Otherwise you compare tool differences, not release differences.
- Use the same format for both. If one is SPDX, convert it first.
- Run the diff.
cyclonedx-cli diff sbom-1.4.0.json sbom-1.5.0.json --component-versions
- Save the output with the release record.
The component versions option reports versions that were added, removed or modified. Output can be text, the default, or JSON for a pipeline.
Read the result in layers
| Change | What it often means | Action |
|---|---|---|
| New direct component | Someone chose a new dependency | Review who maintains it and why it was added |
| New transitive component | A direct dependency pulled it in | Check which parent brought it |
| Version bumped | Routine update or a fix | Compare to advisories for the old version |
| Version dropped | Component removed or replaced | Confirm the replacement is intended |
| Same name, two versions | Duplicate versions in the tree | The analyze command can list components used at more than one version |
| Unexpected removal | Generation gap or real change | Re-run before trusting it |
The analyze command in the same tool reports components present at several versions, which is a quick duplicate check.
Common traps
- Timestamps and serial numbers differ on every run. A good diff ignores them. Do not treat them as changes.
- A change in your generation environment, such as a new base image, shows up as many changes at once.
- Flat and hierarchical merged SBOMs diff badly against single service ones. Compare like with like.
When to diff automatically
Run the diff in your release pipeline and fail or flag only on rules you have agreed, for example any new component with a license outside policy, or a new component not on an approved list. Everything else goes into the release notes.
Try it yourself
Click through it at your own pace, or open it full screen.
Watch how a change over time is surfaced. That is the same idea as an SBOM diff, applied continuously.
Quick check
Can I diff an SPDX file against a CycloneDX file?
Convert one to match the other first. The CycloneDX tool converts between several formats, including SPDX JSON 2.3, though conversion can lose fields.
Why does my diff show everything changed?
Usually the two files were produced with different tools, options or environments.
Safeguard's SBOM and dependency scanning keeps a component inventory per project that you can compare over time, and a free scan is at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
