Reference · v0.8.0

JSON reference

The diff JSON contract: every field sbomlyze --json prints.

sbomlyze before.json after.json --json prints {overview, findings, diff, violations?, compliance?, warnings?}. This page documents the diff object for consumers that read it instead of re-implementing SBOM diffing. Existing keys keep their names; everything below marked new was added after 0.6.0.

Behavior change in what integrity_drift means

drift_summary.integrity_drift used to count any hash change without a version change, including CycloneDX type: file entries (the SHA-256 of /go.mod or a workflow that Syft directory scans emit). It now counts only packages with the same identity, the same non-empty version and the same location whose digest of the same kind changed. File content changes are in file_changes. On 78 real Syft source SBOM pairs this moved 210 false integrity-drift items (all type: file) to file_changes, leaving 0 integrity drift.

Other changes that affect existing values:

Package changes

FieldMeaning
added[], removed[]Components that appeared or disappeared; every occurrence, with locations
changed[]Packages present on both sides that changed: id, name, location (new), before, after, changes, drift
changed[].drift.typeversion, integrity or metadata
changed[].drift.direction (new)upgrade, downgrade, none (equal precedence, e.g. build metadata) or unknown
changed[].drift.level (new)major, minor, patch, prerelease, revision, none or unknown
changed[].drift.licenses_diff+MIT, -Apache-2.0; also on version changes
changed[].drift.hash_changesDigest changes by kind (SHA-256, go-h1, cargo-checksum)
changed[].drift.files (new)Owned-file counts for a version change: modified, added, removed, unverified, unchanged, all_match
moved[] (new)Same identity and version at another location: id, name, version, from, to
os_change (new)The base OS release changed (from, to, e.g. Debian GNU/Linux 12 (bookworm) 12.10 → … 12.12). Only when both SBOMs name the OS (Syft SPDX does not). Counts as a change for the exit code
source_change (new)The scanned source kept its name but its version or digest changed (a re-pushed image tag): name, from, to. Counts as a change for the exit code
version_set_changes[] (new)Several versions changing at one location with no justified pairing: id, name, location, removed_versions, added_versions. The occurrences are also in added/removed

File changes (new)

FieldMeaning
file_changes[]Files whose content changed: path, hashes_before, hashes_after, owners (name@version, when recorded)
files_added[], files_removed[]Inventory files (Syft JSON, SPDX, CycloneDX type: file) that appeared or disappeared: path, hashes, owners
owned_file_drift[]Packages that kept their version while files they own changed: id, name, version, location, files[] (path, change, config, hashes_before, hashes_after)
file_coveragefiles_compared, files_unverified, ambiguous_paths, owned_files_after, unowned_files_after, config_unknown

Same results across formats (new)

The same image scanned once and written as Syft JSON, CycloneDX and SPDX diffs to nothing, in any combination. To get there:

The scanned image or directory is the source, not a component: an SPDX root package (SPDXRef-DocumentRoot-*, or a described pkg:oci/pkg:docker package) is no longer listed in changed.

Syft JSON dependency-of relationships are read as Syft defines them: the parent is the dependency of the child. Earlier versions read them reversed.

Summary and coverage

FieldMeaning
drift_summary.version_drift, integrity_drift, metadata_driftOccurrence counts per drift type
drift_summary.upgrades, downgrades, unknown_direction (new)Version-change occurrences by direction
drift_summary.distinct_version_changes (new)Distinct identity + from + to
drift_summary.file_changes, license_changes (new)Counts of file_changes and of changed entries with a license difference
drift_summary.owned_file_drift, owned_files_changed (new)Packages with owned-file drift; distinct files involved
digest_coverage (new)Same-version package pairs that could be checked for integrity drift: same_version_pairs, comparable, before_only, after_only, disjoint_kinds, by_kind, packages_total
overview.{before,after}.info.format, spec_version (new)CycloneDX / SPDX / Syft JSON and the spec or schema version

Gates