Zum Inhalt springen
Trainingslager IT-Trainingslager

Kapitel 7: SBOM nach CycloneDX/SPDX und Abhängigkeitsanalyse (Syft, Dependency-Track)

In diesem Kapitel lernst du:

  • was eine Software-Stückliste (SBOM) ist und was sie enthalten muss
  • die Unterschiede zwischen CycloneDX und SPDX sowie die Rolle von PURL, CPE und VEX
  • wie du mit Syft SBOMs aus Quellcode und Container-Images erzeugst und mit jq untersuchst
  • wie du eine SBOM ohne erneuten Image-Scan auf Schwachstellen prüfst und als Attestation ans Image hängst
  • wie Dependency-Track SBOMs dauerhaft überwacht, Policies durchsetzt und in die Pipeline eingebunden wird

Worum geht es?

Auf jeder Packung Müsli steht eine Zutatenliste. Wenn eine Charge Haselnüsse verunreinigt ist, kann der Hersteller sofort sagen, welche Produkte betroffen sind, und du als Allergiker siehst es auf einen Blick. Ohne Zutatenliste müsste man jede Packung ins Labor schicken.

Software ist heute zu großen Teilen aus fremden Zutaten gebaut: Bibliotheken, Betriebssystem-Pakete, Laufzeitumgebungen. Eine SBOM (Software Bill of Materials, Software-Stückliste) ist die Zutatenliste dafür. Als im Dezember 2021 die Lücke Log4Shell bekannt wurde, war die wichtigste Frage in jeder IT-Abteilung: „Wo setzen wir log4j ein?” Wer SBOMs hatte, beantwortete das in Minuten. Alle anderen suchten wochenlang.

Eine SBOM allein ist aber nur eine Momentaufnahme. Wertvoll wird sie, wenn ein System sie dauerhaft gegen neue Schwachstellenmeldungen abgleicht. Genau das macht Dependency-Track.

  Quellcode            Build                 Registry
 +-----------+      +-----------+          +------------------+
 | demo-app  |----->|  Image    |--------->| reg-build:5000   |
 | req.txt   |      +-----+-----+          | Image + SBOM-    |
 +-----+-----+            |                | Attestation      |
       |                  | syft           +------------------+
       | syft             v
       v           +--------------+  grype   +--------------------+
  Quell-SBOM       | Image-SBOM   |--------->| einmaliger Befund  |
  (direkte Abh.)   | CycloneDX    |          +--------------------+
                   | SPDX         |  API     +--------------------+
                   +--------------+--------->| Dependency-Track   |
                                             | laufend: CVEs,     |
                                             | Lizenzen, Policies |
                                             +--------------------+

Die Konzepte in einfach

Was steht in einer SBOM?

Eine SBOM ist eine maschinenlesbare Liste von Komponenten mit Zusatzinformationen. Die US-Behörde NTIA hat 2021 Mindestinhalte (Minimum Elements) definiert, die bis heute als Richtschnur gelten:

Feld Bedeutung Beispiel
Lieferant wer die Komponente herausgibt Python Software Foundation
Name Name der Komponente requests
Version genaue Version 2.25.0
Eindeutige ID maschinenlesbare Kennung PURL, CPE
Beziehung wer hängt von wem ab demo-app → requests
Autor der SBOM wer die Liste erstellt hat Syft in CI
Zeitstempel wann erstellt 2026-10-08T10:15:00Z

Dazu kommen oft Lizenzen, Prüfsummen (Hashes) und Herkunftsangaben.

CycloneDX und SPDX

Es gibt zwei etablierte Formate. Beide sind offen, beide werden von allen wichtigen Werkzeugen unterstützt.

Merkmal CycloneDX SPDX
Herkunft OWASP, als ECMA-424 standardisiert Linux Foundation, ISO/IEC 5962
Ursprünglicher Fokus Sicherheit, Schwachstellen Lizenz-Compliance
Versionen (Stand Buch) 1.6 (verbreitet), 1.7 2.3 (verbreitet), 3.0
Dateiformate JSON, XML, Protobuf JSON, Tag-Value, YAML, RDF
VEX eingebaut über OpenVEX / SPDX 3
Dependency-Track ja nein (4.x)

Praktisch heißt das: Für Sicherheitsanalysen und Dependency-Track nimmst du CycloneDX. Fordert ein Kunde oder Prüfer SPDX (häufig bei Lizenz-Audits), erzeugst du aus demselben Scan einfach beide Formate. Syft kann das in einem Durchlauf.

PURL und CPE: Wie heißt eine Komponente eindeutig?

Der Name requests allein ist mehrdeutig. Es gibt ein Python-Paket, aber auch npm-Pakete mit diesem Namen. Deshalb braucht jede Komponente eine eindeutige Kennung.

Die PURL (Package URL) beschreibt ein Paket so, wie es im Paket-Ökosystem heißt:

pkg:pypi/[email protected]
pkg:deb/debian/[email protected]~deb12u1?arch=amd64&distro=debian-12
pkg:oci/demo-app@sha256%3Aabc123...?repository_url=reg-build%3A5000

Aufbau: pkg:<typ>/<namespace>/<name>@<version>?<qualifier>. PURLs sind das wichtigste Bindeglied zu Schwachstellen-Datenbanken wie OSV und GitHub Advisories.

Die CPE (Common Platform Enumeration) ist älter und stammt aus der NVD, der US-Schwachstellendatenbank:

cpe:2.3:a:python:requests:2.25.0:*:*:*:*:*:*:*

CPEs benennen Hersteller und Produkt so, wie die NVD sie führt. Das passt oft schlecht zu Paketnamen und führt zu Fehltreffern. Syft erzeugt CPEs deshalb nur geraten. Wo möglich, sind PURL-basierte Abgleiche genauer.

Direkte und transitive Abhängigkeiten

In requirements.txt der demo-app stehen drei Pakete: flask, gunicorn, requests. Das sind die direkten Abhängigkeiten. Flask braucht aber selbst werkzeug, jinja2, click und weitere. requests braucht urllib3, idna, certifi und chardet. Das sind transitive Abhängigkeiten, also Abhängigkeiten von Abhängigkeiten.

demo-app
 +-- flask 3.0.3
 |    +-- werkzeug, jinja2 (+ markupsafe), click, itsdangerous, blinker
 +-- gunicorn 22.0.0
 |    +-- packaging
 +-- requests 2.25.0
      +-- urllib3, idna, certifi, chardet

Die meisten Schwachstellen stecken in transitiven Abhängigkeiten. Niemand hat sie bewusst ausgewählt, und oft weiß niemand, dass sie da sind.

Quell-SBOM und Image-SBOM

Wo du scannst, bestimmt, was du siehst:

Art Quelle Sieht Sieht nicht
Quell-SBOM Repo, Manifeste, Lockfiles was deklariert ist OS-Pakete, ungelockte Transitive
Image-SBOM fertiges Container-Image was wirklich installiert ist Herkunft im Quellcode

Ohne Lockfile kennt Syft im Quellverzeichnis nur die drei Zeilen aus requirements.txt. Im Image findet es die tatsächlich installierten Python-Pakete samt aller transitiven sowie die Debian-Pakete des Basis-Images. Für die Frage „Was läuft in Produktion?” zählt die Image-SBOM. Die Quell-SBOM ist früher verfügbar und hilft Entwicklern.

Tipp: Mit einem Lockfile (etwa pip-compile aus pip-tools, poetry.lock oder uv.lock) wird auch die Quell-SBOM vollständig. Feste Versionen inklusive Hashes sind ohnehin Teil eines reproduzierbaren Builds (siehe Kapitel 2).

VEX: „Betrifft uns das?”

Ein Scanner meldet: „requests 2.25.0 hat CVE-2023-32681.” Ob deine Anwendung dadurch wirklich angreifbar ist, weiß der Scanner nicht. Vielleicht nutzt sie gar keinen Proxy, und genau dort steckt die Lücke.

VEX (Vulnerability Exploitability eXchange) ist eine maschinenlesbare Aussage des Herstellers zu einer Schwachstelle in einem Produkt. Es gibt vier Zustände:

Status Bedeutung
not_affected Komponente enthalten, aber nicht ausnutzbar (mit Begründung)
affected ausnutzbar, Maßnahme nötig
fixed in dieser Version behoben
under_investigation wird noch geprüft

VEX gibt es als Teil von CycloneDX, als eigenständiges OpenVEX-Format und in CSAF. Scanner wie Grype und Trivy können VEX-Dateien einlesen und unterdrücken dann die als not_affected markierten Befunde. Wie du Befunde begründet bewertest, vertieft Kapitel 8.

Lizenzen

Jede Komponente steht unter einer Lizenz. Für SBOMs werden Lizenzen als SPDX-Lizenz-IDs angegeben, etwa MIT, Apache-2.0, BSD-3-Clause oder GPL-2.0-only. Kombinationen schreibt man als Ausdruck: MIT OR Apache-2.0. Für die Praxis wichtig ist die Einteilung:

  • Freizügige Lizenzen (MIT, BSD, Apache): kaum Pflichten außer Namensnennung.
  • Copyleft-Lizenzen (GPL, AGPL): Wer verändert verbreitet, muss den Quellcode offenlegen. Bei AGPL gilt das auch für Netzdienste.

In Container-Images steckt fast immer GPL-Software aus dem Betriebssystem. Das ist meist unproblematisch, solange du sie nur nutzt. Eine Lizenz-Policy sollte das unterscheiden können.

Regulatorischer Kontext

SBOMs werden zur Pflicht. Drei Regelwerke solltest du kennen:

  • US Executive Order 14028 (Mai 2021): verpflichtete Lieferanten der US-Bundesbehörden, SBOMs bereitzustellen. Sie hat das Thema weltweit angestoßen.
  • EU Cyber Resilience Act (CRA, Verordnung (EU) 2024/2847): gilt für Produkte mit digitalen Elementen auf dem EU-Markt. Hersteller müssen Komponenten erfassen und eine SBOM in einem gängigen, maschinenlesbaren Format erstellen, mindestens für die oberste Ebene der Abhängigkeiten. Die SBOM muss nicht veröffentlicht, aber Marktaufsichtsbehörden auf Verlangen vorgelegt werden. Die Meldepflichten für aktiv ausgenutzte Schwachstellen gelten ab September 2026, die übrigen Pflichten ab Dezember 2027.
  • BSI TR-03183 (Technische Richtlinie „Cyber-Resilienz-Anforderungen an Hersteller und Produkte”): Teil 2 beschreibt konkret, was eine SBOM enthalten soll, etwa CycloneDX oder SPDX in festgelegten Mindestversionen, vollständige transitive Abhängigkeiten, Lizenzen und Hashes. Prüfe die jeweils aktuelle Fassung, da die Mindestversionen angehoben werden.

Merke: Rechtlich verlangt der CRA nur die oberste Ebene. Technisch sinnvoll und nach BSI TR-03183 gefordert ist die vollständige Liste. Eine Image-SBOM aus Syft erfüllt das fast von selbst.

Hands-on-Lab: Von der Zutatenliste zur laufenden Überwachung

Du arbeitest in ~/seclab/kap07. Voraussetzungen: reg-build läuft auf localhost:5001, das Image localhost:5001/demo-app:1.0.0 ist dort gepusht (Kapitel 0/1), das Cosign-Schlüsselpaar aus Kapitel 5 liegt in ~/seclab/kap05/.

Schritt 1: Vorbereitung

mkdir -p ~/seclab/kap07 && cd ~/seclab/kap07
syft version | grep -E '^Version'
grype version | grep -E '^Version'
DIGEST=$(crane digest localhost:5001/demo-app:1.0.0)
IMAGE="localhost:5001/demo-app@${DIGEST}"
echo "$IMAGE"

Erwartung: Versionsangaben für Syft (1.x) und Grype (0.x) und eine Zeile wie localhost:5001/demo-app@sha256:4f2a.... Wie in allen Kapiteln arbeitest du mit dem Digest, damit die SBOM eindeutig zu genau diesem Image gehört.

Schritt 2: Quell-SBOM aus dem demo-app-Verzeichnis

syft dir:$HOME/seclab/demo-app -o cyclonedx-json=sbom-src.cdx.json
jq -r '.components[] | "\(.name) \(.version)"' sbom-src.cdx.json

Erwartete Ausgabe:

flask 3.0.3
gunicorn 22.0.0
requests 2.25.0

Mehr steht in requirements.txt nicht. Syft hat nur gelesen, was deklariert ist. Transitive Abhängigkeiten fehlen, weil es kein Lockfile gibt.

Schritt 3: Image-SBOM in zwei Formaten

syft "$IMAGE" \
  -o cyclonedx-json=sbom.cdx.json \
  -o spdx-json=sbom.spdx.json \
  -o table
ls -lh sbom.*.json

Erwartung: Syft zeigt eine Tabelle mit Spalten NAME, VERSION, TYPE (etwa python, deb, binary) auf dem Bildschirm und schreibt die beiden Dateien. Mehrere -o-Angaben mit =datei erzeugen alle Formate aus einem einzigen Scan.

Tipp: Liegt das Image auch im lokalen Docker-Daemon, liest Syft es eventuell von dort. Mit dem Präfix registry: erzwingst du das Laden aus der Registry: syft registry:$IMAGE .... Für HTTP-Registries außerhalb von localhost brauchst du SYFT_REGISTRY_INSECURE_USE_HTTP=true.

Schritt 4: Die SBOM mit jq untersuchen

Eine SBOM ist JSON. Mit jq beantwortest du Fragen direkt:

# Wie viele Komponenten insgesamt?
jq '.components | length' sbom.cdx.json
# Aufgeteilt nach Paket-Typ (aus der PURL)
jq -r '.components[].purl // "ohne-purl"' sbom.cdx.json \
  | cut -d/ -f1 | sort | uniq -c

Erwartung: insgesamt typischerweise 100 bis 150 Komponenten (abhängig vom Basis-Image), davon etwa 80 bis 100 pkg:deb, gut ein Dutzend pkg:pypi und einige pkg:generic (zum Beispiel der Python-Interpreter selbst).

# Welche requests-Version steckt im Image?
jq '.components[] | select(.name=="requests") | {name, version, purl}' sbom.cdx.json
{
  "name": "requests",
  "version": "2.25.0",
  "purl": "pkg:pypi/[email protected]"
}

Dieselbe Frage im SPDX-Format. Die Struktur ist anders, die Antwort gleich:

jq '.packages | length' sbom.spdx.json
jq -r '.packages[] | select(.name=="requests") | .versionInfo' sbom.spdx.json

Nun der Vergleich Quelle gegen Image. Welche Python-Pakete gibt es nur im Image?

jq -r '.components[] | select((.purl // "") | startswith("pkg:pypi")) | .name' \
  sbom.cdx.json | sort > image-py.txt
jq -r '.components[].name' sbom-src.cdx.json | sort > src-py.txt
comm -13 src-py.txt image-py.txt

Erwartung: eine Liste wie blinker, certifi, chardet, click, idna, itsdangerous, jinja2, markupsafe, packaging, urllib3, werkzeug (eventuell auch pip, setuptools, wheel). Das sind die transitiven Abhängigkeiten, die in keiner Datei deines Repos stehen.

Zum Schluss ein Blick auf Lizenzen:

jq -r '.components[]
  | [.name, (.licenses[0].license.id // .licenses[0].license.name
             // .licenses[0].expression // "-")] | @tsv' sbom.cdx.json \
  | sort -k2 | head -20

Erwartung: Paare aus Name und Lizenz, etwa flask BSD-3-Clause oder Debian-Pakete mit GPL-2.0-only. Einige Einträge haben -, weil keine Lizenz erkannt wurde. Auch das ist ein Befund.

Schritt 5: Schwachstellen aus der SBOM prüfen

Grype kann statt eines Images direkt eine SBOM lesen. Das ist schnell und funktioniert auch dort, wo das Image selbst nicht verfügbar ist, etwa in einer anderen Sicherheitszone (siehe Kapitel 4):

grype sbom:./sbom.cdx.json --only-fixed
grype sbom:./sbom.cdx.json -o json \
  | jq -r '.matches[] | select(.artifact.name=="requests")
           | "\(.vulnerability.id) \(.vulnerability.severity)"' | sort -u

Erwartete Ausgabe (Auszug, die Liste wächst mit der Zeit):

NAME      INSTALLED  FIXED-IN  TYPE    VULNERABILITY        SEVERITY
requests  2.25.0     2.31.0    python  GHSA-j8r2-6x86-q33q  Medium
requests  2.25.0     2.32.0    python  GHSA-9wx4-h78v-vm56  Medium
urllib3   1.26.x     ...       python  GHSA-...             Medium
...

Neuere Grype-Versionen zeigen zusätzliche Spalten wie EPSS oder RISK. GHSA-j8r2-6x86-q33q entspricht CVE-2023-32681 (Weitergabe von Proxy-Zugangsdaten). Die zweite jq-Abfrage listet alle Kennungen nur für requests. Grype nutzt die PURLs aus der SBOM, um passende Einträge in seiner Datenbank zu finden.

Merke: Die SBOM wird einmal erzeugt, der Abgleich kann beliebig oft wiederholt werden. Morgen kann dieselbe SBOM neue Befunde liefern, ohne dass sich am Image etwas geändert hat.

Schritt 6: Die SBOM als Attestation ans Image hängen

Eine SBOM, die irgendwo als Datei liegt, beweist nichts. Wer sagt, dass sie zu genau diesem Image gehört und nicht verändert wurde? Die Lösung kennst du aus Kapitel 5: Du signierst die SBOM als Attestation (signierte Aussage) und legst sie neben dem Image in der Registry ab.

cosign attest --key ~/seclab/kap05/cosign.key \
  --type cyclonedx --predicate sbom.cdx.json \
  --tlog-upload=false "$IMAGE"

Erwartung: Nach Eingabe des Schlüssel-Passworts meldet Cosign, dass die Attestation in die Registry geschrieben wurde. Mit crane ls localhost:5001/demo-app siehst du einen neuen Tag der Form sha256-....att.

Prüfen und auslesen:

cosign verify-attestation --key ~/seclab/kap05/cosign.pub \
  --type cyclonedx --insecure-ignore-tlog=true "$IMAGE" \
  | jq -r '.payload' | base64 --decode \
  | jq '{predicateType, komponenten: (.predicate.components | length)}'

Erwartung: "predicateType": "https://cyclonedx.org/bom" und dieselbe Komponentenzahl wie in Schritt 4. Davor meldet Cosign auf stderr, dass die Signatur gegen den Schlüssel geprüft wurde.

Achtung: Bei cosign v3 ändern sich einige Standardwerte. Falls attest oder verify-attestation Fehler zu Signing-Config oder Transparenzlog melden, hilft --use-signing-config=false. Prüfe im Zweifel cosign attest --help.

In Kapitel 9 lässt du Kyverno genau diese Attestation bei der Bereitstellung prüfen: kein Image ohne signierte SBOM.

Schritt 7: Dependency-Track starten

Dependency-Track besteht aus einem API-Server (Java, mit eingebetteter H2-Datenbank für den Lab-Betrieb) und einem Web-Frontend. Lege eine Compose-Datei an:

cat > docker-compose.yml <<'EOF'
services:
  dtrack-apiserver:
    image: dependencytrack/apiserver:latest
    mem_limit: 6g
    ports:
      - "8080:8080"
    volumes:
      - dtrack-data:/data
    restart: unless-stopped
  dtrack-frontend:
    image: dependencytrack/frontend:latest
    depends_on:
      - dtrack-apiserver
    environment:
      API_BASE_URL: "http://localhost:8080"
    ports:
      - "8088:8080"
    restart: unless-stopped
volumes:
  dtrack-data: {}
EOF
docker compose up -d
docker compose logs -f dtrack-apiserver

Warte, bis im Log eine Zeile mit Dependency-Track is ready oder Started erscheint. Der erste Start dauert einige Minuten. Beende die Log-Ansicht mit Strg+C und prüfe:

curl -s http://localhost:8080/api/version | jq '{application, version}'

Erwartung: "application": "Dependency-Track" und die Versionsnummer, etwa 4.x.

Achtung: Der API-Server ist speicherhungrig. Das Projekt nennt mindestens 4,5 GB RAM, empfohlen sind 16 GB. Mit mem_limit: 6g läuft das Lab stabil, wenn Docker insgesamt mindestens 8 GB hat. Stoppe vorher große Container aus anderen Kapiteln (GitLab, Nexus).

Sicherheit: latest ist hier nur Bequemlichkeit fürs Lab. Ermittle mit crane digest dependencytrack/apiserver:latest den Digest und trage image@sha256:... ein. In einer echten Umgebung beziehst du beide Images aus deiner Spiegel-Registry (siehe Kapitel 3).

Schritt 8: Erstanmeldung, Datenquellen und API-Key

Öffne http://localhost:8088. Melde dich mit admin / admin an. Du musst sofort ein neues Passwort setzen. Wähle ein Lab-Passwort und notiere es.

Datenquellen. Dependency-Track lädt beim ersten Start die NVD-Daten. Das kann ohne NVD-API-Key lange dauern. Für Python-Pakete ist die OSV-Datenbank schneller und genauer:

  1. Administration → Vulnerability Sources → Google OSV Advisories.
  2. Aktivieren und das Ökosystem PyPI auswählen (zusätzlich Debian für die Betriebssystem-Pakete).
  3. Speichern. Der Abgleich läuft im Hintergrund.

API-Key. Pipelines melden sich mit einem API-Key an, nie mit einem Benutzerkonto:

  1. Administration → Access Management → Teams → Team Automation öffnen.
  2. Unter Permissions prüfen bzw. ergänzen: BOM_UPLOAD, PROJECT_CREATION_UPLOAD, VIEW_PORTFOLIO, VIEW_VULNERABILITY, VIEW_POLICY_VIOLATION.
  3. Unter API Keys mit dem Plus-Symbol einen Schlüssel erzeugen und kopieren.
read -rs DT_API_KEY && export DT_API_KEY
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "X-Api-Key: $DT_API_KEY" http://localhost:8080/api/v1/project

Erwartung: 200. Mit read -rs landet der Schlüssel nicht in der Shell-Historie. Ein 401 bedeutet falscher Schlüssel, ein 403 fehlende Berechtigung.

Schritt 9: SBOM per API hochladen

curl -sS -X POST http://localhost:8080/api/v1/bom \
  -H "X-Api-Key: $DT_API_KEY" \
  -F "autoCreate=true" \
  -F "projectName=demo-app" \
  -F "projectVersion=1.0.0" \
  -F "[email protected]" | tee upload.json

Erwartete Ausgabe:

{"token":"9b3c1e8a-5d2f-4c71-a0e4-2f6b9d1c7e55"}

autoCreate=true legt das Projekt an, falls es noch nicht existiert. Dafür ist die Berechtigung PROJECT_CREATION_UPLOAD nötig. Die Verarbeitung läuft asynchron. Mit dem Token fragst du den Stand ab:

TOKEN=$(jq -r .token upload.json)
curl -s -H "X-Api-Key: $DT_API_KEY" \
  http://localhost:8080/api/v1/bom/token/$TOKEN

Erwartung: zuerst {"processing":true}, nach einigen Sekunden {"processing":false}.

Merke: Lade die CycloneDX-Datei hoch, nicht die SPDX-Datei. Dependency-Track 4.x verarbeitet nur CycloneDX.

Schritt 10: Befunde ansehen

Im Frontend findest du unter Projects das Projekt demo-app in Version 1.0.0. Die Reiter Components, Audit Vulnerabilities und Policy Violations zeigen den Stand. Unter Components kannst du nach requests suchen und siehst die zugeordneten Schwachstellen.

Dasselbe per API, so wie es eine Pipeline tun würde:

UUID=$(curl -s -H "X-Api-Key: $DT_API_KEY" \
  "http://localhost:8080/api/v1/project/lookup?name=demo-app&version=1.0.0" \
  | jq -r .uuid)
curl -s -H "X-Api-Key: $DT_API_KEY" \
  http://localhost:8080/api/v1/finding/project/$UUID \
  | jq -r '.[] | [.component.name, .component.version,
                  .vulnerability.vulnId, .vulnerability.severity] | @tsv' \
  | sort -u | head -20

Erwartung: Zeilen wie requests 2.25.0 GHSA-j8r2-6x86-q33q MEDIUM. Ist die Liste leer, läuft der Abgleich mit den Datenquellen noch. Warte einige Minuten und löse die Analyse im Projekt über Reanalyze erneut aus.

Die Kennzahlen für ein Dashboard:

curl -s -H "X-Api-Key: $DT_API_KEY" \
  http://localhost:8080/api/v1/metrics/project/$UUID/current \
  | jq '{critical, high, medium, low, policyViolationsTotal}'

Der entscheidende Unterschied zu Grype in Schritt 5: Dependency-Track behält die SBOM und gleicht sie regelmäßig neu ab. Wird morgen eine Lücke in werkzeug bekannt, erscheint sie im Projekt, ohne dass jemand die Pipeline startet. Über Notifications kannst du dafür Benachrichtigungen per Webhook, E-Mail oder Chat einrichten.

Unter Audit Vulnerabilities kannst du jeden Befund bewerten (Analysis State wie NOT_AFFECTED, EXPLOITABLE, FALSE_POSITIVE) und begründen. Diese Bewertungen kann Dependency-Track als CycloneDX-VEX exportieren.

Schritt 11: Policies anlegen

Policies machen aus Befunden Regeln. Lege zwei an, im Frontend unter Policy Management:

Policy 1: Sicherheit

  1. Create Policy, Name Keine hohen oder kritischen Schwachstellen.
  2. Operator: Any, Violation State: Fail.
  3. Bedingungen hinzufügen: Severity is Critical und Severity is High.

Policy 2: Lizenzen

  1. Create Policy, Name Copyleft prüfen.
  2. Operator: Any, Violation State: Warn.
  3. Bedingung: License Group is Copyleft (eine der mitgelieferten Lizenzgruppen).

Policies gelten zunächst für alle Projekte. Über Projects in der Policy kannst du sie auf bestimmte Projekte oder Tags beschränken.

Die Policy-Auswertung läuft bei jedem Upload und jeder Analyse. Lade die SBOM erneut hoch (Schritt 9) und frage die Verstöße ab:

curl -s -H "X-Api-Key: $DT_API_KEY" \
  http://localhost:8080/api/v1/violation/project/$UUID \
  | jq -r '.[] | [.policyCondition.policy.violationState,
                  .policyCondition.policy.name, .component.name] | @tsv' \
  | sort | uniq -c | sort -rn | head

Erwartung: Verstöße mit WARN für Copyleft prüfen bei Debian-Paketen unter GPL. Ob FAIL-Verstöße der Sicherheits-Policy auftauchen, hängt davon ab, welche hohen Schwachstellen das Basis-Image gerade hat. Fehlen sie, ist das ein gutes Zeichen für das Image, nicht für die Policy. Ändere zum Testen die Bedingung auf Severity is Medium, dann schlägt requests an.

Policies lassen sich auch per API anlegen (Berechtigung POLICY_MANAGEMENT). Das ist der Weg, um sie als Code in Git zu verwalten:

POLICY=$(curl -s -X PUT http://localhost:8080/api/v1/policy \
  -H "X-Api-Key: $DT_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Keine kritischen (API)","operator":"ANY","violationState":"FAIL"}' \
  | jq -r .uuid)
curl -s -X PUT http://localhost:8080/api/v1/policy/$POLICY/condition \
  -H "X-Api-Key: $DT_API_KEY" -H "Content-Type: application/json" \
  -d '{"subject":"SEVERITY","operator":"IS","value":"CRITICAL"}' | jq .uuid

Erwartung: eine UUID für die neue Bedingung. Dafür musst du dem Team Automation vorher die Berechtigung POLICY_MANAGEMENT geben. In der Praxis nimmst du für Verwaltungsaufgaben einen eigenen Schlüssel mit eigenem Team.

Schritt 12: Upload in die Pipeline integrieren

Für GitLab CI brauchst du ein Werkzeug-Image mit syft, curl und jq. Das offizielle Syft-Image enthält nur die Binärdatei ohne Shell. Baue dir daher ein kleines Werkzeug-Image (zum Bauen von Images siehe Kapitel 1 und 2). Speichere den folgenden Inhalt als ~/seclab/kap07/Dockerfile.tools:

FROM alpine:3.20
RUN apk add --no-cache curl jq ca-certificates
COPY --from=anchore/syft:v1.18.0 /syft /usr/local/bin/syft
USER 10001
docker build -t localhost:5001/tools/sbom:1.0.0 - < Dockerfile.tools
docker push localhost:5001/tools/sbom:1.0.0

Erwartung: Der Push meldet einen Digest. Der Job in der .gitlab-ci.yml der demo-app:

variables:
  DT_URL: "http://dtrack-apiserver.example.internal:8080"
  # DT_API_KEY: als maskierte, geschützte CI/CD-Variable oder aus Vault
  SYFT_REGISTRY_INSECURE_USE_HTTP: "true"   # reg-build spricht nur HTTP (Lab)

sbom:
  stage: build
  image: reg-build:5000/tools/sbom:1.0.0
  needs: ["build"]
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH   # wie der Job build
  script:
    - IMAGE_REF="${IMAGE_NAME}@$(cat image-digest.txt)"
    - syft "registry:${IMAGE_REF}" -o cyclonedx-json=sbom.cdx.json
        -o spdx-json=sbom.spdx.json
    - >
      curl -sS --fail-with-body -X POST "${DT_URL}/api/v1/bom"
      -H "X-Api-Key: ${DT_API_KEY}"
      -F "autoCreate=true"
      -F "projectName=${CI_PROJECT_NAME}"
      -F "projectVersion=${CI_COMMIT_REF_NAME}"
      -F "[email protected]"
      | tee dt-upload.json
  artifacts:
    paths: [sbom.cdx.json, sbom.spdx.json, dt-upload.json]
    expire_in: 90 days

Dazu einige Erläuterungen:

  • IMAGE_NAME ist die Variable aus der Pipeline in Kapitel 1. Den Digest liest der Job aus image-digest.txt, dem Artefakt des Jobs build; needs: ["build"] lädt es automatisch herunter. IMAGE_REF enthält damit das Image mit Digest, syft arbeitet also nie mit einem beweglichen Tag.
  • stage: build mit needs auf einen Job derselben Stage ist seit GitLab 14.2 erlaubt. Die Regel übernimmt die Bedingung des Jobs build, der nur auf dem Standard-Branch läuft; sonst fehlt der Job, auf den needs zeigt.
  • --fail-with-body (curl ab 7.76) lässt den Job bei HTTP-Fehlern scheitern und zeigt trotzdem die Antwort. Ältere curl-Versionen nutzen --fail.
  • projectVersion aus dem Branch- oder Tag-Namen ergibt in Dependency-Track pro Release ein eigenes Projekt. Für Tags ist das genau richtig.
  • Den API-Key holst du am besten wie in Kapitel 6 per id_tokens aus Vault, statt ihn als CI-Variable zu speichern.

Soll der Job bei Policy-Verstößen scheitern, wartest du das Ende der Verarbeitung ab und wertest die Verstöße aus:

sbom-gate:
  stage: build
  image: reg-build:5000/tools/sbom:1.0.0
  needs: ["sbom"]
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - TOKEN=$(jq -r .token dt-upload.json)
    - |
      for i in $(seq 1 30); do
        curl -s -H "X-Api-Key: ${DT_API_KEY}" \
          "${DT_URL}/api/v1/bom/token/${TOKEN}" | grep -q '"processing":false' && break
        sleep 10
      done
    - Q="name=${CI_PROJECT_NAME}&version=${CI_COMMIT_REF_NAME}"
    - 'H="X-Api-Key: ${DT_API_KEY}"'
    - >
      UUID=$(curl -s -H "$H" "${DT_URL}/api/v1/project/lookup?${Q}"
      | jq -r .uuid)
    - >
      FAILS=$(curl -s -H "$H" "${DT_URL}/api/v1/violation/project/${UUID}"
      | jq '[.[] | select(.policyCondition.policy.violationState=="FAIL")]
      | length')
    - echo "FAIL-Verstoesse: ${FAILS}"
    - test "${FAILS}" -eq 0

Tipp: Statt eigener Skripte gibt es fertige Uploader wie die CycloneDX-CLI oder Plugins für Jenkins. Das kleine curl-Skript hat aber den Vorteil, dass du genau siehst, was passiert, und keine weitere Abhängigkeit in die Pipeline holst.

Wie streng ein solches Gate sein soll und wie du mit berechtigten Ausnahmen umgehst, behandeln Kapitel 8 und Kapitel 10.

Schritt 13: Aufräumen

cd ~/seclab/kap07
docker compose down
docker compose down -v   # nur, wenn du die Daten nicht mehr brauchst
docker ps --filter name=dtrack

Erwartung: Die letzte Ausgabe zeigt keine laufenden dtrack-Container mehr. Mit -v löschst du auch das Volume mit Datenbank und Schwachstellendaten. Das spart Platz, kostet beim nächsten Start aber wieder den kompletten Erstabgleich. Die SBOM-Dateien und die Attestation in reg-build bleiben erhalten. Du brauchst sie in Kapitel 9 und 11.

Fortschritt speichern? Kostenlos registrieren

Typische Stolperfallen

Symptom Ursache Lösung
Quell-SBOM hat nur 3 Pakete kein Lockfile Lockfile erzeugen oder Image scannen
Upload: HTTP 401 API-Key falsch oder Header vertippt X-Api-Key prüfen
Upload: HTTP 403 Team fehlt BOM_UPLOAD / PROJECT_CREATION_UPLOAD Rechte des Teams ergänzen
Upload ok, Projekt leer SPDX statt CycloneDX hochgeladen sbom.cdx.json verwenden
Keine Schwachstellen in DT Datenquellen noch nicht geladen OSV aktivieren, warten, Reanalyze
API-Server startet neu (OOM) zu wenig RAM für Docker mem_limit erhöhen, andere Container stoppen
Frontend lädt, zeigt keine Daten API_BASE_URL falsch Browser-Sicht: http://localhost:8080
syft: http: server gave HTTP response HTTP-Registry nicht als unsicher markiert SYFT_REGISTRY_INSECURE_USE_HTTP=true
Viele Fehltreffer bei OS-Paketen CPE-Abgleich ungenau PURL-basierte Quellen bevorzugen, VEX

Übung: Upgrade mit Nachweis

Ein Entwickler behauptet: „Ich habe requests auf 2.32.3 aktualisiert, damit sind die Lücken weg.” Überprüfe das mit SBOM und Dependency-Track:

  1. Erhöhe in ~/seclab/demo-app/requirements.txt die Version von requests auf 2.32.3, baue das Image als localhost:5001/demo-app:1.0.1 und pushe es.
  2. Erzeuge eine CycloneDX-SBOM für das neue Image (per Digest).
  3. Zeige mit jq, welche Komponenten sich zwischen 1.0.0 und 1.0.1 in Name oder Version unterscheiden.
  4. Lade die SBOM als Projektversion 1.0.1 in Dependency-Track hoch und vergleiche die Zahl der Befunde beider Versionen über die Metrics-API.

Hinweis 1

Für den Vergleich in Punkt 3 erzeugst du aus beiden SBOMs eine sortierte Liste der Form name@version (am einfachsten aus dem Feld purl, aber nur für pkg:pypi). Das Werkzeug diff oder comm zeigt dir dann die Unterschiede.

Hinweis 2

Achte auf die transitiven Pakete. Neuere requests-Versionen verlangen eine neuere urllib3-Hauptversion und charset-normalizer statt chardet. In der Liste sollten deshalb mehr als nur eine Zeile auftauchen. Für Punkt 4 brauchst du pro Version die Projekt-UUID über /api/v1/project/lookup.

Lösung

cd ~/seclab/demo-app
sed -i.bak 's/^requests==.*/requests==2.32.3/' requirements.txt
docker build -t localhost:5001/demo-app:1.0.1 .
docker push localhost:5001/demo-app:1.0.1

cd ~/seclab/kap07
D2=$(crane digest localhost:5001/demo-app:1.0.1)
syft "localhost:5001/demo-app@${D2}" -o cyclonedx-json=sbom-1.0.1.cdx.json

for f in sbom.cdx.json sbom-1.0.1.cdx.json; do
  jq -r '.components[].purl // empty | select(startswith("pkg:pypi"))' "$f" \
    | sort > "${f%.cdx.json}.purls"
done
diff sbom.purls sbom-1.0.1.purls

Erwartete Ausgabe (sinngemäß):

< pkg:pypi/[email protected]
< pkg:pypi/[email protected]
< pkg:pypi/[email protected]
< pkg:pypi/[email protected]
---
> pkg:pypi/[email protected]
> pkg:pypi/[email protected]
> pkg:pypi/[email protected]
> pkg:pypi/[email protected]

Die genauen Versionen von urllib3, idna und charset-normalizer hängen vom Zeitpunkt des Builds ab, weil sie nicht gepinnt sind. Genau das ist ein weiteres Argument für ein Lockfile.

Upload und Vergleich:

curl -sS -X POST http://localhost:8080/api/v1/bom -H "X-Api-Key: $DT_API_KEY" \
  -F autoCreate=true -F projectName=demo-app -F projectVersion=1.0.1 \
  -F "[email protected]"
sleep 30
for v in 1.0.0 1.0.1; do
  U=$(curl -s -H "X-Api-Key: $DT_API_KEY" \
    "http://localhost:8080/api/v1/project/lookup?name=demo-app&version=$v" \
    | jq -r .uuid)
  echo -n "$v: "
  curl -s -H "X-Api-Key: $DT_API_KEY" \
    http://localhost:8080/api/v1/metrics/project/$U/current \
    | jq -c '{high, medium, low}'
done

Erwartung: Version 1.0.1 hat weniger Befunde, die requests-Befunde sind verschwunden. Liefern die Metriken noch null, löse im Frontend Reanalyze aus und warte kurz. Die Antwort an den Entwickler lautet also: „Stimmt, und hier ist der Nachweis.” Die übrigen Befunde stammen meist aus dem Basis-Image. Mit git checkout requirements.txt oder der .bak-Datei stellst du den Ausgangszustand wieder her, denn spätere Kapitel brauchen die verwundbare Version.

Fortschritt speichern? Kostenlos registrieren

Aus der Praxis

SBOM pro Release, nicht pro Commit. In Dependency-Track entsteht pro projectVersion ein Projekt. Wer bei jedem Feature-Branch-Commit hochlädt, hat bald tausende Projekte und ein unbrauchbares Portfolio. Bewährt hat sich: Upload nur für Tags und den Hauptzweig. Bei main nimmst du eine feste Version wie main oder snapshot, die bei jedem Upload überschrieben wird. Ab Dependency-Track 4.12 kannst du Versionen als „latest” markieren und alte Versionen deaktivieren, damit sie die Kennzahlen nicht verfälschen.

Was läuft wirklich? Das wichtigste Ziel ist eine Antwort auf die Log4Shell-Frage: „Wo läuft Komponente X in Version Y?” Dafür müssen die Projekte in Dependency-Track mit dem verknüpft sein, was wirklich ausgerollt ist. In der Praxis werden Projekte mit Tags wie env:prod versehen oder aus dem GitOps-Repository (Argo CD, Flux, siehe Kapitel 1) heraus aktualisiert. Die Suche über Components zeigt dann portfolioweit, wo eine Komponente steckt.

Zonengrenzen und air-gapped. Die SBOM reist als signierte Attestation mit dem Image über die Zonengrenze (siehe Kapitel 4). In der Zielzone prüft die Freigabestelle die Signatur und lädt die SBOM in eine eigene Dependency-Track-Instanz. Diese bekommt ihre Schwachstellendaten über einen gespiegelten Feed. Dependency-Track unterstützt dafür das Spiegeln von NVD- und OSV-Daten über eigene URLs. Plane dafür einen regelmäßigen, kontrollierten Import-Prozess ein, sonst überwacht die Instanz gegen veraltete Daten.

Betrieb. Für den Dauerbetrieb ersetzt du die eingebettete H2-Datenbank durch PostgreSQL. H2 ist nur für Tests gedacht. Sichere die Datenbank regelmäßig, denn sie enthält die Audit-Entscheidungen der Teams. Diese sind das eigentliche Wissen und lassen sich nicht neu erzeugen. Dependency-Track liefert Prometheus-Metriken, wenn du sie per Konfiguration einschaltest. Überwache Warteschlangen, letzte erfolgreiche Spiegelung der Datenquellen und Speicherverbrauch. Einen bevorstehenden großen Versionssprung (Version 5 mit neuer Architektur) solltest du im Auge behalten und vorher testen.

Rechte und Verantwortung. Jedes Team sieht sein Portfolio, Sicherheitsverantwortliche sehen alles. Dependency-Track kann Benutzer über OIDC oder LDAP anbinden. Pipeline-Schlüssel gehören zu eigenen Teams mit minimalen Rechten. Ein geleakter Upload-Schlüssel ist ärgerlich, ein geleakter Admin-Schlüssel erlaubt das Abschalten aller Policies.

SBOMs von Lieferanten. Der CRA und Ausschreibungen von Behörden verlangen zunehmend SBOMs für eingekaufte Software. Dependency-Track kann auch fremde CycloneDX-SBOMs aufnehmen. Lege dafür eigene Projekte pro Lieferprodukt an und prüfe die Qualität eingehender SBOMs (fehlen Versionen, PURLs, Lizenzen?). Eine SBOM mit 20 Komponenten für ein Produkt mit Java-Stack ist ein Warnzeichen.

Interviewfragen

F: Was ist eine SBOM, und wozu braucht man sie?

A: Eine maschinenlesbare Liste aller Komponenten einer Software mit Name, Version, eindeutiger Kennung wie PURL, Lizenzen und Abhängigkeiten. Man braucht sie, um bei neuen Schwachstellen schnell zu wissen, welche Produkte betroffen sind, für Lizenz-Compliance und zunehmend für regulatorische Pflichten wie den CRA.

F: CycloneDX oder SPDX, welches Format nimmst du?

A: Beide sind etabliert. CycloneDX kommt aus der Sicherheitswelt, bringt VEX mit und ist das Eingangsformat von Dependency-Track. SPDX ist ISO-Standard und stark bei Lizenz-Compliance. Ich erzeuge im Zweifel beide aus einem Scan und nutze CycloneDX für die Sicherheitsanalyse.

F: Warum unterscheiden sich SBOMs aus dem Quellcode und aus dem Image?

A: Die Quell-SBOM zeigt, was deklariert ist. Ohne Lockfile fehlen transitive Abhängigkeiten, und Betriebssystem-Pakete des Basis-Images fehlen immer. Die Image-SBOM zeigt, was tatsächlich installiert ist und ausgeliefert wird. Für die Risikobewertung des Betriebs zählt die Image-SBOM.

F: Was ist eine PURL, und warum ist sie wichtiger als eine CPE?

A: Eine Package URL benennt ein Paket eindeutig im Kontext seines Ökosystems, etwa pkg:pypi/[email protected]. CPEs stammen aus der NVD und bilden Hersteller und Produkt oft ungenau auf Pakete ab. Das erzeugt Fehltreffer. PURL-basierte Abgleiche mit OSV oder GitHub Advisories sind präziser.

F: Wozu Dependency-Track, wenn Grype doch auch die SBOM scannen kann?

A: Grype liefert eine Momentaufnahme im Pipeline-Lauf. Dependency-Track speichert SBOMs dauerhaft, gleicht sie laufend gegen neue Schwachstellendaten ab, wertet Policies aus, speichert Audit-Entscheidungen und zeigt portfolioweit, wo eine Komponente steckt. Es überwacht also auch Software, die gerade nicht gebaut wird.

F: Was ist VEX?

A: Eine maschinenlesbare Aussage, ob eine bekannte Schwachstelle ein konkretes Produkt betrifft, mit Status wie not_affected, affected, fixed oder under_investigation und einer Begründung. Scanner können VEX einlesen und damit Fehlalarme dauerhaft und nachvollziehbar unterdrücken.

F: Wie stellst du sicher, dass eine SBOM wirklich zu einem bestimmten Image gehört?

A: Ich erzeuge sie für das Image per Digest und hänge sie als signierte Attestation (etwa mit cosign attest --type cyclonedx) an genau diesen Digest. Abnehmer prüfen die Signatur mit dem eigenen Vertrauensanker, und eine Admission-Policy kann den Nachweis vor dem Deployment erzwingen.

F: Was verlangt der Cyber Resilience Act zu SBOMs?

A: Hersteller müssen die Komponenten ihrer Produkte erfassen und eine SBOM in einem gängigen maschinenlesbaren Format erstellen, mindestens für die obersten Abhängigkeiten. Sie muss nicht veröffentlicht, aber Behörden auf Verlangen vorgelegt werden. In Deutschland konkretisiert die BSI TR-03183 die Anforderungen, unter anderem vollständige transitive Abhängigkeiten.

Zusammenfassung

Das hast du gelernt:

  • Eine SBOM ist die Zutatenliste deiner Software: Komponenten mit Version, PURL, Lizenz und Beziehungen.
  • CycloneDX ist sicherheitsorientiert und das Format für Dependency-Track, SPDX ist ISO-Standard mit Lizenz-Schwerpunkt. Syft erzeugt beide in einem Lauf.
  • Quell-SBOMs zeigen Deklariertes, Image-SBOMs zeigen Installiertes. Transitive Abhängigkeiten und OS-Pakete findest du verlässlich nur im Image oder mit Lockfile.
  • Mit jq beantwortest du Fragen an die SBOM direkt, mit grype sbom: prüfst du sie ohne erneuten Image-Scan.
  • Eine signierte Attestation bindet die SBOM fälschungssicher an den Image-Digest.
  • Dependency-Track überwacht SBOMs laufend, setzt Sicherheits- und Lizenz-Policies durch und lässt sich per API-Key und curl in jede Pipeline einbinden.
  • VEX hält fest, warum ein Befund ein Produkt nicht betrifft, und macht Bewertungen maschinenlesbar.
  • CRA, BSI TR-03183 und US EO 14028 machen SBOMs von der guten Praxis zur Pflicht.