SBOM
Co je CycloneDX?
CycloneDX je otevřený standard pro kusovníky (bills of materials), který spravuje OWASP Foundation a který Ecma International vydává jako ECMA-424. Nejznámější je jako formát SBOM: strojově čitelný seznam komponent určitého softwaru, toho, jak na sobě navzájem závisejí, a co je známo o jejich zranitelnostech. Aktuální verzí je CycloneDX 1.7 a stejný formát popisuje také služby, hardware, kryptografii a modely strojového učení.
Aktualizováno
CycloneDX v kostce
| Kdo jej spravuje | Projekt CycloneDX nadace OWASP Foundation spolu s technickou komisí 54 (TC54) organizace Ecma International |
|---|---|
| Norma | ECMA-424. 1. vydání (červen 2024) odpovídá CycloneDX 1.6; 2. vydání (prosinec 2025) odpovídá CycloneDX 1.7 |
| Aktuální verze | CycloneDX 1.7, vydaná v říjnu 2025 |
| Kódování | JSON, XML a Protocol Buffers |
| Typ média | application/vnd.cyclonedx+json, s parametrem verze, například version=1.7 |
| Názvy souborů | bom.json, bom.xml, *.cdx.json, *.cdx.xml |
První verze, CycloneDX 1.0, vyšla v roce 2018 jako kusovník zaměřený na bezpečnost. Ecma zřídila TC54 pro standardy dodavatelského řetězce v prosinci 2023 a CycloneDX 1.6 se v červnu 2024 stal normou ECMA-424. Hlavními zdroji jsou přehled specifikace a stránka ECMA-424.
Co obsahuje SBOM v CycloneDX
Dokument CycloneDX je jeden objekt, obvykle nazývaný BOM. Povinná jsou jen dvě pole, bomFormat (vždy
"CycloneDX") a specVersion. Vše ostatní je volitelné, a proto se dva platné soubory CycloneDX
mohou tolik lišit v tom, co vám skutečně řeknou.
| Prvek | Co obsahuje |
|---|---|
metadata |
Kdy a jak BOM vznikl: časové razítko, nástroje, autoři, fáze životního cyklu a komponenta, kterou BOM popisuje |
components |
Každou knihovnu, framework, kontejner, soubor, firmware, zařízení nebo model s verzí, identifikátory, hashi a licencemi |
services |
Externí služby, které software volá, například API, s jejich koncovými body a datovými toky |
dependencies |
Která komponenta nebo služba závisí na které, takže lze strom znovu sestavit včetně tranzitivních úrovní |
compositions |
Jak úplná je každá část BOM: úplná, neúplná, neznámá nebo neuvedená |
vulnerabilities |
Známé zranitelnosti, jejich hodnocení a u VEX to, zda a jak se produktu týkají |
formulation |
Jak byl produkt sestaven: workflow, úlohy a prostředí, které za ním stojí |
annotations |
Komentáře a poznámky připojené k jiným částem BOM, s tím, kdo je vytvořil a kdy |
declarations, definitions, citations |
Atestace shody se standardy, samotné standardy a odkud pocházejí data v BOM |
Pole metadata.lifecycles říká, kdy BOM vznikl: design, pre-build, build, post-build, operations, discovery
nebo decommission. SBOM z fáze buildu a sken stejného produktu po buildu mohou uvádět různé komponenty, takže při
porovnávání dvou souborů na fázi záleží.
Typy kusovníků CycloneDX
Stejný objektový model pokrývá víc než jen software. Projekt CycloneDX uvádí tyto schopnosti:
| Typ | Popisuje |
|---|---|
| SBOM | Softwarové komponenty a jejich závislosti |
| SaaSBOM | Služby, koncové body a datové toky hostované aplikace |
| HBOM | Hardwarové komponenty |
| CBOM | Kryptografická aktiva: algoritmy, klíče, certifikáty a protokoly |
| ML-BOM | Modely strojového učení a datové sady, na kterých stojí |
| OBOM a MBOM | Provozní prostředí a výrobu produktu |
| VEX, VDR a BOV | Zda se zranitelnost produktu týká (VEX), zprávu dodavatele o známých zranitelnostech (VDR) a kusovník zranitelností (bill of vulnerabilities) |
| CDXA | Atestace, že produkt splňuje standard nebo požadavek |
Jde o různá použití jednoho formátu, ne o samostatné formáty. Dokument VEX je například BOM v CycloneDX, jehož položky
vulnerabilities nesou stav analýzy a odkazují na komponenty v SBOM.
Identifikátory: purl, CPE a hashe
Název komponenty nestačí k tomu, aby se dala spárovat se zranitelností, protože stejný název může v různých
ekosystémech znamenat různé balíčky. Komponenty v CycloneDX proto nesou identifikátory: a
package URL (purl), například pkg:npm/[email protected], CPE, tag SWID,
identifikátory OmniBOR a SWHID a kryptografické hashe. Purl je ten, podle kterého většina nástrojů páruje open source
balíčky, a v prosinci 2025 se stal samostatnou normou Ecma, ECMA-427. Uvnitř dokumentu může mít každý prvek také
bom-ref, lokální ID, pomocí kterého na něj odkazují sekce dependencies, compositions a vulnerabilities.
Příklad CycloneDX v JSON
Malá, ale úplná SBOM aplikace acme-api, která používá jeden npm balíček debug, jenž sám závisí
na ms. Je platná podle schématu JSON pro 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"] }
]
}
-
serialNumberaversionidentifikují tento BOM. Každý nově vygenerovaný BOM dostane nové sériové číslo; když se existující BOM upraví, sériové číslo si ponechá a jeho verze se zvýší o jedna. -
metadata.componentje produkt, který SBOM popisuje, a kořen stromu závislostí. -
dependenciesdělá zmstranzitivní závislost: aplikace o ni nikdy nežádala, žádal o nidebug. PrázdnédependsOnříká, že komponenta nemá žádné závislosti. Vynechání komponenty z grafu znamená, že její závislosti nejsou známé, ne že žádné nemá. -
compositionsuvádí, že strom závislostí podacme-apije úplný. Nástroj, který neviděl všechno, by měl místo toho uvéstincompletenebounknown, aby čtenář věděl, že chybějící balíček nemá považovat za nepřítomný.
Větší soubor s hashi, dodavateli a odpovídající verzí stejné aplikace v SPDX najdete v článku příklady SBOM.
Jak vytvořit SBOM v CycloneDX
Existují tři způsoby, jak ji vytvořit, a každý popisuje něco jiného.
| Metoda | Jak funguje | Co přehlédne |
|---|---|---|
| Skenování manifestů a lockfilů | Čte package-lock.json, requirements.txt, pom.xml a podobné soubory |
Vše, co se stáhne mimo správce balíčků, například instalační skripty, skripty buildu a základní image |
| Analýza image, souborového systému nebo binárky | Prohledá hotovou image kontejneru, adresář nebo binárku a hledá metadata balíčků a signatury | Komponenty, po kterých nezůstala žádná metadata, a zkompilovaný kód, který musí odhadovat |
| Záznam během buildu | Zaznamenává, co build za běhu skutečně stáhl | Jen to, co záznamník nevidí, a dobrý záznamník to uvede jako neúplné |
Bezplatné nástroje, které zapisují CycloneDX:
-
cdxgen, projekt OWASP, pro mnoho jazyků a image kontejnerů:
cdxgen -o bom.json. Ve výchozím nastavení zapisuje CycloneDX 1.7. -
Pluginy ekosystému CycloneDX, například
@cyclonedx/cyclonedx-npm, cyclonedx-python, CycloneDX Maven plugin a cyclonedx-gomod, každý pro jednoho správce balíčků:npx @cyclonedx/cyclonedx-npm --output-file bom.json. -
Syft od Anchore, pro image kontejnerů a souborové systémy:
syft <image> -o cyclonedx-json.
CycloneDX Tool Center uvádí mnoho dalších. Jak se tyto přístupy liší v praxi, viz open source generátory SBOM a SBOM pro image Dockeru.
Jak ověřit platnost souboru CycloneDX
Oficiální CycloneDX CLI zkontroluje soubor podle schématu jeho verze:
cyclonedx validate --input-file bom.json --input-version v1_7 --fail-on-errors
Stejný nástroj pomocí cyclonedx convert převádí mezi JSON, XML a Protocol Buffers, mezi verzemi
specifikace a do SPDX JSON. Ověření podle schématu dokazuje jen to, že je soubor správně utvořený. Neřekne vám, zda
některá komponenta nechybí. K tomu zkontrolujte obsah podle seznamu, jako je
checklist kvality SBOM.
CycloneDX vs SPDX
SPDX je druhý široce používaný formát SBOM, hostovaný Linux Foundation a vydaný jako ISO/IEC 5962:2021. Vyrostl ze souladu s licencemi, zatímco CycloneDX vyšel z bezpečnosti, a proto CycloneDX nese zranitelnosti a VEX ve stejném formátu. Oba popisují komponenty, identifikátory, licence a vztahy, nástroje mezi nimi převádějí a evropský Cyber Resilience Act nejmenuje ani jeden. Který vytváříte, obvykle závisí na tom, co čtou vaši zákazníci a vaše nástroje. Úplné srovnání najdete v článku CycloneDX vs SPDX.
Jak CRACI vytváří SBOM v CycloneDX
CRACI je runner pro GitHub Actions, který zaznamenává každý balíček, který každý job za běhu stáhne, v jakékoli hloubce stromu závislostí a včetně balíčků obnovených z cache CI. Každá komponenta v SBOM tedy v buildu skutečně byla. Každý balíček nese svůj purl a deklarovanou licenci a SBOM každého jobu má stav úplnosti, který říká, co job nemohl vidět. SBOM se exportuje jako CycloneDX nebo SPDX, s tranzitivními závislostmi a zranitelnostmi nalezenými v jejích komponentách, a API ji vrací jako CycloneDX 1.7 JSON. Viz generování SBOM z doby buildu nebo osvědčené postupy pro SBOM.
Kdy CRACI není řešením
- Kusovníky hardwaru, kryptografie nebo služeb. CRACI zaznamenává softwarové balíčky, které build stáhne. HBOM, CBOM nebo SaaSBOM potřebují jiné zdroje.
- Buildy mimo GitHub Actions. GitHub Actions je dnes jediný podporovaný systém CI; další systémy CI jsou v plánu vývoje. Do té doby použijte generátor, jako je cdxgen.
- Software, který dostáváte jako binárku. Pokud jste ho nesestavili, nemůžete zaznamenat jeho build. Požádejte dodavatele o SBOM, nebo použijte binární analýzu.
CycloneDX: časté dotazy
K čemu se CycloneDX používá?
Hlavně pro SBOM: seznam komponent určitého softwaru, abyste mohli sledovat zranitelnosti a licence a sdílet seznam se zákazníky. Stejný formát pokrývá také VEX, služby, hardware, kryptografii a modely strojového učení.
Kdo spravuje CycloneDX?
Projekt CycloneDX vede OWASP Foundation a technická komise 54 organizace Ecma International ho vydává jako normu ECMA-424.
Jaká je nejnovější verze CycloneDX?
CycloneDX 1.7, vydaná v říjnu 2025. Je zároveň 2. vydáním ECMA-424, publikovaným v prosinci 2025. 1. vydání odpovídá CycloneDX 1.6.
Je CycloneDX v JSON, nebo v XML?
V obou a také v Protocol Buffers. Nejběžnější je JSON s typem média application/vnd.cyclonedx+json a názvy souborů jako bom.json nebo name.cdx.json.
Je CycloneDX lepší než SPDX?
Obecně není lepší ani jeden. CycloneDX vyšel z bezpečnosti a nativně nese zranitelnosti a VEX, SPDX vyšel ze souladu s licencemi a je normou ISO. Vytvářejte to, co čtou vaši zákazníci a vaše nástroje; převodníky existují oběma směry.
Jak zkontroluji, že je soubor CycloneDX platný?
Spusťte oficiální CycloneDX CLI: cyclonedx validate --input-file bom.json --fail-on-errors. Kontroluje strukturu podle schématu, ne to, zda některá komponenta chybí.
CycloneDX přímo z buildu
Zaznamenejte každý balíček, který vaše joby GitHub Actions stáhnou, se stavem úplnosti, a exportujte ho jako CycloneDX nebo SPDX.
Rezervujte si demo