SBOM
O que é o CycloneDX?
O CycloneDX é uma norma aberta para listas de materiais, gerida pela OWASP Foundation e publicada pela Ecma International como ECMA-424. É conhecido sobretudo como formato de SBOM: uma lista legível por máquina dos componentes de um software, de como dependem uns dos outros e do que se sabe sobre as suas vulnerabilidades. A versão atual é o CycloneDX 1.7, e o mesmo formato descreve também serviços, hardware, criptografia e modelos de machine learning.
Atualizado a
O CycloneDX num relance
| Mantido por | O projeto CycloneDX da OWASP Foundation, com o Comité Técnico 54 (TC54) da Ecma International |
|---|---|
| Norma | ECMA-424. A 1.ª edição (junho de 2024) corresponde ao CycloneDX 1.6; a 2.ª edição (dezembro de 2025) ao CycloneDX 1.7 |
| Versão atual | CycloneDX 1.7, lançado em outubro de 2025 |
| Codificações | JSON, XML e Protocol Buffers |
| Media type | application/vnd.cyclonedx+json, com um parâmetro de versão como version=1.7 |
| Nomes de ficheiros | bom.json, bom.xml, *.cdx.json, *.cdx.xml |
A primeira versão, o CycloneDX 1.0, saiu em 2018 como uma lista de materiais focada na segurança. A Ecma criou o TC54 para normas da cadeia de abastecimento em dezembro de 2023, e o CycloneDX 1.6 tornou-se a ECMA-424 em junho de 2024. A visão geral da especificação e a página da ECMA-424 são as referências principais.
O que contém uma SBOM CycloneDX
Um documento CycloneDX é um único objeto, normalmente chamado BOM. Só dois campos são obrigatórios, bomFormat (sempre
"CycloneDX") e specVersion. Tudo o resto é opcional, e é por isso que dois ficheiros CycloneDX válidos
podem diferir tanto naquilo que efetivamente lhe dizem.
| Elemento | O que contém |
|---|---|
metadata |
Quando e como a BOM foi criada: carimbo temporal, ferramentas, autores, a fase do ciclo de vida e o componente que a BOM descreve |
components |
Cada biblioteca, framework, contentor, ficheiro, firmware, dispositivo ou modelo, com a respetiva versão, identificadores, hashes e licenças |
services |
Serviços externos que o software chama, como APIs, com os respetivos endpoints e fluxos de dados |
dependencies |
Que componente ou serviço depende de qual, para que a árvore possa ser reconstruída, incluindo os níveis transitivos |
compositions |
Quão completa está cada parte da BOM: completa, incompleta, desconhecida ou não especificada |
vulnerabilities |
Vulnerabilidades conhecidas, as suas classificações e, para VEX, se e como afetam o produto |
formulation |
Como o produto foi construído: os workflows, as tarefas e o ambiente por trás dele |
annotations |
Comentários e notas associados a outras partes da BOM, com quem os fez e quando |
declarations, definitions, citations |
Atestações de conformidade com normas, as próprias normas e a origem dos dados da BOM |
O campo metadata.lifecycles indica quando a BOM foi criada: design, pre-build, build, post-build,
operations, discovery ou decommission. Uma SBOM da fase de build e uma análise pós-build do mesmo produto podem listar componentes
diferentes, pelo que a fase importa quando compara dois ficheiros.
Tipos de BOM do CycloneDX
O mesmo modelo de objetos abrange mais do que software. O projeto CycloneDX lista estas capacidades:
| Tipo | Descreve |
|---|---|
| SBOM | Componentes de software e as suas dependências |
| SaaSBOM | Serviços, endpoints e fluxos de dados de uma aplicação alojada |
| HBOM | Componentes de hardware |
| CBOM | Ativos criptográficos: algoritmos, chaves, certificados e protocolos |
| ML-BOM | Modelos de machine learning e os conjuntos de dados por trás deles |
| OBOM e MBOM | Ambientes operacionais e o fabrico de um produto |
| VEX, VDR e BOV | Se uma vulnerabilidade afeta um produto (VEX), o relatório de um fornecedor sobre vulnerabilidades conhecidas (VDR) e uma lista de vulnerabilidades (BOV) |
| CDXA | Atestações de que um produto cumpre uma norma ou um requisito |
São utilizações de um único formato, não formatos separados. Um documento VEX, por exemplo, é uma BOM CycloneDX cujas
entradas vulnerabilities têm um estado de análise e apontam para componentes de uma SBOM.
Identificadores: purl, CPE e hashes
O nome de um componente não chega para o associar a uma vulnerabilidade, porque o mesmo nome pode designar pacotes diferentes em
ecossistemas diferentes. Os componentes CycloneDX têm identificadores para isso: um
package URL (purl) como pkg:npm/[email protected], um CPE, uma tag SWID,
identificadores OmniBOR e SWHID, e hashes criptográficos. O purl é o identificador que a maioria das ferramentas usa para pacotes open source,
e tornou-se uma norma Ecma própria, a ECMA-427, em dezembro de 2025. Dentro do documento, cada elemento pode também ter um
bom-ref, um ID local que as secções de dependências, composições e vulnerabilidades usam para apontar para ele.
Um exemplo JSON de CycloneDX
Uma SBOM pequena mas completa para uma aplicação, acme-api, que usa um pacote npm, debug,
que por sua vez depende de ms. É válida face ao schema JSON do 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"] }
]
}
-
serialNumbereversionidentificam esta BOM. Cada BOM gerada de novo recebe um novo número de série; quando uma BOM existente é modificada, mantém o número de série e a sua versão sobe uma unidade. -
metadata.componenté o produto que a SBOM descreve e a raiz da árvore de dependências. -
dependenciesfaz demsuma dependência transitiva: a aplicação nunca a pediu, foi odebugque a pediu. UmdependsOnvazio indica que o componente não tem dependências. Deixar um componente fora do grafo significa que as suas dependências são desconhecidas, não que não as tem. -
compositionsdeclara que a árvore de dependências sobacme-apiestá completa. Uma ferramenta que não conseguiu ver tudo deve indicar antesincompleteouunknown, para que quem lê saiba que não deve tratar um pacote em falta como ausente.
Para um ficheiro maior, com hashes, fornecedores e uma versão SPDX correspondente da mesma aplicação, consulte exemplos de SBOM.
Como gerar uma SBOM CycloneDX
Há três formas de a produzir, e descrevem coisas diferentes.
| Método | Como funciona | O que lhe escapa |
|---|---|---|
| Análise de manifestos e lockfiles | Lê package-lock.json, requirements.txt, pom.xml e ficheiros semelhantes |
Tudo o que é obtido fora do gestor de pacotes, como scripts de instalação, scripts de build e imagens base |
| Análise de imagens, sistemas de ficheiros ou binários | Inspeciona uma imagem de contentor, um diretório ou um binário já concluído em busca de metadados e assinaturas de pacotes | Componentes que não deixaram metadados e código compilado que tem de adivinhar |
| Registo durante o build | Regista o que o build efetivamente obteve enquanto é executado | Apenas o que o registo não consegue ver, que uma boa ferramenta indica como incompleto |
Ferramentas gratuitas que escrevem CycloneDX:
-
cdxgen, um projeto OWASP, para muitas linguagens e imagens de contentores:
cdxgen -o bom.json. Escreve CycloneDX 1.7 por predefinição. -
Os plugins do ecossistema CycloneDX, como
@cyclonedx/cyclonedx-npm, cyclonedx-python, o plugin CycloneDX para Maven e cyclonedx-gomod, cada um para um gestor de pacotes:npx @cyclonedx/cyclonedx-npm --output-file bom.json. -
Syft, da Anchore, para imagens de contentores e sistemas de ficheiros:
syft <image> -o cyclonedx-json.
O Tool Center do CycloneDX lista muitas mais. Para saber como estas abordagens se comparam na prática, consulte geradores de SBOM open source e SBOM de imagens Docker.
Como validar um ficheiro CycloneDX
A CycloneDX CLI oficial verifica um ficheiro face ao schema da sua versão:
cyclonedx validate --input-file bom.json --input-version v1_7 --fail-on-errors
A mesma ferramenta converte entre JSON, XML e Protocol Buffers, entre versões da especificação e para SPDX JSON, com
cyclonedx convert. A validação do schema apenas prova que o ficheiro está bem formado. Não lhe diz se falta
algum componente. Para isso, verifique o conteúdo face a uma lista como a
checklist de qualidade de SBOM.
CycloneDX vs SPDX
O SPDX é o outro formato de SBOM amplamente usado, alojado pela Linux Foundation e publicado como ISO/IEC 5962:2021. Nasceu da conformidade de licenças, enquanto o CycloneDX começou pela segurança, e é por isso que o CycloneDX inclui vulnerabilidades e VEX no mesmo formato. Ambos descrevem componentes, identificadores, licenças e relações, há ferramentas que convertem entre eles, e o Cyber Resilience Act da UE não nomeia nenhum dos dois. O formato que produz depende normalmente do que os seus clientes e ferramentas leem. A comparação completa está em CycloneDX vs SPDX.
Como o CRACI produz SBOM CycloneDX
O CRACI é um runner de GitHub Actions que regista cada pacote que cada job obtém enquanto é executado, a qualquer profundidade da árvore de dependências e incluindo pacotes restaurados de caches de CI. Assim, cada componente da SBOM esteve efetivamente no build. Cada pacote leva o seu purl e a sua licença declarada, e a SBOM de cada job tem um estado de completude que indica o que o job não conseguiu ver. A SBOM é exportada em CycloneDX ou SPDX, com as dependências transitivas e as vulnerabilidades encontradas nos seus componentes, e a API devolve-a como JSON CycloneDX 1.7. Consulte geração de SBOM durante o build ou boas práticas de SBOM.
Quando o CRACI não é a resposta
- BOM de hardware, criptografia ou serviços. O CRACI regista os pacotes de software que um build obtém. Uma HBOM, CBOM ou SaaSBOM precisa de outras fontes.
- Builds fora do GitHub Actions. O GitHub Actions é hoje o único CI suportado; outros sistemas de CI estão no roadmap. Entretanto, use um gerador como o cdxgen.
- Software que recebe como binário. Se não o compilou, não pode registar o seu build. Peça ao fornecedor uma SBOM ou use a análise de binários.
CycloneDX: perguntas frequentes
Para que serve o CycloneDX?
Sobretudo para SBOM: listar os componentes de um software para poder acompanhar vulnerabilidades e licenças e partilhar a lista com clientes. O mesmo formato abrange também VEX, serviços, hardware, criptografia e modelos de machine learning.
Quem mantém o CycloneDX?
A OWASP Foundation gere o projeto CycloneDX, e o Comité Técnico 54 da Ecma International publica-o como norma ECMA-424.
Qual é a versão mais recente do CycloneDX?
O CycloneDX 1.7, lançado em outubro de 2025. É também a 2.ª edição da ECMA-424, publicada em dezembro de 2025. A 1.ª edição corresponde ao CycloneDX 1.6.
O CycloneDX é JSON ou XML?
Ambos, e também Protocol Buffers. O JSON é o mais comum, com o media type application/vnd.cyclonedx+json e nomes de ficheiros como bom.json ou name.cdx.json.
O CycloneDX é melhor do que o SPDX?
Nenhum é melhor em termos gerais. O CycloneDX começou pela segurança e inclui nativamente vulnerabilidades e VEX; o SPDX começou pela conformidade de licenças e é uma norma ISO. Produza o que os seus clientes e ferramentas leem; existem conversores nos dois sentidos.
Como verifico se um ficheiro CycloneDX é válido?
Execute a CycloneDX CLI oficial: cyclonedx validate --input-file bom.json --fail-on-errors. Verifica a estrutura face ao schema, não se falta algum componente.
CycloneDX a partir do próprio build
Registe cada pacote que os seus jobs de GitHub Actions obtêm, com um estado de completude, e exporte-o em CycloneDX ou SPDX.
Marcar demo