Generare una CBOM CycloneDX in CI

Una CBOM CycloneDX (cryptographic bill of materials, distinta base crittografica) è un documento CycloneDX i cui componenti descrivono asset crittografici: algoritmi, protocolli, certificati e materiale crittografico. Produrne una in integrazione continua è soprattutto una questione di collegamenti: eseguire i rilevatori su codice sorgente, dipendenze, immagini container ed endpoint di test, unire i risultati in un unico documento CycloneDX 1.6, validarlo rispetto allo schema, quindi archiviarlo e confrontarlo con la build precedente. La parte difficile è essere onesti su ciò che una pipeline di build può effettivamente vedere. Per il concetto in sé, partite dalla nostra introduzione alla CBOM.

Dove risiedono gli asset crittografici nel modello CycloneDX 1.6

CycloneDX 1.6 ha introdotto il tipo di componente cryptographic-asset. Ciascuno di questi componenti contiene un oggetto cryptoProperties, e il suo campo assetType determina quale gruppo di proprietà si applica. Esistono quattro tipi di asset.

Altri due campi svolgono il vero lavoro di inventario. Il campo oid associa un algoritmo al suo identificatore di oggetto, quando lo conoscete. E nell'array dependencies, il campo provides indica che un componente software implementa un asset crittografico. È così che una CBOM risponde alla domanda che un auditor pone davvero: quale applicazione usa questo algoritmo, e dove?

{
  "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 è il meccanismo di incapsulamento delle chiavi standardizzato in NIST FIPS 203; il suo set di parametri 768 si colloca nella categoria di sicurezza quantistica NIST 3. È nei componenti di protocollo che compaiono i gruppi di scambio di chiavi ibridi, ad esempio X25519MLKEM768, il cui codepoint 0x11EC è elencato nel registro IANA dei parametri TLS.

Rilevamento statico e comportamento osservato

Un job CI vede un repository, un lockfile e un'immagine. Non vede un handshake negoziato. Trattare le due cose come se fossero la stessa è il modo più comune in cui una CBOM diventa fuorviante.

Registrate la differenza nel documento. Mantenete i fatti derivati staticamente nel componente stesso, con il percorso del file nelle occorrenze delle evidenze del componente, e mantenete i fatti misurati in protocolProperties e certificateProperties prodotti da un job di probing. Compilate sempre metadata.tools, affinché il lettore sappia quale rilevatore ha formulato quale affermazione.

Schema di una pipeline

1. Dichiarare il perimetro

Prima che qualsiasi strumento venga eseguito, decidete cosa copre una CBOM: un componente distribuibile, una versione, un ambiente. Un unico file che descrive dodici servizi invecchia male e non può essere confrontato in modo utile.

2. Raccogliere in parallelo

1. Scansione di sorgenti e dipendenze: un analizzatore statico sul repository e sui lockfile, che emette asset di tipo algoritmo con le posizioni delle evidenze.
2. Scansione dell'immagine o del filesystem: ispezionare l'artefatto prodotto alla ricerca di librerie crittografiche, bundle di certificati, keystore e file di configurazione.
3. Probe degli endpoint osservati: solo sullo staging, confermare ciò che viene realmente negoziato.

# 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

L'algoritmo mlkem768x25519-sha256 è stato aggiunto in OpenSSH 9.9 ed è diventato l'accordo di chiave predefinito in OpenSSH 10.0, secondo le note di rilascio di OpenSSH. Eseguite i probe sullo staging, mai in produzione, e mantenete un fallback classico come X25519 dopo il gruppo ibrido in ogni configurazione server che modificate.

3. Unire, marcare e validare

Unite i documenti parziali in uno solo, quindi fate fallire il job se il risultato non è valido rispetto allo schema. La CLI di CycloneDX fa entrambe le cose.

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

Marcate metadata.timestamp, la versione del componente e lo SHA del commit. Una CBOM senza provenienza è un'opinione.

Archiviare e confrontare la CBOM

Pubblicate il file come artefatto di build per la tracciabilità, e conservate una copia normalizzata per componente in un repository dedicato o in un server BOM, così che lo storico sia interrogabile. La normalizzazione conta più dell'archiviazione: ordinate i componenti, usate valori bom-ref stabili che non contengano il numero di build, ed escludete il timestamp dal diff. Altrimenti ogni build appare come una modifica.

# 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

Decidete poi cosa significa una differenza. Controlli utili, in ordine crescente di gravità: compare un nuovo asset che nessuna build precedente aveva dichiarato; un algoritmo a chiave pubblica vulnerabile ai computer quantistici compare in un componente che prima non ne aveva; un gruppo pre-standard obsoleto, come un gruppo TLS Kyber in versione draft, compare in qualsiasi punto; un gruppo ibrido scompare da un servizio che lo aveva. Iniziate con un avviso, non con un fallimento, finché il rumore dei rilevatori non è compreso. Questo diff è la parte misurabile della crypto agility: mostra se la vostra superficie crittografica cambia intenzionalmente o per caso.

Limiti da mettere per iscritto

• La copertura è disomogenea tra linguaggi ed ecosistemi. Un rilevatore che legge bene un linguaggio può essere cieco in un altro. Registrate ciò che non è stato analizzato.
• I risultati statici sono possibilità, non utilizzi. Una libreria che supporta RSA non significa che RSA sia utilizzato. Mantenete una nota di affidabilità nelle proprietà del componente invece di lasciar intendere una certezza.
• La configurazione risolta a runtime è invisibile. Variabili d'ambiente, secret manager, service mesh e reverse proxy possono sovrascrivere tutto ciò che dice il repository.
• Gli identificatori di oggetto sono incompleti. Per gli algoritmi recenti il campo oid può semplicemente non essere disponibile; lasciatelo vuoto anziché tirare a indovinare.
• Duplicati in fase di unione. Due rilevatori che nominano lo stesso algoritmo in modo diverso producono due componenti, a meno che il vostro schema di bom-ref non sia deterministico.
• Nessun modello di gravità integrato. CycloneDX descrive gli asset; il giudizio su ciò che è vulnerabile ai computer quantistici spetta a voi, o a un riferimento come le nostre pagine sugli algoritmi.

Cosa dimostra una CBOM generata in CI

Diversi testi richiedono un inventario della crittografia in uso. Il requisito 12.3.3 di PCI DSS v4.0.1 chiede che le cipher suite e i protocolli in uso siano documentati e riesaminati almeno ogni 12 mesi, includendo dove vengono utilizzati e una strategia documentata per i cambiamenti previsti nelle vulnerabilità crittografiche, ed è obbligatorio dal 31 marzo 2025 (PCI SSC document library). DORA, Regolamento delegato (UE) 2024/1774 della Commissione, richiede all'articolo 6 una politica di cifratura con disposizioni per l'aggiornamento o la modifica della tecnologia crittografica in funzione degli sviluppi della crittoanalisi, e all'articolo 7 la gestione delle chiavi lungo l'intero ciclo di vita oltre a un registro dei certificati per gli asset ICT che supportano funzioni essenziali o importanti (EUR-Lex). Per le agenzie federali statunitensi, OMB M-26-15 richiede un inventario crittografico automatizzato e aggiornato in modo continuo (M-26-15). La EU Coordinated Implementation Roadmap v1.1 indica un inventario crittografico tra i primi passi entro la fine del 2026, come orientamento coordinato per gli Stati membri e non come regolamento vincolante per le imprese.

La nostra interpretazione, chiaramente indicata come tale: nessuno di questi testi menziona CycloneDX, e una CBOM è un modo pratico per produrre e mantenere un tale inventario, non un formato obbligatorio. Costruite il file perché rende meno costosa la prossima decisione di migrazione, poi mappatelo sull'obbligo applicabile. Si tratta di un'informazione, non di una consulenza legale.

Prossimo passo: confrontare la CBOM con la realtà

Una CBOM generata in CI vi dice cosa contiene la vostra build. Non può dirvi cosa negoziano i vostri server. Colmate questo divario testando direttamente gli endpoint: analizzate il vostro dominio con PQC Status per vedere i gruppi ibridi ML-KEM, le versioni TLS e la catena di certificati effettivamente offerti a un client, quindi riportate questi valori osservati nelle protocolProperties e certificateProperties della vostra prossima CBOM, così che il documento rifletta sia il codice sia il comportamento.