Criar uma AI BOM com CycloneDX: registrar e validar modelos e dados
Yuta Matsuyama
Pesquisador de segurança, TECHFUND Inc.
Atualizado:
Para quem é: Para desenvolvedores de aplicações de IA e responsáveis por infraestrutura de ML e segurança. Informações de 13 de novembro de 2026.
Resposta prática
Primeiro, identifique o modelo e os conjuntos de dados para os quais foi possível verificar as evidências, e registre-os como componentes do CycloneDX. Além de validar o formato, verifique separadamente se há IDs duplicados, referências quebradas e se as informações registradas correspondem à configuração real. Passar na validação, por si só, não garante que uma AI BOM seja completa ou segura.
Decida primeiro o que registrar
Por exemplo, em uma aplicação interna de perguntas e respostas, verifique, de acordo com o objetivo, o nome e a versão do modelo, o fornecedor, os dados usados na avaliação, as dependências de software, o ambiente de uso e os responsáveis. Aqui apresentamos um exemplo mínimo que expressa a relação entre um modelo e seus dados de avaliação. Ele não abrange a configuração de toda a aplicação.
A especificação CycloneDX permite representar modelos com o tipo de componente machine-learning-model e dados com o tipo data. O modelCard do modelo pode registrar, entre outras informações, referências a conjuntos de dados verificados. Os exemplos oficiais de modelos e conjuntos de dados do CycloneDX servem como referência para estabelecer essas relações. A existência de um campo no formato não significa que seu valor esteja realmente disponível.
Comece registrando dois componentes fictícios
Salve o conteúdo abaixo como ai-bom.json. O nome do modelo, as versões e o nome dos dados são todos fictícios. Este exemplo parte da premissa de que um modelo fictício usou dados de avaliação fictícios. O conteúdo dos dados, os dados de treinamento, as licenças e os fornecedores não foram verificados e, por isso, não foram incluídos. A omissão não significa que algo não exista.
bom-ref é o valor que identifica um componente dentro do documento. O ref em modelCard.modelParameters.datasets aponta para dataset-1. Definir os dados como um componente separado e referenciá-lo, em vez de apenas descrevê-los em texto no modelCard, facilita a verificação da relação.
{
"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 o formato e confira também as referências
O comando validate do CycloneDX CLI permite validar o formato de um arquivo especificado. O exemplo a seguir usa o CLI 0.33.1. Em 13 de novembro de 2026, usamos essa versão no macOS arm64 e confirmamos que o JSON do exemplo passou na validação. --input-version v1_6 especifica um arquivo da versão 1.6, e --fail-on-errors configura o comando para encerrar com um código diferente de zero em caso de erros de validação.
Os dois experimentos seguintes testam a alteração do destino de uma referência para um ID inexistente e a duplicação do bom-ref de dois componentes. No mesmo ambiente, ambos exibiram “BOM validated successfully.” e retornaram o código de saída 0. A especificação CycloneDX exige que bom-ref seja único dentro do documento. Não confie apenas no sucesso da validação de formato: verifique separadamente se os destinos das referências existem e se os IDs são únicos. Esses resultados são observações do CLI 0.33.1 com as entradas mostradas, e não conclusões sobre outros validadores ou versões 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-errorsVerificar os IDs e as referências deste exemplo
Salve o pequeno script a seguir como check-example.py e execute-o com python3 check-example.py ai-bom.json. Execute também o mesmo comando com dangling.json e duplicate.json, criados no experimento anterior: eles apresentarão missing-reference e uma duplicação de model-1, respectivamente, e ambos retornarão o código de saída 1. No exemplo válido, os dois resultados ficam vazios e o código de saída é 0.
Este código é apenas ilustrativo e abrange somente a estrutura deste exemplo fictício. Ele verifica apenas os IDs bom-ref dos componentes de nível superior diretamente em components e se as referências de datasets em modelCard apontam para IDs existentes. Não valida os tipos dos destinos, componentes aninhados, BOM-Link, outros formatos de referência nem a exatidão dos dados reais. Em sistemas reais, faça verificações separadas com métodos adequados à estrutura e à especificação correspondentes.
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)Diferencie “registrado” de “correto”
Em uma AI BOM de uso real, confronte os identificadores e as versões dos modelos com as configurações e os registros de uso, e registre as relações com os dados de avaliação quando houver evidências verificáveis, como cartões de modelo ou registros de tarefas de avaliação. Gerencie separadamente as declarações dos cartões de modelo de fornecedores externos e os fatos observados diretamente pela sua equipe. Se os dados de treinamento não forem públicos, não presuma que não existam: registre-os como não verificados em uma planilha de controle ou em um ticket separado e consulte o fornecedor.
A análise estática do repositório, por si só, pode deixar de identificar modelos externos selecionados por variáveis de ambiente ou roteamento em tempo de execução. Compare a configuração com os registros de uso e defina quem atualizará a BOM e quais serão os gatilhos de atualização quando houver mudanças de versão ou de destino dos serviços. Não é necessário inserir diretamente prompts confidenciais ou dados de usuários em uma BOM destinada ao compartilhamento.
Antes de incorporar às operações
Depois de verificar o formato e as referências no primeiro caso, amplie gradualmente o escopo para incluir aplicações, dependências de software, serviços externos e outros itens necessários. Mesmo usando uma ferramenta de geração, confira o que ela descobre e o que deixa passar em relação ao repositório e às operações em questão. Um artigo relacionado aborda a escolha de ferramentas para integração a um pipeline de DevSecOps existente.
Perguntas frequentes
A AI BOM está pronta quando o JSON passa na validação?
Não. Além da sintaxe e da conformidade com a especificação, verifique separadamente a consistência dos IDs e das referências, as evidências que sustentam as informações registradas e a correspondência com a configuração realmente em execução.
Devo preencher com um nome fictício se o conjunto de dados não for público?
Não. Não invente valores não verificados. Registre apenas o que puder confirmar, gerencie os itens não verificados separadamente e consulte o fornecedor.
Como o Hi AUDIT Agent pode ajudar
Depois de ajustar o formato do BOM, também vale revisar o código da aplicação que sustenta as funcionalidades de IA registradas nele. Com o Hi AUDIT Agent, você pode solicitar uma análise de segurança em um ambiente de desenvolvimento conectado ao MCP, por exemplo, da API de busca de uma aplicação RAG. É possível consultar ali mesmo o contexto dos trechos sinalizados e as sugestões de correção, para então avançar com a revisão e as correções em equipe. A geração do BOM e a validação de sua conformidade com a especificação devem ser realizadas separadamente, e os resultados da análise também devem ser verificados por uma pessoa.
Criar uma conta no Hi AUDIT Agent