Gerar um CBOM CycloneDX no CI

Um CBOM CycloneDX (cryptographic bill of materials, ou lista de materiais criptográficos) é um documento CycloneDX cujos componentes descrevem ativos criptográficos: algoritmos, protocolos, certificados e material de chave. Gerar um CBOM em integração contínua é sobretudo trabalho de integração: executar detectores sobre o código-fonte, as dependências, as imagens de contêiner e os endpoints de teste, mesclar os resultados em um único documento CycloneDX 1.6, validá-lo contra o schema e, em seguida, armazená-lo e compará-lo com o build anterior. A parte difícil é ser honesto sobre o que um pipeline de build realmente consegue ver. Para o conceito em si, comece pela nossa introdução ao CBOM.

Onde ficam os ativos criptográficos no modelo CycloneDX 1.6

O CycloneDX 1.6 introduziu o tipo de componente cryptographic-asset. Cada componente desse tipo traz um objeto cryptoProperties, e o campo assetType desse objeto determina qual grupo de propriedades se aplica. Existem quatro tipos de ativo.

Dois outros campos fazem o verdadeiro trabalho de inventário. O campo oid vincula um algoritmo ao seu identificador de objeto, quando você o conhece. E, no array dependencies, o campo provides indica que um componente de software implementa um ativo criptográfico. É assim que um CBOM responde à pergunta que um auditor realmente faz: qual aplicação usa este algoritmo, e onde?

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "serialNumber": "urn:uuid:4e1e1f2a-0000-0000-0000-000000000000",
  "version": 1,
  "metadata": {
    "timestamp": "2026-10-19T06:12:00Z",
    "component": {
      "type": "application",
      "bom-ref": "payments-api@1.42.0",
      "name": "payments-api",
      "version": "1.42.0"
    }
  },
  "components": [
    {
      "type": "cryptographic-asset",
      "bom-ref": "crypto/algorithm/ml-kem-768",
      "name": "ML-KEM-768",
      "cryptoProperties": {
        "assetType": "algorithm",
        "algorithmProperties": {
          "primitive": "kem",
          "parameterSetIdentifier": "768",
          "cryptoFunctions": ["keygen", "encapsulate", "decapsulate"],
          "nistQuantumSecurityLevel": 3
        }
      }
    },
    {
      "type": "cryptographic-asset",
      "bom-ref": "crypto/protocol/tls-1.3",
      "name": "TLS 1.3",
      "cryptoProperties": {
        "assetType": "protocol",
        "protocolProperties": {
          "type": "tls",
          "version": "1.3",
          "cipherSuites": [
            { "name": "TLS_AES_256_GCM_SHA384", "identifiers": ["0x13", "0x02"] }
          ],
          "cryptoRefArray": ["crypto/algorithm/ml-kem-768"]
        }
      }
    }
  ],
  "dependencies": [
    { "ref": "payments-api@1.42.0", "provides": ["crypto/protocol/tls-1.3"] }
  ]
}

O ML-KEM é o mecanismo de encapsulamento de chaves padronizado no NIST FIPS 203; seu conjunto de parâmetros 768 corresponde à categoria 3 de segurança quântica do NIST. É nos componentes de protocolo que aparecem os grupos híbridos de troca de chaves, por exemplo o X25519MLKEM768, cujo codepoint 0x11EC consta do registro de parâmetros TLS da IANA.

Detecção estática versus comportamento observado

Um job de CI vê um repositório, um lockfile e uma imagem. Ele não vê um handshake negociado. Tratar as duas coisas como equivalentes é a forma mais comum de um CBOM se tornar enganoso.

Registre essa diferença no documento. Mantenha os fatos derivados estaticamente no próprio componente, com o caminho do arquivo nas ocorrências de evidência do componente, e mantenha os fatos medidos em protocolProperties e certificateProperties produzidos por um job de sondagem. Sempre preencha metadata.tools, para que o leitor saiba qual detector fez qual afirmação.

Esboço de um pipeline

1. Declare o escopo

Antes de executar qualquer ferramenta, decida o que um CBOM abrange: um componente implantável, uma versão, um ambiente. Um único arquivo que descreve doze serviços envelhece mal e não pode ser comparado de forma útil.

2. Colete em paralelo

1. Varredura de código-fonte e dependências: um analisador estático executado sobre o repositório e os lockfiles, que emite ativos de algoritmo com a localização das evidências.
2. Varredura de imagem ou sistema de arquivos: inspecione o artefato gerado em busca de bibliotecas criptográficas, pacotes de certificados, keystores e arquivos de configuração.
3. Sondagem de endpoints observados: apenas contra o ambiente de staging, confirme o que é realmente negociado.

# TLS: does the staging endpoint negotiate a hybrid group?
# requires OpenSSL 3.5 or later for the ML-KEM groups
openssl s_client -connect staging.example.com:443 \
  -groups X25519MLKEM768 </dev/null | grep "Negotiated TLS1.3 group"

# SSH: which key agreement algorithms does this client build support?
ssh -Q kex

# SSH: confirm the server accepts the post-quantum hybrid key agreement
ssh -o KexAlgorithms=mlkem768x25519-sha256 -o BatchMode=yes \
  git@staging.example.com true

O algoritmo mlkem768x25519-sha256 foi adicionado no OpenSSH 9.9 e se tornou o acordo de chaves padrão no OpenSSH 10.0, segundo as notas de versão do OpenSSH. Sonde o staging, nunca a produção, e mantenha um fallback clássico, como X25519, após o grupo híbrido em toda configuração de servidor que você alterar.

3. Mescle, carimbe e valide

Mescle os documentos parciais em um só e faça o job falhar se o resultado não for válido em relação ao schema. A CycloneDX CLI faz as duas coisas.

cyclonedx merge \
  --input-files static.cbom.json image.cbom.json observed.cbom.json \
  --output-file cbom.json

cyclonedx validate --input-file cbom.json --fail-on-errors

Registre metadata.timestamp, a versão do componente e o SHA do commit. Um CBOM sem procedência é uma opinião.

Armazenar e comparar o CBOM

Publique o arquivo como artefato de build para fins de rastreabilidade e mantenha uma cópia normalizada por componente em um repositório dedicado ou em um servidor de BOM, para que o histórico possa ser consultado. A normalização importa mais do que o armazenamento: ordene os componentes, use valores de bom-ref estáveis que não contenham o número do build e exclua o timestamp do diff. Caso contrário, todo build parecerá uma mudança.

# extract a stable, sorted view of the cryptographic assets
jq -S '[.components[]
       | select(.type == "cryptographic-asset")
       | {name, assetType: .cryptoProperties.assetType,
          primitive: .cryptoProperties.algorithmProperties.primitive}]
       | sort_by(.name)' cbom.json > current.view.json

diff -u previous.view.json current.view.json

Em seguida, decida o que uma diferença significa. Gates úteis, em ordem crescente de severidade: surge um novo ativo que nenhum build anterior declarava; um algoritmo de chave pública vulnerável à computação quântica aparece em um componente que antes não tinha nenhum; um grupo pré-padrão obsoleto, como um grupo TLS Kyber em versão draft, aparece em qualquer lugar; um grupo híbrido desaparece de um serviço que o utilizava. Comece emitindo alertas, e não falhas, até entender o ruído dos detectores. Esse diff é a parte mensurável da agilidade criptográfica: ele mostra se a sua superfície criptográfica muda de propósito ou por acidente.

Limites que vale a pena documentar

• A cobertura é desigual conforme a linguagem e o ecossistema. Um detector que lê bem uma linguagem pode ser cego em outra. Registre o que não foi analisado.
• Achados estáticos são possibilidades, não uso. O fato de uma biblioteca suportar RSA não significa que RSA seja usado. Mantenha uma nota de confiança nas propriedades do componente em vez de sugerir certeza.
• A configuração resolvida em tempo de execução é invisível. Variáveis de ambiente, gerenciadores de segredos, service meshes e proxies reversos podem sobrepor tudo o que o repositório diz.
• Os identificadores de objeto são incompletos. Para algoritmos recentes, o campo oid pode simplesmente não estar disponível; deixe-o vazio em vez de tentar adivinhar.
• Duplicatas na mesclagem. Dois detectores que nomeiam o mesmo algoritmo de forma diferente produzem dois componentes, a menos que o seu esquema de bom-ref seja determinístico.
• Não há modelo de severidade embutido. O CycloneDX descreve ativos; o julgamento sobre o que é vulnerável à computação quântica cabe a você, ou a uma referência como as nossas páginas de algoritmos.

O que um CBOM gerado no CI comprova

Vários textos exigem um inventário da criptografia em uso. O requisito 12.3.3 do PCI DSS v4.0.1 pede que as cipher suites e os protocolos em uso sejam documentados e revisados pelo menos a cada 12 meses, incluindo onde são usados e uma estratégia documentada para mudanças previstas nas vulnerabilidades criptográficas, e é obrigatório desde 31 de março de 2025 (biblioteca de documentos do PCI SSC). O DORA, por meio do Regulamento Delegado (UE) 2024/1774 da Comissão, exige no Artigo 6 uma política de criptografia com disposições para atualizar ou alterar a tecnologia criptográfica à medida que a criptoanálise evolui e, no Artigo 7, a gestão de chaves ao longo de todo o ciclo de vida, além de um registro de certificados para os ativos de TIC que suportam funções críticas ou importantes (EUR-Lex). Para as agências federais dos EUA, o OMB M-26-15 pede um inventário criptográfico automatizado e continuamente atualizado (M-26-15). O EU Coordinated Implementation Roadmap v1.1 inclui um inventário criptográfico entre os primeiros passos até o final de 2026, como orientação coordenada para os Estados-Membros, e não como um regulamento vinculante para as empresas.

Nossa interpretação, claramente identificada como tal: nenhum desses textos menciona o CycloneDX, e um CBOM é uma forma prática de produzir e manter esse inventário, não um formato obrigatório. Gere o arquivo porque ele torna a próxima decisão de migração mais barata e, depois, relacione-o à obrigação aplicável. Isto é informação, não aconselhamento jurídico.

Próximo passo: compare o CBOM com a realidade

Um CBOM gerado no CI informa o que o seu build contém. Ele não pode informar o que os seus servidores negociam. Feche essa lacuna testando os próprios endpoints: analise o seu domínio com o PQC Status para ver os grupos híbridos ML-KEM, as versões de TLS e a cadeia de certificados efetivamente oferecidos a um cliente e, em seguida, reinsira esses valores observados nas protocolProperties e certificateProperties do seu próximo CBOM, para que o documento reflita tanto o código quanto o comportamento.