SBOM
Che cos'è CycloneDX?
CycloneDX è uno standard aperto per le distinte base (bill of materials), gestito dalla OWASP Foundation e pubblicato da Ecma International come ECMA-424. È noto soprattutto come formato SBOM: un elenco leggibile da una macchina dei componenti di un software, di come dipendono l'uno dall'altro e di ciò che si sa delle loro vulnerabilità. La versione attuale è CycloneDX 1.7, e lo stesso formato descrive anche servizi, hardware, crittografia e modelli di machine learning.
Aggiornato il
CycloneDX in sintesi
| Mantenuto da | Il progetto CycloneDX della OWASP Foundation, con il Technical Committee 54 (TC54) di Ecma International |
|---|---|
| Standard | ECMA-424. La 1ª edizione (giugno 2024) corrisponde a CycloneDX 1.6; la 2ª edizione (dicembre 2025) a CycloneDX 1.7 |
| Versione attuale | CycloneDX 1.7, rilasciata a ottobre 2025 |
| Codifiche | JSON, XML e Protocol Buffers |
| Media type | application/vnd.cyclonedx+json, con un parametro di versione come version=1.7 |
| Nomi dei file | bom.json, bom.xml, *.cdx.json, *.cdx.xml |
La prima versione, CycloneDX 1.0, è uscita nel 2018 come distinta base orientata alla sicurezza. Ecma ha istituito il TC54 per gli standard della supply chain a dicembre 2023, e CycloneDX 1.6 è diventato ECMA-424 a giugno 2024. La panoramica della specifica e la pagina ECMA-424 sono i riferimenti principali.
Che cosa contiene una SBOM CycloneDX
Un documento CycloneDX è un unico oggetto, di solito chiamato BOM. Solo due campi sono obbligatori, bomFormat
(sempre "CycloneDX") e specVersion. Tutto il resto è facoltativo, ed è per questo che due file
CycloneDX validi possono differire così tanto in ciò che dicono davvero.
| Elemento | Che cosa contiene |
|---|---|
metadata |
Quando e come è stata creata la BOM: timestamp, strumenti, autori, fase del ciclo di vita e il componente che la BOM descrive |
components |
Ogni libreria, framework, container, file, firmware, dispositivo o modello, con versione, identificatori, hash e licenze |
services |
Servizi esterni richiamati dal software, come le API, con i loro endpoint e flussi di dati |
dependencies |
Quale componente o servizio dipende da quale, così che l'albero possa essere ricostruito, livelli transitivi inclusi |
compositions |
Quanto è completa ogni parte della BOM: completa, incompleta, sconosciuta o non specificata |
vulnerabilities |
Vulnerabilità note, le loro valutazioni e, per VEX, se e come riguardano il prodotto |
formulation |
Come è stato costruito il prodotto: i workflow, le attività e l'ambiente alla base |
annotations |
Commenti e note collegati ad altre parti della BOM, con chi li ha scritti e quando |
declarations, definitions, citations |
Attestazioni di conformità agli standard, gli standard stessi e la provenienza dei dati nella BOM |
Il campo metadata.lifecycles indica quando è stata creata la BOM: design, pre-build, build, post-build,
operations, discovery o decommission. Una SBOM della fase di build e una scansione post-build dello stesso prodotto
possono elencare componenti diversi, quindi la fase conta quando si confrontano due file.
I tipi di BOM di CycloneDX
Lo stesso modello a oggetti copre più del solo software. Il progetto CycloneDX elenca queste capacità:
| Tipo | Descrive |
|---|---|
| SBOM | Componenti software e le loro dipendenze |
| SaaSBOM | Servizi, endpoint e flussi di dati di un'applicazione ospitata |
| HBOM | Componenti hardware |
| CBOM | Risorse crittografiche: algoritmi, chiavi, certificati e protocolli |
| ML-BOM | Modelli di machine learning e i dataset alla loro base |
| OBOM e MBOM | Ambienti operativi e la produzione di un prodotto |
| VEX, VDR e BOV | Se una vulnerabilità riguarda un prodotto (VEX), il rapporto di un vendor sulle vulnerabilità note (VDR) e una distinta delle vulnerabilità |
| CDXA | Attestazioni che un prodotto soddisfa uno standard o un requisito |
Si tratta di usi di un unico formato, non di formati separati. Un documento VEX, per esempio, è una BOM CycloneDX le cui
voci vulnerabilities riportano uno stato di analisi e puntano a componenti di una SBOM.
Identificatori: purl, CPE e hash
Il nome di un componente non basta per associarlo a una vulnerabilità, perché lo stesso nome può indicare pacchetti
diversi in ecosistemi diversi. Per questo i componenti CycloneDX riportano degli identificatori: un
package URL (purl) come pkg:npm/[email protected], un CPE, un tag SWID,
identificatori OmniBOR e SWHID e hash crittografici. Il purl è quello su cui la maggior parte degli strumenti effettua
la corrispondenza per i pacchetti open source, ed è diventato a sua volta uno standard Ecma, ECMA-427, a dicembre 2025.
All'interno del documento, ogni elemento può avere anche un bom-ref, un ID locale che le sezioni
dependencies, compositions e vulnerabilities usano per farvi riferimento.
Un esempio JSON di CycloneDX
Una SBOM piccola ma completa per un'applicazione, acme-api, che usa un pacchetto npm, debug,
il quale a sua volta dipende da ms. È valida rispetto allo schema JSON di CycloneDX 1.7.
{
"bomFormat": "CycloneDX",
"specVersion": "1.7",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"metadata": {
"timestamp": "2026-11-16T09:30:00Z",
"lifecycles": [{ "phase": "build" }],
"component": {
"type": "application",
"bom-ref": "acme-api",
"name": "acme-api",
"version": "1.4.0"
}
},
"components": [
{
"type": "library",
"bom-ref": "pkg:npm/[email protected]",
"name": "debug",
"version": "4.4.0",
"purl": "pkg:npm/[email protected]",
"licenses": [{ "license": { "id": "MIT" } }]
},
{
"type": "library",
"bom-ref": "pkg:npm/[email protected]",
"name": "ms",
"version": "2.1.3",
"purl": "pkg:npm/[email protected]",
"licenses": [{ "license": { "id": "MIT" } }]
}
],
"dependencies": [
{ "ref": "acme-api", "dependsOn": ["pkg:npm/[email protected]"] },
{ "ref": "pkg:npm/[email protected]", "dependsOn": ["pkg:npm/[email protected]"] },
{ "ref": "pkg:npm/[email protected]", "dependsOn": [] }
],
"compositions": [
{ "aggregate": "complete", "dependencies": ["acme-api"] }
]
}
-
serialNumbereversionidentificano questa BOM. Ogni BOM generata ex novo riceve un nuovo numero di serie; quando una BOM esistente viene modificata, mantiene il numero di serie e la sua versione aumenta di uno. -
metadata.componentè il prodotto descritto dalla SBOM e la radice dell'albero delle dipendenze. -
dependenciesrendemsuna dipendenza transitiva: l'applicazione non l'ha mai richiesta, l'ha richiestadebug. UndependsOnvuoto indica che il componente non ha dipendenze. Lasciare un componente fuori dal grafo significa che le sue dipendenze sono sconosciute, non che non ne ha. -
compositionsdichiara che l'albero delle dipendenze sottoacme-apiè completo. Uno strumento che non ha potuto vedere tutto dovrebbe invece indicareincompleteounknown, così che chi legge sappia di non dover considerare assente un pacchetto mancante.
Per un file più ampio con hash, fornitori e una versione SPDX corrispondente della stessa applicazione, consulti gli esempi di SBOM.
Come generare una SBOM CycloneDX
Ci sono tre modi per produrne una, e descrivono cose diverse.
| Metodo | Come funziona | Che cosa non vede |
|---|---|---|
| Scansione di manifest e lockfile | Legge package-lock.json, requirements.txt, pom.xml e file simili |
Tutto ciò che viene scaricato al di fuori del package manager, come script di installazione, script di build e immagini base |
| Analisi di immagini, filesystem o binari | Esamina un'immagine container, una directory o un binario finiti alla ricerca di metadati e firme dei pacchetti | I componenti che non hanno lasciato metadati e il codice compilato che deve indovinare |
| Registrazione in fase di build | Registra ciò che la build ha effettivamente scaricato mentre è in esecuzione | Solo ciò che il registratore non può vedere, che uno strumento valido dichiara come incompleto |
Strumenti gratuiti che scrivono CycloneDX:
-
cdxgen, un progetto OWASP, per molti linguaggi e immagini container:
cdxgen -o bom.json. Scrive CycloneDX 1.7 per impostazione predefinita. -
I plugin dell'ecosistema CycloneDX, come
@cyclonedx/cyclonedx-npm, cyclonedx-python, il plugin Maven di CycloneDX e cyclonedx-gomod, ciascuno per un package manager:npx @cyclonedx/cyclonedx-npm --output-file bom.json. -
Syft, di Anchore, per immagini container e filesystem:
syft <image> -o cyclonedx-json.
Il Tool Center di CycloneDX ne elenca molti altri. Per il confronto pratico tra questi approcci, consulti generatori di SBOM open source e SBOM delle immagini Docker.
Come convalidare un file CycloneDX
La CycloneDX CLI ufficiale verifica un file rispetto allo schema della sua versione:
cyclonedx validate --input-file bom.json --input-version v1_7 --fail-on-errors
Lo stesso strumento converte tra JSON, XML e Protocol Buffers, tra versioni della specifica e verso SPDX JSON, con
cyclonedx convert. La convalida dello schema dimostra solo che il file è ben formato. Non può dirLe se manca
un componente. Per questo, verifichi il contenuto con un elenco come la
checklist di qualità delle SBOM.
CycloneDX vs SPDX
SPDX è l'altro formato SBOM molto diffuso, ospitato dalla Linux Foundation e pubblicato come ISO/IEC 5962:2021. È nato dalla conformità delle licenze, mentre CycloneDX è partito dalla sicurezza, ed è per questo che CycloneDX include vulnerabilità e VEX nello stesso formato. Entrambi descrivono componenti, identificatori, licenze e relazioni, esistono strumenti che convertono dall'uno all'altro, e il Cyber Resilience Act dell'UE non ne nomina nessuno. Quale produrre dipende di solito da ciò che leggono i Suoi clienti e i Suoi strumenti. Il confronto completo è in CycloneDX vs SPDX.
Come CRACI produce SBOM CycloneDX
CRACI è un runner GitHub Actions che registra ogni pacchetto scaricato da ogni job mentre è in esecuzione, a ogni profondità dell'albero delle dipendenze e compresi i pacchetti ripristinati dalle cache CI. Ogni componente della SBOM era quindi effettivamente nella build. Ogni pacchetto riporta il proprio purl e la licenza dichiarata, e la SBOM di ogni job ha uno stato di completezza che indica ciò che il job non ha potuto vedere. La SBOM si esporta in CycloneDX o SPDX, con le dipendenze transitive e le vulnerabilità trovate nei suoi componenti, e l'API la restituisce come JSON CycloneDX 1.7. Consulti la generazione di SBOM in fase di build o le best practice per le SBOM.
Quando CRACI non è la risposta
- BOM di hardware, crittografia o servizi. CRACI registra i pacchetti software scaricati da una build. Una HBOM, una CBOM o una SaaSBOM richiedono altre fonti.
- Build al di fuori di GitHub Actions. Oggi GitHub Actions è l'unico CI supportato; altri sistemi CI sono in roadmap. Nel frattempo usi un generatore come cdxgen.
- Software che riceve come binario. Se non lo ha compilato Lei, non può registrarne la build. Chieda una SBOM al fornitore o usi l'analisi dei binari.
CycloneDX: domande frequenti
A che cosa serve CycloneDX?
Soprattutto alle SBOM: elencare i componenti di un software per tracciarne vulnerabilità e licenze e condividere l'elenco con i clienti. Lo stesso formato copre anche VEX, servizi, hardware, crittografia e modelli di machine learning.
Chi mantiene CycloneDX?
La OWASP Foundation gestisce il progetto CycloneDX, e il Technical Committee 54 di Ecma International lo pubblica come standard ECMA-424.
Qual è l'ultima versione di CycloneDX?
CycloneDX 1.7, rilasciata a ottobre 2025. È anche la 2ª edizione di ECMA-424, pubblicata a dicembre 2025. La 1ª edizione corrisponde a CycloneDX 1.6.
CycloneDX è JSON o XML?
Entrambi, e anche Protocol Buffers. JSON è il più comune, con il media type application/vnd.cyclonedx+json e nomi di file come bom.json o name.cdx.json.
CycloneDX è migliore di SPDX?
Nessuno dei due è migliore in assoluto. CycloneDX è nato dalla sicurezza e include nativamente vulnerabilità e VEX, SPDX dalla conformità delle licenze ed è uno standard ISO. Produca ciò che leggono i Suoi clienti e i Suoi strumenti; esistono convertitori in entrambe le direzioni.
Come verifico che un file CycloneDX sia valido?
Esegua la CycloneDX CLI ufficiale: cyclonedx validate --input-file bom.json --fail-on-errors. Verifica la struttura rispetto allo schema, non se manca qualche componente.
CycloneDX dalla build stessa
Registri ogni pacchetto scaricato dai Suoi job GitHub Actions, con uno stato di completezza, e lo esporti in CycloneDX o SPDX.
Prenota una demo