rezmoss/sbomlyzeGit diff für SBOMs – CycloneDX-, SPDX- und Syft-Dokumente vergleichen, Manipulationen erkennen und als CI-Gate dienen.
# sbomlyze
**`git diff` für deine SBOM.** Vergleiche zwei Software Bills of Materials und sieh, was sich zwischen Builds, Versionen und Releases geändert hat.
sbomlyze vergleicht Komponenten-Hashes, nicht nur Versionsstrings. Wenn ein Angreifer ein Paket austauscht, ohne dessen Version zu erhöhen, markiert sbomlyze dies. Generatoren und Schwachstellen-Scanner übersehen dies.
[![CI][ci-img]][ci]
[![GitHub Marketplace][marketplace-img]][marketplace]
[![GitHub Release][release-img]][release]
[![Go Report Card][go-report-img]][go-report]
[![OpenSSF Scorecard][scorecard-img]][scorecard]
[![OpenSSF Best Practices][best-practices-img]][best-practices]
[![License: Apache-2.0][license-img]][license]
[![Downloads][download-img]][download]
[](https://github.com/rezmoss/sbomlyze-go-spdx-demo/pull/2)
Erfahre, warum sich dieses Signal von einem Manifest- oder gewöhnlichen Komponenten-Diff unterscheidet, in
[Manifest diff vs. SBOM diff vs. integrity drift](https://github.com/rezmoss/sbomlyze/blob/main/docs/manifest-vs-sbom-vs-integrity-drift.md).
> Generatoren erstellen SBOMs und Scanner finden CVEs. sbomlyze sagt dir, was sich zwischen zwei SBOMs geändert hat und ob du ihnen vertrauen kannst.
> Führe es nach deinem Generator aus: `syft image:tag -o cyclonedx-json | sbomlyze - --compliance` analysiert und bewertet die generierte SBOM ohne temporäre Datei. Vergleiche sie mit einer Baseline, um Drift zu klassifizieren und deine Pipeline zu steuern.
## GitHub Action Schnellstart
Füge [SBOMlyze Diff from GitHub Marketplace][marketplace] hinzu, um eine eingecheckte
oder separat generierte SBOM mit ihrer Git-Baseline zu vergleichen. Der unveränderliche SHA unten ist
die veröffentlichte `v0.5.1` Action:```yaml
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
- uses: rezmoss/sbomlyze@31503690611fda8ebba4ed2bd186eda000442594 # v0.5.1
with:
sbom-path: build/sbom.cdx.json
```
Die Action schreibt standardmäßig eine Job-Zusammenfassung und kann Richtlinien durchsetzen, Integritätsabweichungen melden, SARIF hochladen oder einen einzelnen Pull-Request-Kommentar pflegen. Siehe
[die vollständige Action-Referenz](https://github.com/rezmoss/sbomlyze/blob/main/ACTION.md) für Eingaben, Ausgaben, Berechtigungen
und Sicherheitshinweise. Siehe das
[Live-Demonstrations-Repository](https://github.com/rezmoss/sbomlyze-action-demo)
für ein bestandenes Abhängigkeits-Update und eine blockierte Hash-Änderung bei gleicher Version, mit
öffentlichen Workflow-Läufen und SARIF-Nachweisen.
Für formatspezifisches Dogfooding verwenden Sie das öffentliche
[Go + SPDX](https://github.com/rezmoss/sbomlyze-go-spdx-demo),
[Node + CycloneDX](https://github.com/rezmoss/sbomlyze-node-cyclonedx-demo) oder
[Container](https://github.com/rezmoss/sbomlyze-container-demo)-Beispiel. Jedes
enthält fünf reproduzierbare Review-Szenarien. Der
[10-Minuten-Beta-Leitfaden](https://github.com/rezmoss/sbomlyze/blob/main/BETA.md) sammelt vier gezielte Fragen zu Aktivierung und Signalqualität.
Generierte SBOMs müssen nicht committet werden: `baseline: workflow-artifact`
ruft das zuletzt passende Artefakt aus einem erfolgreichen Standard-Branch-Lauf ab. Ein [gepinnter Syft-Begleit-Workflow](https://github.com/rezmoss/sbomlyze/blob/main/examples/workflows/syft-companion.yml)
zeigt Generierung und Baseline-Veröffentlichung, während SBOMlyze weiterhin für
Review und Richtlinien verantwortlich bleibt.
## Warum sbomlyze?
Viele Tools generieren SBOMs. Wenige vergleichen sie, und noch weniger sagen Ihnen, ob eine Änderung routinemäßig oder eine Supply-Chain-Warnung ist. sbomlyze schließt diese Lücke.
| Fähigkeit | **sbomlyze** | cyclonedx-cli | sbomqs | syft / trivy |
|---|:---:|:---:|:---:|:---:|
| SBOM-zu-SBOM-**Diff** | ✅ | basic | ❌ | ❌ |
| **Integritäts-/Manipulations**-Abweichung (Hash geändert ohne Version) | ✅ | ❌ | ❌ | ❌ |
| Dependency-Graph-Diff + Risiko durch transitive Tiefe | ✅ | ❌ | ❌ | ❌ |
| **NTIA / CISA / BSI**-Compliance-Bewertung | ✅ | ❌ | ✅ | ❌ |
| Formatkonvertierung (Syft / CycloneDX / SPDX) | ✅ | ✅ | ❌ | partial |
| **TUI + Web UI**-Explorer | ✅ | ❌ | ❌ | ❌ |
| Policy-Gate + SARIF / JUnit / Markdown / HTML / Patch | ✅ | partial | partial | partial |
## Funktionen
- **SBOM-Diffing**: Vergleichen Sie zwei SBOMs und sehen Sie hinzugefügte, entfernte und geänderte Komponenten auf einen Blick
- **Drift-Klassifizierung**: Unterscheiden Sie Versionsdrift von **Integritätsdrift** (ein Hash hat sich ohne Versionsänderung geändert, was auf Manipulation hindeutet) und Metadatendrift
- **Compliance-Bewertung**: Bewerten Sie jede SBOM anhand der Mindestelemente von **NTIA**, **CISA 2025** und **BSI TR-03183**
- **Dependency-Graph-Diff**: Verfolgen Sie transitive Abhängigkeiten und Supply-Chain-Tiefe
- **Multi-Format-Unterstützung**: Syft, CycloneDX, SPDX (JSON)
- **Formatkonvertierung**: Konvertieren Sie zwischen CycloneDX-, SPDX- und Syft-Formaten
- **Starke Identitätsabgleichung**: PURL → CPE → BOM-ref → Namespace/Name-Präzedenz
- **Statistikmodus**: Analysieren Sie einzelne SBOMs auf Lizenz-, Abhängigkeits- und Integritätsmetriken
- **Interaktiver TUI-Modus**: Erkunden Sie SBOMs mit Tastaturnavigation und Suche
- **Web-UI-Modus**: Browserbasierter SBOM-Explorer mit Drag-and-Drop-Upload
- **Policy-Engine**: Setzen Sie Drift-, Lizenz- und Compliance-Score-Regeln in CI-Pipelines durch
- **GitHub Marketplace Action**: Steuern Sie Pull Requests anhand von SBOM-Drift mit Job-Zusammenfassung, SARIF und optionaler Kommentarausgabe
- **Duplikat- und Kollisionserkennung**: Finden Sie mehrere Versionen desselben Pakets und mehrdeutige Identitätsübereinstimmungen
- **Mehrere Ausgabeformate**: Text, JSON, SARIF, JUnit XML, Markdown, HTML, JSON Patch
- **Tolerantes Parsing**: Fahren Sie bei Fehlern mit strukturierten Warnungen fort
## Installation
### Homebrew (macOS/Linux)```bash
brew install rezmoss/sbomlyze/sbomlyze
```
### Installer-Skript
Das Installer-Skript lädt die passende Binärdatei für Ihr Betriebssystem/Ihre Architektur herunter:```bash
# Install to ./bin
curl -sSfL https://raw.githubusercontent.com/rezmoss/sbomlyze/main/install.sh | sh
# Install to /usr/local/bin (requires sudo)
curl -sSfL https://raw.githubusercontent.com/rezmoss/sbomlyze/main/install.sh | sudo sh -s -- -b /usr/local/bin
# Install specific version
curl -sSfL https://raw.githubusercontent.com/rezmoss/sbomlyze/main/install.sh | sh -s -- -v 0.4.0
```
**Installer-Optionen:**
| Option | Beschreibung |
|--------|-------------|
| `-b <dir>` | Installationsverzeichnis (Standard: `./bin`) |
| `-d` | Debug-Ausgabe aktivieren |
| `-v <ver>` | Bestimmte Version installieren (Standard: neueste) |
Der Installer überprüft immer die Prüfsumme des Releases. Wenn eine kompatible GitHub CLI
installiert ist, überprüft er außerdem die Build-Provenienz des Releases und schlägt fehl,
wenn diese Überprüfung nicht erfolgreich ist.
### Go Install```bash
go install github.com/rezmoss/sbomlyze/cmd/sbomlyze@latest
```
### Aus Binär-Release
Laden Sie die neueste Binärdatei von [GitHub Releases](https://github.com/rezmoss/sbomlyze/releases) herunter.
Ab v0.3.7 werden Release-Archive mit GitHub-Artefakt-Attestierungen veröffentlicht. Überprüfen Sie einen Download unabhängig mit:```bash
gh attestation verify ./sbomlyze_0.4.0_Linux_x86_64.tar.gz \
--repo rezmoss/sbomlyze \
--signer-workflow rezmoss/sbomlyze/.github/workflows/release.yml
```
Unsigned apt-, rpm- und apk-Repository-Anweisungen wurden entfernt, bis die
Repositories die paketmanager-native Signaturüberprüfung unterstützen.
**macOS-Benutzer:** Entfernen Sie das Quarantäne-Flag nach dem Herunterladen:```bash
xattr -d com.apple.quarantine ./sbomlyze
chmod +x ./sbomlyze
```
### Aus dem Quellcode erstellen```bash
git clone https://github.com/rezmoss/sbomlyze.git
cd sbomlyze
go build -o sbomlyze ./cmd/sbomlyze
```
## Schnellstart```bash
# Compare two SBOMs (the headline use case)
sbomlyze before.json after.json
# Analyze a single SBOM
sbomlyze image.json
# Read an SBOM from standard input
syft image:tag -o cyclonedx-json | sbomlyze -
# Use standard input on either side of a diff
syft image:tag -o cyclonedx-json | sbomlyze baseline.json -
# Score an SBOM against NTIA / CISA / BSI minimum elements
sbomlyze image.json --compliance
# Interactive TUI explorer
sbomlyze image.json -i
# Web UI (opens browser)
sbomlyze -web
# Convert between SBOM formats
sbomlyze convert syft.json --to spdx
sbomlyze convert cdx.json --to syft -o output.json
# JSON output for CI integration
sbomlyze before.json after.json --json
# SARIF output for GitHub Code Scanning
sbomlyze before.json after.json --format sarif
# Markdown report for PR comments
sbomlyze before.json after.json --format markdown
# Apply policy checks
sbomlyze before.json after.json --policy policy.json
```
## Verwendung```
sbomlyze <sbom1|-> [sbom2|-] [options]
sbomlyze convert <sbom|-> --to <format> [-o output]
Modes:
Single file: sbomlyze <sbom> [--json] Show statistics
Interactive: sbomlyze <sbom> -i Interactive explorer
Convert: sbomlyze convert <sbom> --to <fmt> Convert SBOM format
Web server: sbomlyze -web [--port 8080] Web UI explorer
Two files: sbomlyze <sbom1> <sbom2> [...] Show diff
Use `-` in place of one SBOM path to read it from standard input.
Options:
-i, --interactive Interactive TUI explorer
-web, --web Start web UI server
--port <port> Web server port (default 8080)
--json Output in JSON format (shortcut for --format json)
--format <format> Output format: text, json, sarif, junit, markdown, html, patch
--compliance Show NTIA/CISA/BSI compliance scoring
--policy <file> Policy file for CI checks
--strict Fail on parse warnings
--tolerant Continue on parse warnings (default)
--no-pager Disable automatic paging of output
--to <format> Target format for convert: cyclonedx (cdx), spdx, syft
-o, --output <file> Output file for convert (default: stdout)
--version, -v Show version information
--help, -h Show this help message
```
## Befehle
### Statistikmodus (Einzelne Datei)
Analysiere eine SBOM, um Einblicke in Komponenten, Lizenzen und Abhängigkeiten zu erhalten.```bash
sbomlyze image.json
```
Die Ausgabe enthält den Scan-Kontext, automatisch erkannte wichtige Befunde und Statistiken:```
Scan Context:
Tool: syft 1.40.1
Schema: 16.0.18
Scan Scope: all-layers
Source Type: image
Source: alpine:latest
Key Findings:
💻 OS/Distro: Alpine Linux v3.21
📦 Dominated by apk: 71 of 71 packages (100.0%)
📂 8,542 files tracked on filesystem
🔗 Relationships: 71 containment + 64 dependency
📜 License profile: 72% permissive, 20% copyleft
⚠️ Low hash coverage: 0.0% (71 of 71 missing)
🔍 Top catalogers: apkdb-cataloger (71)
📦 SBOM Statistics
==================
Total Components: 71
By Package Type:
apk 71
Licenses:
With license: 71
Without license: 0
Top Licenses:
MIT 17
BSD-3-Clause 8
GPL-2.0-only 8
Integrity:
With hashes: 0
Without hashes: 71
Dependencies:
Components with deps: 65
Total dep relations: 176
```
#### Wichtige Erkenntnisse
sbomlyze generiert automatisch Erkenntnisse über Ihre SBOM. Für die Einzeldateianalyse umfassen diese:
| Erkenntnis | Beschreibung |
|---------|-------------|
| **OS-/Distro-Erkennung** | Identifiziert das Betriebssystem oder die Distribution aus den SBOM-Metadaten |
| **Dominantes Ökosystem** | Meldet, wenn ein Pakettyp dominiert (>60 % aller Pakete) |
| **Dateisystem-Footprint** | Anzahl der verfolgten Dateien im Dateisystem |
| **Beziehungsdichte** | Zählt Containment- und Dependency-of-Beziehungen |
| **Standort-Hotspots** | Top-Verzeichnisse, in denen Komponenten gefunden werden |
| **Lizenzrisikoprofil** | Aufschlüsselung der Prozentsätze von permissiven/Copyleft/unbekannten Lizenzen |
| **Datenqualitätswarnungen** | Warnungen, wenn die Abdeckung von Lizenzen (<50 %), Hashes (<50 %) oder PURLs (<80 %) gering ist |
| **Duplikatswarnungen** | Markiert doppelte Komponentengruppen |
| **Katalogisierer-Aufschlüsselung** | Top-Scanner/Katalogisierer, die Komponenten erkannt haben (Syft-SBOMs) |
#### Abdeckungsmetriken
Der Statistikmodus berechnet Abdeckungsprozentsätze zur Bewertung der Datenqualität:
| Metrik | Beschreibung |
|--------|-------------|
| **PURL-Abdeckung** | Prozentsatz der Komponenten mit Package URLs |
| **CPE-Abdeckung** | Prozentsatz der Komponenten mit CPEs (Bereitschaft für Schwachstellenscans) |
| **Lizenzabdeckung** | Prozentsatz der Komponenten mit mindestens einer Lizenz |
| **Hash-Abdeckung** | Prozentsatz der Komponenten mit Integritätshashes |
#### Lizenzkategorisierung
Lizenzen werden automatisch kategorisiert in:
| Kategorie | Beispiele |
|----------|----------|
| **Copyleft** | GPL, LGPL, AGPL, MPL, EPL, CDDL |
| **Permissiv** | MIT, BSD, Apache, ISC, Zlib, Unlicense |
| **Public Domain** | Public-Domain-Widmungen |
| **Unbekannt** | Nicht erkannte oder fehlende Lizenzen |
### Konvertierungsmodus
Konvertiert SBOMs zwischen den Formaten CycloneDX, SPDX und Syft JSON. Das Eingabeformat wird automatisch erkannt.```bash
# CycloneDX to SPDX
sbomlyze convert image.cdx.json --to spdx
# Syft to CycloneDX (cdx is an alias for cyclonedx)
sbomlyze convert syft-output.json --to cdx
# SPDX to Syft, writing to a file
sbomlyze convert spdx-output.json --to syft -o converted.json
```
#### Unterstützte Zielformate
| Format | `--to`-Wert | Ausgabe |
|--------|-------------|--------|
| CycloneDX 1.5 | `cyclonedx` oder `cdx` | CycloneDX JSON mit Metadaten, Abhängigkeiten und Eigenschaften |
| SPDX 2.3 | `spdx` | SPDX JSON mit Paketen, Beziehungen und externen Referenzen |
| Syft | `syft` | Syft JSON mit Artefakten, Beziehungen, Quelle und Distro-Informationen |
#### Was erhalten bleibt
Die Konvertierung bewahrt Komponentennamen, Versionen, PURLs, CPEs, Lizenzen, Hashes, Lieferanteninformationen und Abhängigkeitsbeziehungen. Formatspezifische Felder (z. B. Syft-Sprache, foundBy, locations) werden bei der Konvertierung zu CDX über CycloneDX-Eigenschaften weitergegeben.
### Diff-Modus (Zwei Dateien)
Vergleichen Sie zwei SBOMs, um zu sehen, was sich zwischen Versionen geändert hat.```bash
sbomlyze v1.0.json v2.0.json
```
#### Diff-Übersicht
Der Diff beginnt mit einem Side-by-Side-Vergleich der Metadaten (Dateinamen, Größen, OS-Informationen, Tool-Informationen, Komponentenanzahl), gefolgt von Details zum Scan-Kontext, sofern verfügbar.
#### Ausgabe```
📊 Drift Summary:
📦 Version drift: 58 components
⚠️ Integrity drift: 1 component (hash changed without version change!)
📝 Metadata drift: 2 components
🔑 Key Findings:
📈 Attack surface: +5 packages (7.0%), +120 files (3.2%)
🚨 2 version downgrades detected: openssl 3.1.4→3.0.2, curl 8.5.0→8.4.0
🔄 56 version upgrades (2 major, 12 minor, 42 patch) among 65 shared packages
⚠️ Integrity drift (1 total): 1 npm (review recommended)
❌ python ecosystem entirely removed (15 → 0 packages)
➕ New ecosystem: golang (8 packages)
✅ Core system packages stable: apk (71) unchanged
+ Added (2):
+ libgcrypt 1.10.3-r0
+ libgpg-error 1.49-r0
- Removed (3):
- libapk 3.0.3-r1
- libgcc 15.2.0-r2
- nghttp3 1.13.1-r0
~ Changed (58):
~ nginx
version: 1.29.4-r1 -> 1.27.3-r1
~ suspicious-pkg ⚠️ [INTEGRITY]
hash[SHA256]: abc123 -> def456
>> Added dependencies:
pkg:apk/alpine/libxslt: +[so:libgcrypt.so.20]
<< Removed dependencies:
pkg:apk/alpine/libcurl: -[so:libnghttp3.so.9]
🔗 New transitive dependencies (3):
+ pkg:npm/lodash (depth 2)
via: [pkg:npm/my-app pkg:npm/express pkg:npm/lodash]
+ pkg:npm/underscore (depth 3)
via: [pkg:npm/my-app pkg:npm/express pkg:npm/lodash pkg:npm/underscore]
📊 New deps by depth:
Depth 2: 1
Depth 3+ (risky): 2 ⚠️
```
#### Diff – Wichtige Erkenntnisse
Im Diff-Modus generiert sbomlyze automatisch umfangreichere Einblicke durch den Vergleich beider SBOMs:
| Erkenntnis | Beschreibung |
|---------|-------------|
| **Scan-Kontext-Abweichung** | Warnt, wenn sich die Schema-Version oder der Scan-Umfang zwischen den SBOMs geändert hat |
| **Delta der Angriffsfläche** | Änderungen der Anzahl von Paketen, Dateien und Beziehungen mit Prozentangaben |
| **Verschwundene/neue Ökosysteme** | Pakettypen, die vollständig erschienen oder verschwunden sind |
| **OS/Distro-Migration** | Erkennt Änderungen des Betriebssystems zwischen Scans |
| **Analyse von Versionsänderungen** | Zählt Upgrades vs. Downgrades, klassifiziert Änderungen als Major/Minor/Patch |
| **Versions-Downgrades** | Markiert Downgrades als Sicherheitssignal mit Komponentendetails |
| **Kontext der Integritätsabweichung** | Schlüsselt Integritätsabweichungen nach Pakettyp mit Risikohinweisen auf |
| **Dominante Pfadmuster** | Konzentrierte Änderungen nach Typ und Dateisystempfad |
| **Hotspots für Entfernung/Hinzufügung** | Top-Verzeichnisse, die von Änderungen betroffen sind |
| **Stabile Typen** | Pakettypen mit identischen Anzahlen (unveränderter Kern) |
| **Verschiebungen der Lizenzkategorien** | Änderungen im Gleichgewicht zwischen Copyleft und Permissive |
| **Lücken im Katalogisierer** | Scanner, die Pakete in Before, aber keine in After gefunden haben |
#### Paketstichproben nach Typ
Hinzugefügte und entfernte Komponenten werden nach Pakettyp mit Beispielauflistungen gruppiert, sodass leicht erkennbar ist, was sich in jedem Ökosystem geändert hat.
## Compliance-Bewertung
Bewerten Sie jede SBOM anhand der drei wichtigsten Minimum-Element-Frameworks, um die Frage zu beantworten, die Auditoren und Beschaffungsteams immer wieder stellen: **„Ist diese SBOM vollständig genug?“**```bash
# Score a single SBOM
sbomlyze image.json --compliance
# Score alongside a diff
sbomlyze before.json after.json --compliance
# As JSON for CI
sbomlyze image.json --compliance --json
```
### Bewertete Frameworks
| Framework | Prüfungen | Wichtige Anforderungen |
|-----------|--------|----------------------|
| **NTIA Minimum Elements** (2021) | 7 | Name, Version, Lieferant, eindeutige IDs (PURL/CPE), Abhängigkeitsbeziehungen, SBOM-Autor, Zeitstempel |
| **CISA 2025 Minimum Elements** (Aug 2025 Entwurf) | 10 | fügt Softwarehersteller, Lizenzinformationen, **Komponenten-Hash** und Toolname zusätzlich zu NTIA hinzu |
| **BSI TR-03183-2** (v2.1.0, 2025) | 9 | erfordert Kontakt des Komponentenerstellers, **SHA-512-Hash**, Lizenzen im SPDX-Format und Kontakt des SBOM-Erstellers |
### Darstellung der Bewertung
Jedes Framework meldet einen Prozentsatz (bestandene Prüfungen / Gesamtprüfungen) sowie eine Gesamtbewertung (Durchschnitt über alle Frameworks), mit Statusindikatoren:
| Indikator | Bewertung |
|-----------|-------|
| 🟢 | ≥ 90% |
| 🟡 | 70–89% |
| 🟠 | 50–69% |
| 🔴 | < 50% |
Die JSON-Ausgabe (`--compliance --json`) enthält den vollständigen Bericht mit Pass/Fail-Details pro Prüfung; das HTML-Format bettet den Compliance-Bericht in die Berichtsseite ein.
### Compliance-Gating in CI
Erzwingen Sie Compliance-Schwellenwerte über die [Policy Engine](#policy-engine). Das Setzen eines beliebigen Schwellenwerts löst die Compliance-Bewertung ohne das `--compliance`-Flag aus:```json
{
"min_ntia_score": 85,
"min_cisa_score": 70,
"min_bsi_score": 80,
"min_overall_compliance": 75
}
```
---
[Read more](https://github.com/rezmoss/sbomlyze)