使用 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