SBOM
Wat is CycloneDX?
CycloneDX is een open standaard voor stuklijsten (bills of materials), beheerd door de OWASP Foundation en door Ecma International gepubliceerd als ECMA-424. Het is vooral bekend als SBOM-formaat: een machineleesbare lijst van de componenten in een stuk software, hoe ze van elkaar afhangen en wat er bekend is over hun kwetsbaarheden. De huidige versie is CycloneDX 1.7, en hetzelfde formaat beschrijft ook services, hardware, cryptografie en machinelearningmodellen.
Bijgewerkt op
CycloneDX in één oogopslag
| Beheerd door | Het CycloneDX-project van de OWASP Foundation, met Ecma International Technical Committee 54 (TC54) |
|---|---|
| Standaard | ECMA-424. De 1e editie (juni 2024) is CycloneDX 1.6; de 2e editie (december 2025) is CycloneDX 1.7 |
| Huidige versie | CycloneDX 1.7, uitgebracht in oktober 2025 |
| Coderingen | JSON, XML en Protocol Buffers |
| Mediatype | application/vnd.cyclonedx+json, met een versieparameter zoals version=1.7 |
| Bestandsnamen | bom.json, bom.xml, *.cdx.json, *.cdx.xml |
De eerste versie, CycloneDX 1.0, verscheen in 2018 als op beveiliging gerichte stuklijst. Ecma richtte in december 2023 TC54 op voor standaarden voor de softwareketen, en CycloneDX 1.6 werd in juni 2024 ECMA-424. Het overzicht van de specificatie en de ECMA-424-pagina zijn de primaire bronnen.
Wat een CycloneDX-SBOM bevat
Een CycloneDX-document is één object, meestal een BOM genoemd. Slechts twee velden zijn verplicht: bomFormat
(altijd "CycloneDX") en specVersion. Al het andere is optioneel, en daarom kunnen twee geldige
CycloneDX-bestanden zo sterk verschillen in wat ze u werkelijk vertellen.
| Element | Wat het bevat |
|---|---|
metadata |
Wanneer en hoe de BOM is gemaakt: tijdstempel, tools, auteurs, de levenscyclusfase en het component dat de BOM beschrijft |
components |
Elke bibliotheek, elk framework, elke container, elk bestand, elke firmware, elk apparaat of model, met versie, identifiers, hashes en licenties |
services |
Externe services die de software aanroept, zoals API's, met hun endpoints en gegevensstromen |
dependencies |
Welk component of welke service van welke afhangt, zodat de boom kan worden herbouwd, transitieve niveaus inbegrepen |
compositions |
Hoe volledig elk deel van de BOM is: volledig, onvolledig, onbekend of niet gespecificeerd |
vulnerabilities |
Bekende kwetsbaarheden, hun beoordelingen en, voor VEX, of en hoe ze het product raken |
formulation |
Hoe het product is gebouwd: de workflows, taken en omgeving erachter |
annotations |
Opmerkingen en notities bij andere delen van de BOM, met wie ze maakte en wanneer |
declarations, definitions, citations |
Verklaringen van conformiteit met standaarden, de standaarden zelf, en waar gegevens in de BOM vandaan komen |
Het veld metadata.lifecycles zegt wanneer de BOM is gemaakt: design, pre-build, build, post-build,
operations, discovery of decommission. Een SBOM uit de buildfase en een scan na de build van hetzelfde product kunnen
verschillende componenten vermelden, dus de fase doet ertoe wanneer u twee bestanden vergelijkt.
CycloneDX-BOM-typen
Hetzelfde objectmodel dekt meer dan software. Het CycloneDX-project noemt deze toepassingen:
| Type | Beschrijft |
|---|---|
| SBOM | Softwarecomponenten en hun afhankelijkheden |
| SaaSBOM | Services, endpoints en gegevensstromen van een gehoste applicatie |
| HBOM | Hardwarecomponenten |
| CBOM | Cryptografische middelen: algoritmen, sleutels, certificaten en protocollen |
| ML-BOM | Machinelearningmodellen en de datasets erachter |
| OBOM en MBOM | Operationele omgevingen, en de productie van een product |
| VEX, VDR en BOV | Of een kwetsbaarheid een product raakt (VEX), het rapport van een leverancier over bekende kwetsbaarheden (VDR), en een stuklijst van kwetsbaarheden (BOV) |
| CDXA | Attestaties dat een product aan een standaard of eis voldoet |
Dit zijn toepassingen van één formaat, geen aparte formaten. Een VEX-document is bijvoorbeeld een CycloneDX-BOM waarvan
de vulnerabilities-items een analysestatus hebben en naar componenten in een SBOM verwijzen.
Identifiers: purl, CPE en hashes
De naam van een component is niet genoeg om het aan een kwetsbaarheid te koppelen, omdat dezelfde naam in verschillende
ecosystemen verschillende pakketten kan betekenen. CycloneDX-componenten hebben daarvoor identifiers: een
package URL (purl) zoals pkg:npm/[email protected], een CPE, een SWID-tag,
OmniBOR- en SWHID-identifiers, en cryptografische hashes. Purl is de identifier waarop de meeste tools open-sourcepakketten
matchen, en werd in december 2025 een eigen Ecma-standaard, ECMA-427. Binnen het document kan elk element ook een
bom-ref hebben, een lokale ID waarmee de secties dependencies, compositions en vulnerabilities ernaar
verwijzen.
Een CycloneDX-JSON-voorbeeld
Een kleine maar volledige SBOM voor een applicatie, acme-api, die één npm-pakket gebruikt,
debug, dat op zijn beurt afhangt van ms. Het valideert tegen het JSON-schema van 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"] }
]
}
-
serialNumberenversionidentificeren deze BOM. Elke nieuw gegenereerde BOM krijgt een nieuw serienummer; wanneer een bestaande BOM wordt gewijzigd, behoudt die het serienummer en gaat de versie met één omhoog. -
metadata.componentis het product dat de SBOM beschrijft, en de wortel van de afhankelijkheidsboom. -
dependenciesmaaktmseen transitieve afhankelijkheid: de applicatie heeft er nooit om gevraagd,debugwel. Een legedependsOnzegt dat het component geen afhankelijkheden heeft. Een component weglaten uit de graaf betekent dat de afhankelijkheden onbekend zijn, niet dat het er geen heeft. -
compositionsstelt dat de afhankelijkheidsboom onderacme-apivolledig is. Een tool die niet alles kon zien, hoort in plaats daarvanincompleteofunknownte zeggen, zodat een lezer weet dat een ontbrekend pakket niet als afwezig mag worden behandeld.
Voor een groter bestand met hashes, leveranciers en een bijpassende SPDX-versie van dezelfde applicatie, zie SBOM-voorbeelden.
Hoe u een CycloneDX-SBOM genereert
Er zijn drie manieren om er een te maken, en ze beschrijven verschillende dingen.
| Methode | Hoe het werkt | Wat het mist |
|---|---|---|
| Manifesten en lockfiles scannen | Leest package-lock.json, requirements.txt, pom.xml en vergelijkbare bestanden |
Alles wat buiten de pakketbeheerder wordt opgehaald, zoals installatiescripts, buildscripts en base images |
| Analyse van images, bestandssystemen of binaries | Onderzoekt een afgeronde containerimage, map of binary op pakketmetadata en signaturen | Componenten zonder achtergebleven metadata, en gecompileerde code waarnaar het moet raden |
| Vastleggen tijdens de build | Legt vast wat de build werkelijk ophaalt terwijl die draait | Alleen wat de vastlegger niet kan zien, en een goede vastlegger meldt dat als onvolledig |
Gratis tools die CycloneDX schrijven:
-
cdxgen, een OWASP-project, voor veel talen en containerimages:
cdxgen -o bom.json. Het schrijft standaard CycloneDX 1.7. -
De CycloneDX-ecosysteemplug-ins, zoals
@cyclonedx/cyclonedx-npm, cyclonedx-python, de CycloneDX Maven-plug-in en cyclonedx-gomod, elk voor één pakketbeheerder:npx @cyclonedx/cyclonedx-npm --output-file bom.json. -
Syft, van Anchore, voor containerimages en bestandssystemen:
syft <image> -o cyclonedx-json.
Het CycloneDX Tool Center noemt er nog veel meer. Hoe deze benaderingen zich in de praktijk tot elkaar verhouden, leest u bij open-source-SBOM-generatoren en SBOM's voor Docker-images.
Hoe u een CycloneDX-bestand valideert
De officiële CycloneDX CLI controleert een bestand tegen het schema van zijn versie:
cyclonedx validate --input-file bom.json --input-version v1_7 --fail-on-errors
Dezelfde tool converteert met cyclonedx convert tussen JSON, XML en Protocol Buffers, tussen
specificatieversies, en naar SPDX JSON. Schemavalidatie bewijst alleen dat het bestand goed gevormd is. Het kan u niet
vertellen of er een component ontbreekt. Controleer daarvoor de inhoud aan de hand van een lijst zoals de
SBOM-kwaliteitschecklist.
CycloneDX vs SPDX
SPDX is het andere veelgebruikte SBOM-formaat, ondergebracht bij de Linux Foundation en gepubliceerd als ISO/IEC 5962:2021. Het is voortgekomen uit licentiecompliance, terwijl CycloneDX bij beveiliging begon, en daarom bevat CycloneDX kwetsbaarheden en VEX in hetzelfde formaat. Beide beschrijven componenten, identifiers, licenties en relaties, tools converteren tussen de twee, en de Cyber Resilience Act van de EU noemt geen van beide. Welk formaat u maakt, hangt meestal af van wat uw klanten en tools lezen. De volledige vergelijking staat in CycloneDX vs SPDX.
Hoe CRACI CycloneDX-SBOM's maakt
CRACI is een GitHub Actions-runner die elk pakket vastlegt dat elke job ophaalt terwijl die draait, op elk niveau van de afhankelijkheidsboom en inclusief pakketten die uit CI-caches worden teruggezet. Elk component in de SBOM zat dus werkelijk in de build. Elk pakket heeft zijn purl en gedeclareerde licentie, en de SBOM van elke job heeft een volledigheidsstatus die zegt wat de job niet kon zien. De SBOM wordt geëxporteerd als CycloneDX of SPDX, met de transitieve afhankelijkheden en de kwetsbaarheden die in de componenten zijn gevonden, en de API levert hem als CycloneDX 1.7 JSON. Zie SBOM-generatie tijdens de build of best practices voor SBOM's.
Wanneer CRACI niet het antwoord is
- BOM's voor hardware, cryptografie of services. CRACI legt softwarepakketten vast die een build ophaalt. Een HBOM, CBOM of SaaSBOM heeft andere bronnen nodig.
- Builds buiten GitHub Actions. GitHub Actions is vandaag de enige ondersteunde CI; andere CI-systemen staan op de roadmap. Gebruik in de tussentijd een generator zoals cdxgen.
- Software die u als binary ontvangt. Hebt u het niet zelf gebouwd, dan kunt u de build niet vastleggen. Vraag de leverancier om een SBOM, of gebruik binaire analyse.
CycloneDX: veelgestelde vragen
Waarvoor wordt CycloneDX gebruikt?
Vooral voor SBOM's: de componenten in een stuk software opsommen, zodat u kwetsbaarheden en licenties kunt volgen en de lijst met klanten kunt delen. Hetzelfde formaat dekt ook VEX, services, hardware, cryptografie en machinelearningmodellen.
Wie beheert CycloneDX?
De OWASP Foundation beheert het CycloneDX-project, en Technical Committee 54 van Ecma International publiceert het als de standaard ECMA-424.
Wat is de nieuwste versie van CycloneDX?
CycloneDX 1.7, uitgebracht in oktober 2025. Het is ook de 2e editie van ECMA-424, gepubliceerd in december 2025. De 1e editie komt overeen met CycloneDX 1.6.
Is CycloneDX JSON of XML?
Beide, en ook Protocol Buffers. JSON is het meest gebruikelijk, met het mediatype application/vnd.cyclonedx+json en bestandsnamen zoals bom.json of name.cdx.json.
Is CycloneDX beter dan SPDX?
In het algemeen is geen van beide beter. CycloneDX begon bij beveiliging en ondersteunt kwetsbaarheden en VEX van huis uit, SPDX begon bij licentiecompliance en is een ISO-standaard. Maak wat uw klanten en tools lezen; er bestaan converters in beide richtingen.
Hoe controleer ik of een CycloneDX-bestand geldig is?
Draai de officiële CycloneDX CLI: cyclonedx validate --input-file bom.json --fail-on-errors. Die controleert de structuur tegen het schema, niet of er een component ontbreekt.
CycloneDX uit de build zelf
Leg elk pakket vast dat uw GitHub Actions-jobs ophalen, met een volledigheidsstatus, en exporteer het als CycloneDX of SPDX.
Demo boeken