使用 CycloneDX 创建 AI BOM:记录并验证模型与数据
Yuta Matsuyama
TECHFUND 株式会社 安全研究员
更新日期:
适合谁阅读: 面向 AI 应用开发者、ML 基础设施和安全负责人。信息截至 2026 年 11 月 13 日。
简要回答
首先,识别模型以及已有可核实依据的数据集,并将其记录为 CycloneDX 组件。除了验证格式,还应单独检查 ID 是否重复、引用是否失效,以及记录的内容是否与实际配置一致。AI BOM 通过验证,并不意味着它的完整性或安全性就有了保证。
先决定要记录什么
例如,对于内部问答应用,应根据目的核实模型名称与版本、提供方、评估所用数据、软件依赖关系、使用环境及负责人。本文介绍的是一个表达模型与其评估数据之间关系的最小示例,并未涵盖整个应用的配置。
CycloneDX 规范允许使用 machine-learning-model 组件类型表示模型,使用 data 组件类型表示数据。模型的 modelCard 可以记录对已核实数据集的引用等信息。CycloneDX 官方的模型与数据集示例可供参考,帮助理解如何将它们关联起来。格式中存在某个字段,与实际能否获得该字段的值,是两回事。
先记录两个虚构组件
请将以下内容保存为 ai-bom.json。模型名称、版本和数据名称均为虚构。本例假设一个虚构模型使用了虚构的评估数据。数据内容、训练数据、许可证和提供方均未核实,因此没有填写。省略并不代表“不存在”。
bom-ref 是用于在文档内标识组件的值。modelCard.modelParameters.datasets 中的 ref 指向 dataset-1。不要只在 modelCard 中用文字描述数据,而应将其定义为单独的组件并引用,这样更容易核查它们之间的关系。
{
"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" }]
}
]
}验证格式,也要检查引用
CycloneDX CLI 的 validate 命令可以验证指定文件的格式。以下示例使用 CLI 0.33.1。2026 年 11 月 13 日,我们在 macOS arm64 上使用该版本,确认示例 JSON 正常通过验证。通过 --input-version v1_6 将文件指定为 1.6 版本,并使用 --fail-on-errors 设置在出现验证错误时以非零状态退出。
接下来的两个实验分别尝试将引用目标改为不存在的 ID,以及让两个组件的 bom-ref 重复。在我们的同一环境中,两者均显示“BOM validated successfully.”,退出码均为 0。CycloneDX 规范要求 bom-ref 在文档内唯一。不要只依赖格式验证成功,还应单独检查引用目标是否存在以及 ID 是否唯一。这些结果是在 CLI 0.33.1 和所示输入下观察到的行为,并不是对其他验证器或未来版本的结论。
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-errors检查此示例中的 ID 和引用
将下面的小脚本保存为 check-example.py,并运行 python3 check-example.py ai-bom.json。对上一次实验中创建的 dangling.json 和 duplicate.json 也运行同一命令:两者将分别报告 missing-reference 和 model-1 重复,并均返回退出码 1。对于正常示例,两项结果均为空,退出码为 0。
这段代码仅用于说明,只针对本次虚构示例的结构。它仅检查 components 直属顶层组件的 bom-ref ID,以及 modelCard 中的 datasets 引用是否指向已存在的 ID,不验证引用目标的类型、嵌套组件、BOM-Link、其他引用形式或实际数据的准确性。在实际系统中,请另行采用适合目标结构和规范的方法进行检查。
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)区分“已记录”和“正确”
在实际使用的 AI BOM 中,应将模型标识符和版本与配置及使用记录进行核对;只有能通过模型卡或评估任务记录等核实依据时,才填写与评估数据的关系。应将外部提供方模型卡中的描述与自己直接观察到的事实分开管理。如果训练数据未公开,不要推断其不存在,而应在单独的管理表或工单中将其标记为未核实,并向提供方确认。
仅对代码仓库进行静态分析,可能会遗漏通过环境变量或运行时路由选用的外部模型。应对照配置和使用记录,并明确当版本或服务目标发生变化时,由谁在什么触发条件下更新。无需将机密提示词或用户数据原样放入用于共享的 BOM。
纳入日常运作之前
在第一个案例中确认格式与引用后,再逐步扩展到应用、软件依赖关系、外部服务等必要对象。即使使用生成工具,也应结合目标代码仓库和实际运作,确认工具能发现什么、会遗漏什么。关于接入现有 DevSecOps 流水线时的工具选型,另有相关文章介绍。
常见问题
JSON 通过验证后,AI BOM 就算完成了吗?
不是。除了语法和规范符合性,还应单独检查 ID 与引用的一致性、记录内容的依据,以及是否与实际运行的配置一致。
如果数据集未公开,应该用虚构名称填充吗?
不应该。不要编造未经核实的值,只记录能够核实的内容,并单独管理未核实事项,向提供方确认。
Hi AUDIT Agent 如何帮助您
整理好 BOM 的格式后,也值得检查支撑其中所记录 AI 功能的应用代码。使用 Hi AUDIT Agent,可以在连接到 MCP 的开发环境中请求安全分析,例如对 RAG 应用的搜索 API 进行安全分析。可以当场查看被指出位置的上下文和修改建议,继而推进团队审查与修改。BOM 的生成及规范符合性验证应另行开展,分析结果也请由人工确认。
注册 Hi AUDIT Agent