SBOM
Mitä CycloneDX on?
CycloneDX on avoin standardi materiaaliluetteloille (bill of materials). Sitä ylläpitää OWASP Foundation, ja Ecma International julkaisee sen nimellä ECMA-424. Se tunnetaan parhaiten SBOM-formaattina: koneluettavana luettelona ohjelmiston komponenteista, niiden keskinäisistä riippuvuuksista ja siitä, mitä niiden haavoittuvuuksista tiedetään. Nykyinen versio on CycloneDX 1.7, ja sama formaatti kuvaa myös palveluita, laitteistoa, kryptografiaa ja koneoppimismalleja.
Päivitetty
CycloneDX lyhyesti
| Ylläpitäjä | OWASP Foundationin CycloneDX-projekti yhdessä Ecma Internationalin teknisen komitean 54 (TC54) kanssa |
|---|---|
| Standardi | ECMA-424. 1. painos (kesäkuu 2024) on CycloneDX 1.6; 2. painos (joulukuu 2025) on CycloneDX 1.7 |
| Nykyinen versio | CycloneDX 1.7, julkaistu lokakuussa 2025 |
| Koodaukset | JSON, XML ja Protocol Buffers |
| Mediatyyppi | application/vnd.cyclonedx+json, versioparametrin kanssa, kuten version=1.7 |
| Tiedostonimet | bom.json, bom.xml, *.cdx.json, *.cdx.xml |
Ensimmäinen versio, CycloneDX 1.0, julkaistiin vuonna 2018 tietoturvaan keskittyvänä materiaaliluettelona. Ecma perusti TC54:n toimitusketjustandardeja varten joulukuussa 2023, ja CycloneDX 1.6:sta tuli ECMA-424 kesäkuussa 2024. Spesifikaation yleiskuvaus ja ECMA-424-sivu ovat ensisijaiset lähteet.
Mitä CycloneDX-SBOM sisältää
CycloneDX-dokumentti on yksi olio, jota kutsutaan yleensä BOM:ksi. Vain kaksi kenttää on pakollisia: bomFormat (aina
"CycloneDX") ja specVersion. Kaikki muu on valinnaista, minkä vuoksi kaksi validia CycloneDX-tiedostoa
voivat erota niin paljon siinä, mitä ne todella kertovat.
| Elementti | Mitä se sisältää |
|---|---|
metadata |
Milloin ja miten BOM tehtiin: aikaleima, työkalut, tekijät, elinkaaren vaihe ja komponentti, jota BOM kuvaa |
components |
Jokainen kirjasto, kehys, kontti, tiedosto, laiteohjelmisto, laite tai malli versioineen, tunnisteineen, tiivisteineen ja lisensseineen |
services |
Ulkoiset palvelut, joita ohjelmisto kutsuu, kuten API:t, päätepisteineen ja tietovirtoineen |
dependencies |
Mikä komponentti tai palvelu riippuu mistäkin, jotta puu voidaan rakentaa uudelleen transitiivisine tasoineen |
compositions |
Kuinka kattava BOM:n kukin osa on: complete, incomplete, unknown tai not specified |
vulnerabilities |
Tunnetut haavoittuvuudet, niiden luokitukset ja VEX:n osalta se, vaikuttavatko ne tuotteeseen ja miten |
formulation |
Miten tuote buildattiin: sen taustalla olevat työnkulut, tehtävät ja ympäristö |
annotations |
BOM:n muihin osiin liitetyt kommentit ja huomautukset sekä tieto siitä, kuka ne teki ja milloin |
declarations, definitions, citations |
Vakuutukset standardien mukaisuudesta, itse standardit ja tieto siitä, mistä BOM:n tiedot ovat peräisin |
Kenttä metadata.lifecycles kertoo, milloin BOM tehtiin: design, pre-build, build, post-build,
operations, discovery tai decommission. Saman tuotteen build-vaiheen SBOM ja buildin jälkeinen skannaus voivat luetella eri
komponentteja, joten vaiheella on merkitystä, kun vertaat kahta tiedostoa.
CycloneDX:n BOM-tyypit
Sama oliomalli kattaa muutakin kuin ohjelmistoja. CycloneDX-projekti luettelee nämä käyttötavat:
| Tyyppi | Kuvaa |
|---|---|
| SBOM | Ohjelmistokomponentit ja niiden riippuvuudet |
| SaaSBOM | Palvelimella ajettavan sovelluksen palvelut, päätepisteet ja tietovirrat |
| HBOM | Laitteistokomponentit |
| CBOM | Kryptografiset resurssit: algoritmit, avaimet, varmenteet ja protokollat |
| ML-BOM | Koneoppimismallit ja niiden taustalla olevat datajoukot |
| OBOM ja MBOM | Käyttöympäristöt sekä tuotteen valmistus |
| VEX, VDR ja BOV | Vaikuttaako haavoittuvuus tuotteeseen (VEX), toimittajan raportti tunnetuista haavoittuvuuksista (VDR) ja haavoittuvuusluettelo (BOV) |
| CDXA | Vakuutukset siitä, että tuote täyttää standardin tai vaatimuksen |
Nämä ovat yhden formaatin käyttötapoja, eivät erillisiä formaatteja. VEX-dokumentti on esimerkiksi CycloneDX-BOM, jonka
vulnerabilities-merkinnöillä on analyysin tila ja jotka osoittavat SBOM:n komponentteihin.
Tunnisteet: purl, CPE ja tiivisteet
Komponentin nimi ei riitä sen yhdistämiseen haavoittuvuuteen, koska sama nimi voi tarkoittaa eri paketteja
eri ekosysteemeissä. CycloneDX-komponenteilla on sitä varten tunnisteita:
package URL (purl), kuten pkg:npm/[email protected], CPE, SWID-tagi,
OmniBOR- ja SWHID-tunnisteet sekä kryptografiset tiivisteet. Purl on se, johon useimmat työkalut vertaavat avoimen lähdekoodin paketteja,
ja siitä tuli oma Ecma-standardinsa, ECMA-427, joulukuussa 2025. Dokumentin sisällä jokaisella elementillä voi myös olla
bom-ref, paikallinen tunniste, jolla dependencies-, compositions- ja vulnerabilities-osiot viittaavat siihen.
CycloneDX JSON -esimerkki
Pieni mutta täydellinen SBOM sovellukselle acme-api, joka käyttää yhtä npm-pakettia, debug,
joka puolestaan riippuu paketista ms. Se validoituu CycloneDX 1.7:n JSON-skeemaa vasten.
{
"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"] }
]
}
-
serialNumberjaversionyksilöivät tämän BOM:n. Jokainen uutena generoitu BOM saa uuden sarjanumeron; kun olemassa olevaa BOM:ia muokataan, se säilyttää sarjanumeronsa ja sen versio kasvaa yhdellä. -
metadata.componenton tuote, jota SBOM kuvaa, ja riippuvuuspuun juuri. -
dependenciestekee paketistamstransitiivisen riippuvuuden: sovellus ei koskaan pyytänyt sitä, vaandebugpyysi. TyhjädependsOnkertoo, ettei komponentilla ole riippuvuuksia. Jos komponentti jätetään pois graafista, sen riippuvuudet ovat tuntemattomia, eikä se tarkoita, ettei niitä ole. -
compositionsilmoittaa, ettäacme-api-sovelluksen alla oleva riippuvuuspuu on täydellinen. Työkalun, joka ei nähnyt kaikkea, pitäisi sen sijaan ilmoittaaincompletetaiunknown, jotta lukija tietää, ettei puuttuvaa pakettia pidä tulkita poissaolevaksi.
Suurempi tiedosto tiivisteineen ja toimittajineen sekä saman sovelluksen vastaava SPDX-versio löytyvät sivulta SBOM-esimerkit.
Miten CycloneDX-SBOM generoidaan
Sellaisen voi tuottaa kolmella tavalla, ja ne kuvaavat eri asioita.
| Menetelmä | Miten se toimii | Mitä siltä jää huomaamatta |
|---|---|---|
| Manifestien ja lukitustiedostojen skannaus | Lukee tiedostot package-lock.json, requirements.txt, pom.xml ja vastaavat |
Kaikki paketinhallinnan ulkopuolelta haettu, kuten asennusskriptit, build-skriptit ja peruskuvat |
| Kuvan, tiedostojärjestelmän tai binäärin analyysi | Tutkii valmiista konttikuvasta, hakemistosta tai binääristä pakettien metatietoja ja tunnisteita | Komponentit, joista ei jäänyt metatietoja, ja käännetty koodi, jota sen täytyy arvailla |
| Tallennus buildin aikana | Tallentaa, mitä buildi todella haki ollessaan käynnissä | Vain sen, mitä tallentaja ei näe, ja hyvä tallentaja ilmoittaa sen puutteelliseksi |
Ilmaiset työkalut, jotka kirjoittavat CycloneDX:ää:
-
cdxgen, OWASP-projekti, monille kielille ja konttikuville:
cdxgen -o bom.json. Se kirjoittaa oletuksena CycloneDX 1.7:ää. -
CycloneDX-ekosysteemien lisäosat, kuten
@cyclonedx/cyclonedx-npm, cyclonedx-python, CycloneDX Maven -lisäosa ja cyclonedx-gomod, kukin yhdelle paketinhallintatyökalulle:npx @cyclonedx/cyclonedx-npm --output-file bom.json. -
Syft, Anchorelta, konttikuville ja tiedostojärjestelmille:
syft <image> -o cyclonedx-json.
CycloneDX:n Tool Center luettelee monia muita. Miten nämä lähestymistavat vertautuvat käytännössä, katso avoimen lähdekoodin SBOM-generaattorit ja Docker-kuvien SBOM:t.
Miten CycloneDX-tiedosto validoidaan
Virallinen CycloneDX CLI tarkistaa tiedoston sen version skeemaa vasten:
cyclonedx validate --input-file bom.json --input-version v1_7 --fail-on-errors
Sama työkalu muuntaa JSONin, XML:n ja Protocol Buffersin välillä, spesifikaation versioiden välillä ja SPDX JSONiksi komennolla
cyclonedx convert. Skeemavalidointi todistaa vain, että tiedosto on hyvin muodostettu. Se ei voi kertoa, puuttuuko
jokin komponentti. Sitä varten tarkista sisältö listaa vasten, kuten
SBOM:n laadun tarkistuslista.
CycloneDX vs. SPDX
SPDX on toinen laajasti käytetty SBOM-formaatti, jota ylläpitää Linux Foundation ja joka on julkaistu standardina ISO/IEC 5962:2021. Se syntyi lisenssien noudattamisesta, kun taas CycloneDX lähti liikkeelle tietoturvasta, minkä vuoksi CycloneDX sisältää haavoittuvuudet ja VEX:n samassa formaatissa. Molemmat kuvaavat komponentteja, tunnisteita, lisenssejä ja suhteita, työkalut muuntavat niiden välillä, eikä EU:n kyberkestävyyssäädös (Cyber Resilience Act, CRA) nimeä kumpaakaan. Se, kumpaa tuotat, riippuu yleensä siitä, mitä asiakkaasi ja työkalusi lukevat. Koko vertailu on sivulla CycloneDX vs. SPDX.
Miten CRACI tuottaa CycloneDX-SBOM:eja
CRACI on GitHub Actions -runneri, joka tallentaa jokaisen paketin, jonka kukin jobi hakee ollessaan käynnissä, riippuvuuspuun jokaisella tasolla ja myös CI-välimuisteista palautetut paketit. Jokainen SBOM:n komponentti oli siis todella mukana buildissa. Jokaisella paketilla on purl ja ilmoitettu lisenssi, ja jokaisen jobin SBOM:lla on kattavuustila, joka kertoo, mitä jobi ei nähnyt. SBOM viedään CycloneDX- tai SPDX-muodossa transitiivisine riippuvuuksineen ja sen komponenteista löydettyine haavoittuvuuksineen, ja API palauttaa sen CycloneDX 1.7 JSONina. Katso buildin aikainen SBOM-generointi tai SBOM:n parhaat käytännöt.
Milloin CRACI ei ole oikea vastaus
- Laitteisto-, kryptografia- tai palvelu-BOM:t. CRACI tallentaa ohjelmistopaketit, jotka buildi hakee. HBOM, CBOM tai SaaSBOM tarvitsee muita lähteitä.
- Buildit GitHub Actionsin ulkopuolella. GitHub Actions on tällä hetkellä ainoa tuettu CI; muut CI-järjestelmät ovat tiekartalla. Käytä sillä välin generaattoria, kuten cdxgeniä.
- Binäärinä saamasi ohjelmistot. Jos et buildannut sitä itse, et voi tallentaa sen buildia. Pyydä toimittajalta SBOM tai käytä binäärianalyysiä.
CycloneDX: usein kysytyt kysymykset
Mihin CycloneDX:ää käytetään?
Enimmäkseen SBOM:eihin: ohjelmiston komponenttien luettelointiin, jotta voit seurata haavoittuvuuksia ja lisenssejä ja jakaa luettelon asiakkaille. Sama formaatti kattaa myös VEX:n, palvelut, laitteiston, kryptografian ja koneoppimismallit.
Kuka ylläpitää CycloneDX:ää?
OWASP Foundation vetää CycloneDX-projektia, ja Ecma Internationalin tekninen komitea 54 julkaisee sen ECMA-424-standardina.
Mikä on CycloneDX:n uusin versio?
CycloneDX 1.7, julkaistu lokakuussa 2025. Se on myös ECMA-424:n 2. painos, joka julkaistiin joulukuussa 2025. 1. painos vastaa CycloneDX 1.6:ta.
Onko CycloneDX JSONia vai XML:ää?
Molempia, ja lisäksi Protocol Buffersia. JSON on yleisin, mediatyyppinä application/vnd.cyclonedx+json ja tiedostoniminä esimerkiksi bom.json tai name.cdx.json.
Onko CycloneDX parempi kuin SPDX?
Kumpikaan ei ole yleisesti parempi. CycloneDX lähti liikkeelle tietoturvasta ja sisältää haavoittuvuudet ja VEX:n natiivisti, SPDX lisenssien noudattamisesta ja on ISO-standardi. Tuota sitä, mitä asiakkaasi ja työkalusi lukevat; muuntimia on kumpaankin suuntaan.
Miten tarkistan, että CycloneDX-tiedosto on validi?
Aja virallinen CycloneDX CLI: cyclonedx validate --input-file bom.json --fail-on-errors. Se tarkistaa rakenteen skeemaa vasten, ei sitä, puuttuuko jokin komponentti.
CycloneDX suoraan buildista
Tallenna jokainen paketti, jonka GitHub Actions -jobisi hakevat, kattavuustilan kanssa ja vie se CycloneDX- tai SPDX-muotoon.
Varaa demo