Review SBOM changes between releases

A release diff mixes software changes with observation changes unless the baseline controls both. Compare the same product boundary, platform, inventory scope and discovery settings. Record the generator and schema versions. A new cataloger may discover packages already present in the old image; counting them all as new dependencies invents a change in attack surface. Re-scan the older immutable artifact with the newer profile where possible, retaining both original and normalized observations.

Package identity also needs two keys. Use ecosystem, namespace, name and relevant qualifiers to group a component family; use version and content hash to detect a changed instance. Treat one-to-many copies and platform variants explicitly. Comparing full versioned identifiers as an unstructured set produces a removal plus addition for every upgrade and obscures its relationship. The exercise supplies already comparable inventories, except for a deliberately documented generator discovery, so the causal decisions can be made without tools.

An upgrade changes the version of the same component family. A same-version hash change may be a repack, rebuild, local patch or unauthorized replacement; the version string cannot distinguish them. A dependency edge change may expose an existing component to a new runtime path even if the component list is unchanged. A removal is meaningful only when the component is absent from shipped bytes, not merely missing from the new scanner's output.

For Harbor 8.2, parsekit moves from 4.1.0 to 4.1.2 with a corresponding approved dependency change. The helper package retains version 2.0.0 but changes from H20 to H99; no build or supplier record explains it. That is a release hold under the fixture policy. The newly visible libc is a discovery correction because a re-scan of 8.1 also finds it. Testkit disappears because the final image now excludes development tools. These four events deserve different review questions even when a naive set diff calls all of them additions and removals.

The script below groups the components of two CycloneDX SBOMs by package family, using the purl type, namespace, name and arch qualifier, and prints one line per change: VERSION, BYTES for a same-version hash change, ADDED, REMOVED, or COPIES when a family has several instances. It exits with status 1 when a change must hold the release. Version comparison is left to people because ordering rules differ between ecosystems, and a version change may be a downgrade.

Run on Trivy 0.75 SBOMs of alpine:3.22.4 and alpine:3.22.6, it reported six version changes, including libcrypto3 and libssl3 from 3.5.6-r0 to 3.5.8-r0, and confirmed ten unchanged packages by their checksums. With one checksum altered in the newer SBOM it reported BYTES for musl and exited with status 1. On Syft SBOMs of the same image it could confirm nothing, because Syft records no APK package hashes. cyclonedx diff --component-versions from cyclonedx-cli lists version changes as well, but it does not report same-version hash changes.

"""Classify component changes between two CycloneDX JSON SBOMs of the same product boundary."""
import json
import sys

from packageurl import PackageURL  # pip install packageurl-python


def inventory(path):
    with open(path, encoding="utf-8") as f:
        bom = json.load(f)
    items = {}
    for c in bom.get("components", []):
        if c.get("purl"):
            p = PackageURL.from_string(c["purl"])
            # A family is one package on one architecture; version and hashes describe an instance.
            family = (p.type, p.namespace, p.name, (p.qualifiers or {}).get("arch"))
            hashes = {h["alg"]: h["content"] for h in c.get("hashes", [])}
            items.setdefault(family, []).append((p.version, hashes))
    return items


old, new = inventory(sys.argv[1]), inventory(sys.argv[2])
hold, same, unverified = False, 0, 0
for family in sorted(old.keys() | new.keys(), key=str):
    name = "/".join(part for part in family[:3] if part)
    before, after = old.get(family, []), new.get(family, [])
    if len(before) > 1 or len(after) > 1:
        print(f"COPIES    {name}: {len(before)} -> {len(after)} instances, review by hand")
        hold = True
    elif not before:
        print(f"ADDED     {name} {after[0][0]} (rescan the old artifact before calling it new)")
    elif not after:
        print(f"REMOVED   {name} {before[0][0]} (confirm against the shipped files)")
    elif before[0][0] != after[0][0]:
        print(f"VERSION   {name} {before[0][0]} -> {after[0][0]}")
    else:
        (_, h1), (_, h2) = before[0], after[0]
        shared = h1.keys() & h2.keys()
        if any(h1[alg] != h2[alg] for alg in shared):
            print(f"BYTES     {name} {before[0][0]}: same version, different hash: hold")
            hold = True
        elif shared:
            same += 1
        else:
            unverified += 1
print(f"{same} unchanged with matching hashes; {unverified} unchanged with no hash to compare")
sys.exit(1 if hold else 0)

Assign policy consequences to the kind of evidence available. In this example, an unexplained runtime byte substitution blocks promotion. A known upgrade can proceed after the designated functional and security tests; it is not automatically safe because the version number increased. A removed development component should be checked against the final artifact and any build dependency that remains. A discovery-only change requires correcting the older inventory so downstream consumers do not infer a false introduction date. Check license changes as well as version changes, because a new version can change its license: /domains/supply-chain/dependencies/open-source-license-compliance/.

A useful change record includes product and artifact identities, old/new component identities and hashes, relationship changes, explanation evidence, vulnerability and license review references, decision owner, outcome and unresolved facts. Severity scores alone cannot explain a byte substitution or ownership transfer. The decision should survive a reviewer asking why a high-severity known issue was accepted while an unscored substitution blocked: one may have bounded exposure and verified mitigation, whereas the other's origin is not established at all.

Publish each release's inventory as an immutable snapshot and keep a separately versioned diff or decision report. If inventory 8.1 was incomplete, issue a corrected 8.1 document bound to the same artifact and explain the correction. In CycloneDX, a modified BOM keeps its serialNumber and increments version by 1, and consumers use the highest version for a serial number; the CISA 2026 minimum elements likewise expect an SBOM Version that changes with every edit and prompt corrections of errors. Do not silently overwrite history or relabel the older artifact as a new release. Consumers need to distinguish new software, new vulnerability knowledge and improved inventory coverage.

No amount of normalization should remove a fact that changes a security decision. Excluding timestamps and document-local IDs may reduce noise; excluding hashes or architecture can hide material change. Pin the normalization rules and test them with a known substitution. Inventory generation and graph capabilities are documented by Syft and CycloneDX, while the release policy here is an explicit fictional organizational choice. The SBOM inventory lab at /labs/sbom-inventory/ practices finding shipped components that an SBOM omits; the complete decision data below is sufficient on its own.

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. CycloneDX specification overview, version 1.7. Version 1.7 (October 2025).
2. SPDX specification 3.0.1
3. Syft: supported targets and SBOM output
4. CycloneDX 1.7 JSON reference: serialNumber and version
5. CycloneDX CLI
6. Package URL specification
7. CISA: 2026 Minimum Elements for a Software Bill of Materials. 29 July 2026.

Reference information

Tags

SBOMSigning and software updates

SDLC phase

Release

Role

AppSec engineersPlatform engineers and SREs

Download this guide as Markdown

Continue exploring