A manifest diff, an ordinary SBOM component diff, an integrity-drift check and an owned-file check answer different questions. Treating them as interchangeable leaves a blind spot: a package can keep the same name and version while its bytes, or the files inside it, change.
| Layer | Primary question | Strongest signal | Important blind spot |
|---|---|---|---|
| {{ .layer }} | {{ .q }} | {{ .s }} | {{ .b }} |
These layers complement one another. sbomlyze does not replace a package manager, an SBOM generator, signature verification, or a vulnerability scanner. It reviews the evidence produced by the build and classifies what changed between two points in time.
- github.com/google/uuid v1.5.0 + github.com/google/uuid v1.6.0
That is an excellent review surface. But the manifest describes dependency resolution, not necessarily the final artifact. It may omit operating-system packages, copied binaries, vendored files, build-stage tools, generated assets, or components introduced by the container base image.
Comparing two inventories reveals changes a manifest misses: a new transitive package, an OS package added by a base-image update, a component removed from the final artifact, a resolved version that differs from the source declaration, or a license and supplier change.
The naive implementation is a JSON diff, which produces noise from timestamps, serial numbers, generated identifiers, and ordering. sbomlyze matches component identity using stable identifiers when available — Package URLs (keeping the subpath) and CPEs, with format-specific references and names as fallbacks — so it can compare SPDX, CycloneDX, and Syft evidence without identical layouts.
Each package is an occurrence: identity, version and location (the lockfile or install path). A package in two lockfiles is two occurrences; none is ever dropped. A version change is reported only within one location, and never by pairing a package that left /Cargo.lock with another version that appeared in /sub/Cargo.lock. Results do not depend on component order.
Upgrade and downgrade follow each ecosystem's own ordering, checked against the real tools:
| Ecosystems | Ordering | Tested pairs |
|---|---|---|
| {{ delimit .ecosystems ", " }} | {{ .rule }} | {{ with .oracle_pairs }}{{ . }} vs the real tool{{ else }}—{{ end }} |
Anything else, and versions like release/v1, report direction unknown — never a guessed downgrade.
example at version 1.4.2 in both SBOMs, a name-and-version diff calls it unchanged — even if the component bytes are different.Integrity drift is the narrow condition where sbomlyze matches a package in both SBOMs at the same location, sees the same non-empty version, and finds that a digest of the same kind changed. The version says consumers should be receiving the same release, while the digest says the recorded content is not the same. Those two facts disagree, so a reviewer should establish why before merging.
Digest kinds are never mixed: CycloneDX and SPDX hashes by algorithm (SHA-256), the Go module checksum from go.sum (go-h1, Syft's syft:metadata:h1Digest) and the Cargo.lock checksum (cargo-checksum). A digest that exists on one side only is a coverage change, not drift. The JSON report's digest_coverage says how many same-version pairs could actually be compared.
go.mod, package-lock.json, workflow files. Those change on every ordinary edit, so they are reported as file_changes, never as integrity drift.Some explanations are benign. The point of the check is not to label every hash change an attack. It is to prevent a silent mismatch from passing as “no dependency change.”
A package digest is one number for the whole package, and many images carry none. Their SBOM still records a hash for every installed file and which package owns it (Syft JSON files + contains, SPDX files + CONTAINS). sbomlyze compares those files too: a package that keeps its version while a file it owns is modified, added or removed is owned-file drift.
package: coreutils 9.1-1 -> 9.1-1
file: /usr/bin/ls sha256 cb30d69b… -> 1a12c71a…
verdict: owned-file drift [deny_owned_file_drift]dpkg marks config files; they are flagged config: true and skipped by the policy unless owned_file_drift_include_config is set, because editing /etc after install is normal. A file can have several owners (busybox and busybox-binsh), and both are reported. What the generator did not hash stays invisible: Syft does not hash Python or npm package files by default, and file_coverage says so.
Hash comparison is only as stable as the evidence around it. Before making the check required:
The last two cases are small, specific, and easy to miss. Giving each its own policy signal (deny_integrity_drift, deny_owned_file_drift) turns an ambiguous SBOM diff into a review decision.