CycloneDX-CBOM in CI erzeugen

Eine CycloneDX-CBOM (Cryptographic Bill of Materials, kryptografische Stückliste) ist ein CycloneDX-Dokument, dessen Komponenten kryptografische Assets beschreiben: Algorithmen, Protokolle, Zertifikate und Schlüsselmaterial. Sie in der Continuous Integration zu erzeugen, ist überwiegend Verdrahtungsarbeit: Detektoren über Quellcode, Abhängigkeiten, Container-Images und Testendpunkte laufen lassen, die Ergebnisse zu einem einzigen CycloneDX-1.6-Dokument zusammenführen, dieses gegen das Schema validieren und es anschließend speichern und mit dem vorherigen Build vergleichen. Der schwierige Teil besteht darin, ehrlich zu benennen, was eine Build-Pipeline tatsächlich sehen kann. Für das Konzept selbst beginnen Sie mit unserer Einführung in die CBOM.

Wo kryptografische Assets im CycloneDX-1.6-Modell liegen

CycloneDX 1.6 hat den Komponententyp cryptographic-asset eingeführt. Jede solche Komponente enthält ein cryptoProperties-Objekt, und dessen Feld assetType bestimmt, welche Eigenschaftsgruppe gilt. Es gibt vier Asset-Typen.

Zwei weitere Felder leisten die eigentliche Inventarisierungsarbeit. Das Feld oid ordnet einem Algorithmus seinen Object Identifier zu, sofern Sie ihn kennen. Und im Array dependencies gibt das Feld provides an, dass eine Softwarekomponente ein kryptografisches Asset implementiert. Auf diese Weise beantwortet eine CBOM die Frage, die ein Auditor tatsächlich stellt: Welche Anwendung nutzt diesen Algorithmus, und wo?

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "serialNumber": "urn:uuid:4e1e1f2a-0000-0000-0000-000000000000",
  "version": 1,
  "metadata": {
    "timestamp": "2026-10-19T06:12:00Z",
    "component": {
      "type": "application",
      "bom-ref": "payments-api@1.42.0",
      "name": "payments-api",
      "version": "1.42.0"
    }
  },
  "components": [
    {
      "type": "cryptographic-asset",
      "bom-ref": "crypto/algorithm/ml-kem-768",
      "name": "ML-KEM-768",
      "cryptoProperties": {
        "assetType": "algorithm",
        "algorithmProperties": {
          "primitive": "kem",
          "parameterSetIdentifier": "768",
          "cryptoFunctions": ["keygen", "encapsulate", "decapsulate"],
          "nistQuantumSecurityLevel": 3
        }
      }
    },
    {
      "type": "cryptographic-asset",
      "bom-ref": "crypto/protocol/tls-1.3",
      "name": "TLS 1.3",
      "cryptoProperties": {
        "assetType": "protocol",
        "protocolProperties": {
          "type": "tls",
          "version": "1.3",
          "cipherSuites": [
            { "name": "TLS_AES_256_GCM_SHA384", "identifiers": ["0x13", "0x02"] }
          ],
          "cryptoRefArray": ["crypto/algorithm/ml-kem-768"]
        }
      }
    }
  ],
  "dependencies": [
    { "ref": "payments-api@1.42.0", "provides": ["crypto/protocol/tls-1.3"] }
  ]
}

ML-KEM ist der in NIST FIPS 203 standardisierte Schlüsselkapselungsmechanismus (Key Encapsulation Mechanism); sein Parametersatz 768 liegt in der NIST-Quantensicherheitskategorie 3. In Protokollkomponenten erscheinen die hybriden Schlüsselaustauschgruppen, zum Beispiel X25519MLKEM768, dessen Codepoint 0x11EC in der IANA-Registry der TLS-Parameter aufgeführt ist.

Statische Erkennung und beobachtetes Verhalten

Ein CI-Job sieht ein Repository, eine Lockfile und ein Image. Einen ausgehandelten Handshake sieht er nicht. Beides gleichzusetzen ist der häufigste Grund, warum eine CBOM irreführend wird.

Halten Sie den Unterschied im Dokument fest. Legen Sie statisch abgeleitete Fakten in der Komponente selbst ab, mit dem Dateipfad in den Evidence-Occurrences der Komponente, und legen Sie gemessene Fakten in protocolProperties und certificateProperties ab, die von einem Probing-Job erzeugt werden. Befüllen Sie stets metadata.tools, damit Leser erkennen, welcher Detektor welche Aussage getroffen hat.

Eine Pipeline im Überblick

1. Den Umfang festlegen

Bevor ein Werkzeug läuft, legen Sie fest, was eine CBOM abdeckt: eine deploybare Komponente, eine Version, eine Umgebung. Eine einzige Datei, die zwölf Dienste beschreibt, altert schlecht und lässt sich nicht sinnvoll vergleichen.

2. Parallel erfassen

1. Quellcode- und Abhängigkeitsscan: ein statischer Analysator über das Repository und die Lockfiles, der Algorithmus-Assets mit Fundstellen ausgibt.
2. Image- oder Dateisystemscan: das gebaute Artefakt auf Kryptobibliotheken, Zertifikatsbündel, Keystores und Konfigurationsdateien untersuchen.
3. Probe beobachteter Endpunkte: ausschließlich gegen Staging bestätigen, was tatsächlich ausgehandelt wird.

# TLS: does the staging endpoint negotiate a hybrid group?
# requires OpenSSL 3.5 or later for the ML-KEM groups
openssl s_client -connect staging.example.com:443 \
  -groups X25519MLKEM768 </dev/null | grep "Negotiated TLS1.3 group"

# SSH: which key agreement algorithms does this client build support?
ssh -Q kex

# SSH: confirm the server accepts the post-quantum hybrid key agreement
ssh -o KexAlgorithms=mlkem768x25519-sha256 -o BatchMode=yes \
  git@staging.example.com true

Der Algorithmus mlkem768x25519-sha256 wurde in OpenSSH 9.9 hinzugefügt und ist laut den OpenSSH-Release-Notes seit OpenSSH 10.0 der Standard für die Schlüsselvereinbarung. Testen Sie gegen Staging, niemals gegen Produktion, und behalten Sie in jeder Serverkonfiguration, die Sie anfassen, nach der hybriden Gruppe einen klassischen Fallback wie X25519 bei.

3. Zusammenführen, kennzeichnen und validieren

Führen Sie die Teildokumente zu einem zusammen und lassen Sie den Job fehlschlagen, wenn das Ergebnis nicht schemakonform ist. Die CycloneDX CLI erledigt beides.

cyclonedx merge \
  --input-files static.cbom.json image.cbom.json observed.cbom.json \
  --output-file cbom.json

cyclonedx validate --input-file cbom.json --fail-on-errors

Versehen Sie das Dokument mit metadata.timestamp, der Komponentenversion und dem Commit-SHA. Eine CBOM ohne Herkunftsnachweis ist eine Meinung.

Die CBOM speichern und vergleichen

Veröffentlichen Sie die Datei zur Nachvollziehbarkeit als Build-Artefakt und halten Sie pro Komponente eine normalisierte Kopie in einem eigenen Repository oder auf einem BOM-Server vor, damit die Historie abfragbar bleibt. Die Normalisierung ist wichtiger als die Speicherung: Sortieren Sie die Komponenten, verwenden Sie stabile bom-ref-Werte, die keine Build-Nummer enthalten, und schließen Sie den Zeitstempel vom Diff aus. Andernfalls sieht jeder Build wie eine Änderung aus.

# extract a stable, sorted view of the cryptographic assets
jq -S '[.components[]
       | select(.type == "cryptographic-asset")
       | {name, assetType: .cryptoProperties.assetType,
          primitive: .cryptoProperties.algorithmProperties.primitive}]
       | sort_by(.name)' cbom.json > current.view.json

diff -u previous.view.json current.view.json

Legen Sie anschließend fest, was ein Unterschied bedeutet. Sinnvolle Gates, nach steigender Schwere: Ein neues Asset taucht auf, das kein früherer Build deklariert hat; ein quantenverwundbarer Public-Key-Algorithmus taucht in einer Komponente auf, die bisher keinen hatte; eine veraltete vorstandardisierte Gruppe wie eine Kyber-Draft-TLS-Gruppe taucht irgendwo auf; eine hybride Gruppe verschwindet aus einem Dienst, der sie bisher hatte. Beginnen Sie mit Warnungen statt mit Fehlschlägen, bis das Rauschen der Detektoren verstanden ist. Dieser Diff ist der messbare Teil der Krypto-Agilität: Er zeigt, ob sich Ihre kryptografische Oberfläche beabsichtigt oder zufällig ändert.

Grenzen, die festgehalten werden sollten

• Die Abdeckung ist je nach Sprache und Ökosystem ungleichmäßig. Ein Detektor, der eine Sprache gut liest, kann in einer anderen blind sein. Halten Sie fest, was nicht gescannt wurde.
• Statische Befunde sind Möglichkeiten, keine Nutzung. Dass eine Bibliothek RSA unterstützt, bedeutet nicht, dass RSA verwendet wird. Hinterlegen Sie einen Konfidenzhinweis in den Komponenteneigenschaften, statt Gewissheit zu suggerieren.
• Zur Laufzeit aufgelöste Konfiguration ist unsichtbar. Umgebungsvariablen, Secret Manager, Service Meshes und Reverse Proxies können alles überschreiben, was im Repository steht.
• Object Identifier sind unvollständig. Für neuere Algorithmen ist das Feld oid unter Umständen schlicht nicht verfügbar; lassen Sie es dann leer, statt zu raten.
• Duplikate beim Zusammenführen. Zwei Detektoren, die denselben Algorithmus unterschiedlich benennen, erzeugen zwei Komponenten, sofern Ihr bom-ref-Schema nicht deterministisch ist.
• Ein Schweregradmodell ist nicht eingebaut. CycloneDX beschreibt Assets; die Beurteilung, was quantenverwundbar ist, kommt von Ihnen oder aus einer Referenz wie unseren Algorithmusseiten.

Was eine in CI erzeugte CBOM belegt

Mehrere Regelwerke verlangen ein Inventar der eingesetzten Kryptografie. PCI DSS v4.0.1 Anforderung 12.3.3 verlangt, dass eingesetzte Cipher Suites und Protokolle dokumentiert und mindestens alle 12 Monate überprüft werden, einschließlich der Einsatzorte und einer dokumentierten Strategie für erwartete Änderungen bei kryptografischen Schwachstellen; die Anforderung ist seit dem 31. März 2025 verpflichtend (PCI SSC Document Library). DORA, Delegierte Verordnung (EU) 2024/1774 der Kommission, verlangt in Artikel 6 eine Verschlüsselungsleitlinie mit Bestimmungen zur Aktualisierung oder Änderung kryptografischer Technologie entsprechend der Entwicklung der Kryptoanalyse sowie in Artikel 7 ein Schlüsselmanagement über den gesamten Lebenszyklus und ein Register der Zertifikate für IKT-Assets, die kritische oder wichtige Funktionen unterstützen (EUR-Lex). Für US-Bundesbehörden fordert OMB M-26-15 ein automatisiertes, kontinuierlich aktualisiertes Kryptografieinventar (M-26-15). Die EU Coordinated Implementation Roadmap v1.1 nennt ein Kryptografieinventar unter den ersten Schritten bis Ende 2026, und zwar als koordinierte Leitlinie für die Mitgliedstaaten, nicht als Verordnung, die Unternehmen bindet.

Unsere Auslegung, ausdrücklich als solche gekennzeichnet: Keiner dieser Texte nennt CycloneDX, und eine CBOM ist ein praktikabler Weg, ein solches Inventar zu erstellen und zu pflegen, kein vorgeschriebenes Format. Erstellen Sie die Datei, weil sie die nächste Migrationsentscheidung günstiger macht, und ordnen Sie sie dann der jeweils geltenden Pflicht zu. Dies ist eine Information, keine Rechtsberatung.

Nächster Schritt: die CBOM mit der Realität abgleichen

Eine in CI erzeugte CBOM zeigt Ihnen, was Ihr Build enthält. Was Ihre Server aushandeln, kann sie Ihnen nicht sagen. Schließen Sie diese Lücke, indem Sie die Endpunkte selbst testen: Scannen Sie Ihre Domain mit PQC Status, um die hybriden ML-KEM-Gruppen, TLS-Versionen und die Zertifikatskette zu sehen, die einem Client tatsächlich angeboten werden, und übernehmen Sie diese beobachteten Werte anschließend in die protocolProperties und certificateProperties Ihrer nächsten CBOM, damit das Dokument sowohl Code als auch Verhalten abbildet.