Generar un CBOM CycloneDX en CI

Un CBOM CycloneDX (cryptographic bill of materials, lista de materiales criptográficos) es un documento CycloneDX cuyos componentes describen activos criptográficos: algoritmos, protocolos, certificados y material de claves. Generarlo en integración continua es sobre todo una cuestión de fontanería: ejecutar detectores sobre el código fuente, las dependencias, las imágenes de contenedor y los endpoints de prueba, fusionar los resultados en un único documento CycloneDX 1.6, validarlo contra el esquema y, después, almacenarlo y compararlo con el build anterior. La parte difícil es ser honesto sobre lo que un pipeline de build puede ver realmente. Para el concepto en sí, empiece por nuestra introducción al CBOM.

Dónde residen los activos criptográficos en el modelo CycloneDX 1.6

CycloneDX 1.6 introdujo el tipo de componente cryptographic-asset. Cada uno de estos componentes incluye un objeto cryptoProperties, y su campo assetType determina qué grupo de propiedades se aplica. Existen cuatro tipos de activo.

Otros dos campos hacen el verdadero trabajo de inventario. El campo oid vincula un algoritmo a su identificador de objeto cuando se conoce. Y en el array dependencies, el campo provides indica que un componente de software implementa un activo criptográfico. Así es como un CBOM responde a la pregunta que realmente formula un auditor: ¿qué aplicación utiliza este algoritmo, y dónde?

{
  "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"] }
  ]
}

ML-KEM es el mecanismo de encapsulación de claves normalizado en NIST FIPS 203; su conjunto de parámetros 768 corresponde a la categoría 3 de seguridad cuántica del NIST. Los componentes de protocolo son donde aparecen los grupos híbridos de intercambio de claves, por ejemplo X25519MLKEM768, cuyo codepoint 0x11EC figura en el registro de parámetros TLS de la IANA.

Detección estática frente a comportamiento observado

Un job de CI ve un repositorio, un lockfile y una imagen. No ve un handshake negociado. Tratar ambas cosas como si fueran lo mismo es la forma más habitual de que un CBOM resulte engañoso.

Deje constancia de la diferencia en el documento. Mantenga los hechos derivados estáticamente en el propio componente, con la ruta del archivo en las ocurrencias de evidencia del componente, y mantenga los hechos medidos en protocolProperties y certificateProperties, generados por un job de sondeo. Rellene siempre metadata.tools para que el lector sepa qué detector ha afirmado qué.

Esquema de un pipeline

1. Declarar el alcance

Antes de ejecutar cualquier herramienta, decida qué cubre un CBOM: un componente desplegable, una versión, un entorno. Un único archivo que describe doce servicios envejece mal y no se puede comparar de forma útil.

2. Recopilar en paralelo

1. Análisis del código fuente y de las dependencias: un analizador estático sobre el repositorio y los lockfiles, que emite activos de tipo algoritmo con la ubicación de la evidencia.
2. Análisis de la imagen o del sistema de archivos: inspeccionar el artefacto generado en busca de bibliotecas criptográficas, paquetes de certificados, keystores y archivos de configuración.
3. Sondeo de endpoints observados: únicamente contra staging, para confirmar lo que realmente se negocia.

# 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

El algoritmo mlkem768x25519-sha256 se añadió en OpenSSH 9.9 y pasó a ser el acuerdo de claves por defecto en OpenSSH 10.0, según las notas de versión de OpenSSH. Sondee staging, nunca producción, y mantenga un respaldo clásico como X25519 después del grupo híbrido en cada configuración de servidor que modifique.

3. Fusionar, sellar y validar

Fusione los documentos parciales en uno solo y haga fallar el job si el resultado no es válido según el esquema. La CLI de CycloneDX hace ambas cosas.

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

Selle metadata.timestamp, la versión del componente y el SHA del commit. Un CBOM sin procedencia es una opinión.

Almacenar y comparar el CBOM

Publique el archivo como artefacto de build para la trazabilidad y conserve una copia normalizada por componente en un repositorio dedicado o en un servidor de BOM, de modo que el historial se pueda consultar. La normalización importa más que el almacenamiento: ordene los componentes, utilice valores bom-ref estables que no contengan el número de build y excluya la marca de tiempo de la comparación. De lo contrario, cada build parecerá un cambio.

# 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

A continuación, decida qué significa una diferencia. Controles útiles, en orden de gravedad creciente: aparece un activo nuevo que ningún build anterior declaraba; aparece un algoritmo de clave pública vulnerable a la computación cuántica en un componente que antes no tenía ninguno; aparece en cualquier lugar un grupo preestándar obsoleto, como un grupo TLS de borrador de Kyber; desaparece un grupo híbrido de un servicio que lo tenía. Empiece emitiendo avisos, no fallos, hasta comprender el ruido de los detectores. Esta comparación es la parte medible de la agilidad criptográfica: muestra si su superficie criptográfica cambia de forma intencionada o por accidente.

Límites que conviene dejar por escrito

• La cobertura es desigual según el lenguaje y el ecosistema. Un detector que lee bien un lenguaje puede estar ciego en otro. Deje constancia de lo que no se ha analizado.
• Los hallazgos estáticos son posibilidades, no uso. Que una biblioteca admita RSA no significa que se utilice RSA. Incluya una nota de confianza en las propiedades del componente en lugar de dar a entender una certeza.
• La configuración resuelta en tiempo de ejecución es invisible. Las variables de entorno, los gestores de secretos, las service meshes y los proxies inversos pueden anular todo lo que dice el repositorio.
• Los identificadores de objeto están incompletos. Para algoritmos recientes, el campo oid puede simplemente no estar disponible; déjelo vacío en lugar de adivinarlo.
• Duplicados en la fusión. Dos detectores que nombran el mismo algoritmo de forma distinta producen dos componentes, salvo que su esquema de bom-ref sea determinista.
• No incluye un modelo de gravedad. CycloneDX describe activos; el juicio sobre qué es vulnerable a la computación cuántica le corresponde a usted, o a una referencia como nuestras páginas de algoritmos.

Qué acredita un CBOM generado en CI

Varios textos exigen un inventario de la criptografía en uso. El requisito 12.3.3 de PCI DSS v4.0.1 exige que las suites de cifrado y los protocolos en uso se documenten y revisen al menos cada 12 meses, incluido dónde se utilizan y una estrategia documentada ante cambios previstos en las vulnerabilidades criptográficas, y es obligatorio desde el 31 de marzo de 2025 (biblioteca de documentos del PCI SSC). DORA, mediante el Reglamento Delegado (UE) 2024/1774 de la Comisión, exige en su artículo 6 una política de cifrado con disposiciones para actualizar o cambiar la tecnología criptográfica a medida que evoluciona el criptoanálisis, y en su artículo 7 la gestión de claves a lo largo de todo su ciclo de vida, además de un registro de certificados para los activos de TIC que respaldan funciones críticas o importantes (EUR-Lex). Para las agencias federales de EE. UU., el memorando OMB M-26-15 exige un inventario criptográfico automatizado y actualizado de forma continua (M-26-15). La hoja de ruta de implementación coordinada de la UE v1.1 incluye un inventario criptográfico entre los primeros pasos antes de finales de 2026, como orientación coordinada para los Estados miembros y no como un reglamento vinculante para las empresas.

Nuestra interpretación, claramente identificada como tal: ninguno de estos textos menciona CycloneDX, y un CBOM es una forma práctica de elaborar y mantener dicho inventario, no un formato obligatorio. Genere el archivo porque abarata la próxima decisión de migración y, después, vincúlelo a la obligación que corresponda. Esto es información, no asesoramiento jurídico.

Siguiente paso: contrastar el CBOM con la realidad

Un CBOM generado en CI le indica lo que contiene su build. No puede indicarle lo que negocian sus servidores. Cierre esa brecha probando los propios endpoints: analice su dominio con PQC Status para ver los grupos híbridos ML-KEM, las versiones de TLS y la cadena de certificados que se ofrecen realmente a un cliente, e incorpore después esos valores observados a protocolProperties y certificateProperties de su próximo CBOM, para que el documento refleje tanto el código como el comportamiento.