AKIVA-AI/toolkit-ml-provenance

# 工具包 ML 溯源与 SBOM 为数据集、训练配置、代码快照和模型权重等制品生成确定性 JSON 清单（"ML SBOM"）。支持 CycloneDX 1.5 标准 SBOM 格式。通过重新哈希引用的制品来验证其完整性。 ## 安装 ``` pip install -e ".[dev]" ``` 如需签名支持： ``` pip install -e ".[signing]" ``` ## CLI 参考 ### 全局选项 | 标志 | 描述 | |------|-------------| | `--version` | 显示版本并退出 | | `--verbose`, `-v` | 启用 DEBUG 级别日志输出到 stderr | | `--log-format {text,json}` | 日志输出格式（默认：text） | ### `generate` -- 创建溯源清单 ``` toolkit-mlsbom generate --root --out --include [--meta key=value] [--format {json,cyclonedx}] ``` | 参数 | 必填 | 描述 | |----------|----------|-------------| | `--root` | 否 | 根目录（默认：`.`） | | `--out` | 是 | 输出清单文件路径 | | `--include` | 是 | 文件匹配模式（可重复） | | `--meta` | 否 | 元数据键值对（可重复） | | `--format` | 否 | 输出格式：`json`（默认）或 `cyclonedx`（CycloneDX 1.5 JSON） | **示例：** ``` # 为模型权重和配置生成 manifest toolkit-mlsbom generate --root ./my-model \ --out manifest.json \ --include "weights/*.safetensors" \ --include "configs/*.json" \ --meta model=gpt-2 \ --meta version=1.0 # 生成 CycloneDX SBOM toolkit-mlsbom generate --root ./my-model \ --out sbom.cdx.json \ --include "**/*" \ --format cyclonedx ``` ### `verify` -- 根据清单验证文件完整性 ``` toolkit-mlsbom verify --manifest [--signature --public-key ] [--out ] [--format {json,table}] ``` | 参数 | 必填 | 描述 | |----------|----------|-------------| | `--manifest` | 是 | 清单 JSON 文件路径 | | `--signature` | 否 | 用于验证的签名 JSON 文件 | | `--public-key` | 否 | 公钥 PEM 文件（与 --signature 配合使用） | | `--out` | 否 | 输出报告文件路径（默认：stdout） | | `--format` | 否 | 输出格式：`json`（默认）或 `table`（人类可读） | **示例：** ``` # 验证 manifest toolkit-mlsbom verify --manifest manifest.json # 使用表格输出验证 toolkit-mlsbom verify --manifest manifest.json --format table # 使用签名验证 toolkit-mlsbom verify --manifest manifest.json \ --signature manifest.sig.json \ --public-key ed25519_pub.pem ``` ### `keygen` -- 生成 Ed25519 签名密钥对 ``` toolkit-mlsbom keygen --private-key --public-key ``` | 参数 | 必填 | 描述 | |----------|----------|-------------| | `--private-key` | 是 | 输出私钥文件路径 | | `--public-key` | 是 | 输出公钥文件路径 | ### `sign` -- 签署清单 ``` toolkit-mlsbom sign --manifest --private-key [--out ] ``` | 参数 | 必填 | 描述 | |----------|----------|-------------| | `--manifest` | 是 | 清单 JSON 文件路径 | | `--private-key` | 是 | 私钥 PEM 文件路径 | | `--out` | 否 | 输出签名文件（默认：stdout） | ## 输出格式 ### 原生 JSON（默认） 默认的 `json` 格式生成的清单包含： ``` { "version": 1, "created_ts": 1741500000.0, "root": "/path/to/model", "git_commit": "abc123...", "entries": [ {"path": "weights/model.bin", "size": 1024, "sha256": "..."} ], "meta": {"model": "gpt-2"} } ``` ### CycloneDX 1.5 JSON `cyclonedx` 格式生成符合 [CycloneDX 1.5](https://cyclonedx.org/docs/1.5/json/) 标准的 SBOM： ``` { "bomFormat": "CycloneDX", "specVersion": "1.5", "serialNumber": "urn:uuid:...", "version": 1, "metadata": { "timestamp": "2026-03-09T00:00:00+00:00", "tools": {"components": [{"type": "application", "name": "toolkit-ml-provenance-sbom", "version": "0.1.0"}]} }, "components": [ {"type": "data", "name": "weights/model.bin", "hashes": [{"alg": "SHA-256", "content": "..."}]} ] } ``` ## 退出码 | 代码 | 含义 | |------|---------| | `0` | 成功 | | `2` | 用法无效 / CLI 错误 | | `3` | 意外错误 | | `4` | 验证失败 | ## 编程使用 该包导出一个公共 Python API： ``` from toolkit_ml_sbom import ( Manifest, build_manifest, sha256_file, sign_bytes, verify_bytes, generate_ed25519_keypair, canonical_json_bytes, ) from pathlib import Path # 构建 manifest manifest = build_manifest( root=Path("./my-model"), paths=list(Path("./my-model").glob("**/*")), meta={"model": "gpt-2"}, ) # Serialize data = manifest.to_json() # Deserialize loaded = Manifest.from_json(data) ``` ## 结构化日志 为日志聚合管道启用 JSON 格式的日志： ``` toolkit-mlsbom --verbose --log-format json generate --root . --out m.json --include "*.py" ``` 输出（stderr）： ``` {"timestamp":"2026-03-09T12:00:00+00:00","level":"INFO","logger":"toolkit_ml_sbom.cli","message":"Generating manifest for root: /path"} ``` ## 许可证 MIT 许可证 - 详见 LICENSE 文件。

标签：Apex, CycloneDX, Homebrew安装, JSON, MLOps, PEM, Provenance, Python, SBOM, 二进制安全, 人工智能安全, 代码快照, 加密签名, 合规性, 哈希校验, 安全可观测性, 完整性验证, 审计, 工件管理, 恶意代码分析, 提示词模板, 数据溯源, 数据集管理, 文档结构分析, 无后门, 机器学习, 模型权重, 版本控制, 硬件无关, 跌倒检测, 软件物料清单, 逆向工具, 配置文件