Crear una AI BOM con CycloneDX: registrar y validar modelos y datos
Yuta Matsuyama
Investigador de seguridad, TECHFUND Inc.
Actualizado:
Para quién es: Para desarrolladores de aplicaciones de IA y responsables de infraestructura de ML y seguridad. Información a fecha del 13 de noviembre de 2026.
Respuesta práctica
Primero, identifique el modelo y los conjuntos de datos para los que haya podido verificar la evidencia, y regístrelos como componentes de CycloneDX. Además de validar el formato, compruebe por separado si hay ID duplicados, referencias rotas y discrepancias entre la información registrada y la configuración real. Que una AI BOM supere la validación no garantiza, por sí solo, que sea completa o segura.
Decida primero qué registrar
Por ejemplo, en una aplicación interna de preguntas y respuestas, compruebe, según su objetivo, el nombre y la versión del modelo, el proveedor, los datos utilizados para la evaluación, las dependencias de software, el entorno de uso y las personas responsables. Aquí presentamos un ejemplo mínimo que expresa la relación entre un modelo y sus datos de evaluación. No abarca la configuración de toda la aplicación.
La especificación CycloneDX permite representar los modelos con el tipo de componente machine-learning-model y los datos con el tipo data. En la modelCard del modelo se pueden registrar, entre otras cosas, referencias a conjuntos de datos verificados. Los ejemplos oficiales de modelos y conjuntos de datos de CycloneDX sirven de referencia para relacionarlos. Que el formato incluya un campo no significa que su valor esté realmente disponible.
Empiece registrando dos componentes ficticios
Guarde lo siguiente como ai-bom.json. El nombre del modelo, las versiones y el nombre de los datos son ficticios. Este ejemplo parte del supuesto de que un modelo ficticio utilizó datos de evaluación ficticios. No se han verificado el contenido de los datos, los datos de entrenamiento, las licencias ni los proveedores, por lo que no se incluyen. La omisión no significa que algo no exista.
bom-ref es el valor que identifica un componente dentro del documento. El ref de modelCard.modelParameters.datasets apunta a dataset-1. Definir los datos como un componente independiente y referenciarlo, en lugar de limitarse a describirlos en texto dentro de modelCard, facilita la comprobación de la relación.
{
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"version": 1,
"components": [
{
"type": "machine-learning-model",
"bom-ref": "model-1",
"name": "fictional-model",
"version": "1.0",
"modelCard": {
"modelParameters": {
"datasets": [{ "ref": "dataset-1" }]
}
}
},
{
"type": "data",
"bom-ref": "dataset-1",
"name": "fictional-evaluation-data",
"version": "1.0",
"data": [{ "type": "dataset" }]
}
]
}Valide el formato y compruebe también las referencias
El comando validate de CycloneDX CLI permite validar el formato de un archivo especificado. El siguiente ejemplo utiliza CLI 0.33.1. El 13 de noviembre de 2026 utilizamos esa versión en macOS arm64 y confirmamos que el JSON del ejemplo superaba la validación. --input-version v1_6 especifica que se trata de un archivo de la versión 1.6, y --fail-on-errors configura una salida con un código distinto de cero si se producen errores de validación.
Los dos experimentos siguientes prueban qué ocurre al cambiar el destino de una referencia por un ID inexistente y al duplicar el bom-ref de dos componentes. En nuestro mismo entorno, ambos mostraron «BOM validated successfully.» y devolvieron el código de salida 0. La especificación CycloneDX exige que bom-ref sea único dentro del documento. No se base únicamente en que la validación del formato haya sido satisfactoria: compruebe por separado que los destinos de las referencias existan y que los ID sean únicos. Estos resultados son observaciones de CLI 0.33.1 con las entradas mostradas, no conclusiones sobre otros validadores ni sobre versiones futuras.
cyclonedx-cli --version
cyclonedx-cli validate --input-file ai-bom.json --input-format json --input-version v1_6 --fail-on-errors
# 架空のデータ参照を存在しないIDに変更
python3 -c 'import json; d=json.load(open("ai-bom.json")); d["components"][0]["modelCard"]["modelParameters"]["datasets"][0]["ref"]="missing-reference"; print(json.dumps(d))' > dangling.json
cyclonedx-cli validate --input-file dangling.json --input-format json --input-version v1_6 --fail-on-errors
# 架空のデータIDをモデルIDと重複させる
python3 -c 'import json; d=json.load(open("ai-bom.json")); d["components"][1]["bom-ref"]="model-1"; print(json.dumps(d))' > duplicate.json
cyclonedx-cli validate --input-file duplicate.json --input-format json --input-version v1_6 --fail-on-errorsComprobar los ID y las referencias de este ejemplo
Guarde el siguiente script breve como check-example.py y ejecútelo con python3 check-example.py ai-bom.json. Ejecute también el mismo comando con dangling.json y duplicate.json, creados en el experimento anterior: mostrarán missing-reference y un duplicado de model-1, respectivamente, y ambos devolverán el código de salida 1. En el ejemplo válido, ambos resultados están vacíos y el código de salida es 0.
Este código es meramente ilustrativo y solo abarca la estructura de este ejemplo ficticio. Únicamente comprueba los ID bom-ref de los componentes de primer nivel situados directamente en components y si las referencias de datasets en modelCard apuntan a ID existentes. No valida los tipos de los destinos, los componentes anidados, BOM-Link, otros formatos de referencia ni la exactitud de los datos reales. En sistemas reales, realice comprobaciones adicionales con métodos adecuados para la estructura y la especificación correspondientes.
import collections
import json
import sys
data = json.load(open(sys.argv[1], encoding="utf-8"))
components = data.get("components", [])
ids = [item["bom-ref"] for item in components if "bom-ref" in item]
duplicates = [key for key, count in collections.Counter(ids).items() if count > 1]
refs = [
dataset["ref"]
for item in components
for dataset in item.get("modelCard", {}).get("modelParameters", {}).get("datasets", [])
if "ref" in dataset
]
missing = [ref for ref in refs if ref not in ids]
print("duplicates:", duplicates, "missing:", missing)
sys.exit(1 if duplicates or missing else 0)Distinga entre «registrado» y «correcto»
En una AI BOM de uso real, contraste los identificadores y las versiones de los modelos con la configuración y los registros de uso, e incluya las relaciones con los datos de evaluación cuando pueda verificar la evidencia, como las fichas de modelo o los registros de los trabajos de evaluación. Gestione por separado lo que indican las fichas de modelo de proveedores externos y los hechos que haya observado directamente. Si los datos de entrenamiento no son públicos, no deduzca que no existen: déjelos como no verificados en una hoja de seguimiento o un ticket independiente y consulte al proveedor.
El análisis estático del repositorio por sí solo puede pasar por alto modelos externos seleccionados mediante variables de entorno o enrutamiento en tiempo de ejecución. Contraste la configuración con los registros de uso y defina quién actualizará la BOM y qué desencadenará la actualización cuando cambien las versiones o los destinos de servicio. No es necesario incluir directamente prompts confidenciales ni datos de usuarios en una BOM destinada a compartirse.
Antes de incorporarla a las operaciones
Una vez comprobados el formato y las referencias del primer caso, amplíe gradualmente el alcance a las aplicaciones, dependencias de software, servicios externos y demás elementos necesarios. Aunque utilice una herramienta de generación, compruebe qué detecta y qué pasa por alto en relación con el repositorio y las operaciones en cuestión. Un artículo relacionado trata la selección de herramientas para integrarlas en un pipeline de DevSecOps existente.
Preguntas frecuentes
¿Está terminada una AI BOM si su JSON supera la validación?
No. Además de la sintaxis y la conformidad con la especificación, compruebe por separado la coherencia de los ID y las referencias, la evidencia que respalda la información registrada y su correspondencia con la configuración que realmente está en ejecución.
¿Debo poner un nombre ficticio si un conjunto de datos no es público?
No. No invente valores sin verificar. Registre solo lo que pueda confirmar, gestione por separado los aspectos no verificados y consulte al proveedor.
Cómo puede ayudar Hi AUDIT Agent
Después de dar al BOM el formato adecuado, también conviene revisar el código de la aplicación que sustenta las funciones de IA registradas en él. Con Hi AUDIT Agent, puedes solicitar un análisis de seguridad desde un entorno de desarrollo conectado a MCP; por ejemplo, de la API de búsqueda de una aplicación RAG. Puedes consultar allí mismo el contexto de las ubicaciones señaladas y las correcciones propuestas, y pasar a la revisión y corrección en equipo. La generación del BOM y la validación de su conformidad con la especificación deben realizarse por separado, y una persona también debe verificar los resultados del análisis.
Crear una cuenta de Hi AUDIT Agent