Lab700xOrg/aisbom

# AIsbom：人工智能的供应链 [](https://pypi.org/project/aisbom-cli/)    **AIsbom** 是一款专为机器学习（ML）工件设计的专业安全与合规扫描器。 - **SPDX 2.3**：用于行业合规的标准 SBOM 格式。 - **CycloneDX**：受支持（默认输出格式）。 通过 **Pip** 安装，或下载我们的**独立、隔离网络的二进制文件**用于 USB/离线审计。 与仅解析 `requirements.txt` 的通用 SBOM 工具不同，AIsbom 会对模型文件（`.pt`、`.pkl`、`.safetensors`、`.gguf`）执行**深度二进制内省**，以检测隐藏在序列化权重内部的恶意软件风险和法定许可证违规行为。  ## 快速入门 ### 1. 安装 直接从 PyPI 安装。无需克隆。 ``` pip install aisbom-cli ``` *注意：包名为 `aisbom-cli`，但您运行的命令是 `aisbom`。* ### 1a. 独立二进制文件（隔离网络） 对于无法安装 Python 的环境，请从我们的[发布页面](https://github.com/Lab700xOrg/aisbom/releases/latest)下载单文件可执行文件。 **可用二进制文件：** * `aisbom-linux-amd64` (Linux x86_64) * `aisbom-macos-amd64` (macOS Intel) * `aisbom-macos-arm64` (macOS Silicon M1/M2/M3) #### 安装与故障排除 由于 Apple 对未签名二进制文件有严格的安全策略，您必须明确允许该应用运行。 ``` # 1. 使 binary 可执行 chmod +x aisbom-macos-* # 2. 移除 "Quarantine" 属性（修复 "Unidentified Developer" 错误） xattr -d com.apple.quarantine aisbom-macos-* # 3. 运行它 ./aisbom-macos-arm64 --help ``` *为什么需要 `xattr`？* macOS 会为下载的文件打上“隔离”属性标签。由于我们的开源二进制文件未使用 Apple Developer ID 进行代码签名，Gatekeeper 默认会将其阻止。`xattr -d` 命令会移除此标签，从而允许该二进制文件在您的机器上执行。 * **零依赖**：所有内容均已捆绑。 * **可移植**：可在裸机服务器上运行。 ### 2. 运行本地扫描 将其指向包含您的 ML 项目的任何目录。它将递归扫描 requirements 文件及二进制模型工件。 ``` aisbom scan ./my-project-folder ``` ### 3. 输出结果 您将在终端中看到结合了安全与法律的风险评估： ``` 🧠 AI Model Artifacts Found ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Filename ┃ Framework ┃ Security Risk ┃ Legal Risk ┃ ┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ bert_finetune.pt │ PyTorch │ CRITICAL (RCE Found) │ UNKNOWN │ │ safe_model.st │ SafeTensors │ LOW │ UNKNOWN │ │ restricted_model.st │ SafeTensors │ LOW │ LEGAL RISK (cc-by-nc-4.0) │ │ llama-3-quant.gguf │ GGUF │ LOW │ LEGAL RISK (cc-by-nc-sa) │ └─────────────────────┴─────────────┴──────────────────────┴─────────────────────────────┘ ``` 包含 SHA256 哈希值和许可证数据的合规 `sbom.json`（CycloneDX v1.6）将在您的当前目录中生成。 ## 高级用法 ### 远程扫描 无需下载数 TB 的权重，直接扫描 Hugging Face 上的模型。我们使用 HTTP Range 请求通过线缆检查请求头。 ``` aisbom scan hf://google-bert/bert-base-uncased ``` * **速度：** 几秒钟内即可完成扫描，而非几分钟。 * **存储：** 零磁盘占用。 * **安全性：** 在您执行 `git clone` 之前即可验证“SafeTensors”的合规性。 ### 配置漂移检测 检测您的 AI 供应链中的“无声退化”。`diff` 命令会将您当前的 SBOM 与已知的基线 JSON 进行比较。 ``` aisbom diff baseline_sbom.json new_sbom.json ``` **漂移分析输出：** ``` ┏━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓ ┃ Component ┃ Type ┃ Change ┃ Security Risk ┃ Legal Risk ┃ Details ┃ ┡━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩ │ drift-risk.pt │ Modified │ DRIFT │ LOW -> │ - │ │ │ │ │ │ CRITICAL │ │ │ │ drift-license │ Modified │ DRIFT │ - │ UNKNOWN -> │ Lic: MIT -> │ │ │ │ │ │ LEGAL RISK │ CC-BY-NC │ │ drift-hash.pt │ Modified │ DRIFT │ INTEGRITY FAIL │ - │ Hash: ... │ └───────────────┴──────────┴─────────┴────────────────┴─────────────────┴────────────────┘ ``` 如果发生以下情况，它将通过退出码 **code 1** 强制执行质量门控： * 引入了新的 **CRITICAL**（严重）风险。 * 某个组件的风险等级升级（例如，LOW -> CRITICAL）。 * **哈希漂移**：已验证的文件被篡改（标记为 INTEGRITY FAIL）。 ### 严格模式（白名单） 对于高安全性环境，请从“黑名单”（查找恶意软件）切换为“白名单”（阻止所有未知内容）。 ``` aisbom scan model.pkl --strict ``` 此模式将报告**所有**不在安全列表中的导入。 **允许的库**：`torch`（及子模块）、`numpy`、`collections`、`typing`、`datetime`、`re`、`pathlib`、`copy`、`functools`、`dataclasses`、`uuid`。 **允许的内建对象**：`dict`、`list`、`set`、`tuple`、`int`、`float`、`str`、`bytes` 等）。 * 将所有未知的全局导入标记为 `CRITICAL`。 ### 迁移就绪（PyTorch weights_only=True） 让您的模型为即将到来的 PyTorch 安全默认设置做好准备。PyTorch 2.6+ 将默认启用 `weights_only=True`，这将破坏许多旧版模型。 ``` aisbom scan model.pt --lint ``` `--lint` 标志会激活 Migration Linter，它将在不执行代码的情况下静态模拟 unpickling 栈，以预测运行时故障。 ### 策略：纵深防御 AIsbom 提倡双层安全方法： 1. **第 1 层（预执行）：** 使用 `aisbom scan --lint` 静态分析文件结构。这可以在无需加载文件的情况下捕获 99% 的明显恶意软件和不兼容的全局变量。 2. **第 2 层（运行时隔离）：** 如果您*必须*加载使用 `REDUCE` 或不安全全局变量的模型（在旧版文件中很常见），请勿在裸机上运行它。 * **建议：** 使用[沙盒执行](docs/sandboxed-execution.md)（例如 `uvx` + `amazing-sandbox`）来遏制任何潜在的 RCE。 **它能检测：** * **自定义类导入**：不在 PyTorch 默认白名单中的对象。 * **不安全的全局变量**：使用了 `posix.system` 或其他不安全的模块。 **输出：** ``` 🛡️ Migration Readiness (weights_only=True) ┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ File ┃ Issue ┃ Recommendation ┃ ┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ mock_broken.pt │ Custom Class Import Detected: │ Module 'aisbom' is not in PyTorch │ │ │ aisbom.mock.Layer │ default allowlist. Use │ │ │ │ `torch.serialization.add_safe_globals` │ │ │ │ . │ └────────────────┴───────────────────────────────┴────────────────────────────────────────┘ ``` ### Markdown 报告 (CI/CD) 生成适用于 Pull Request 评论的 GitHub 风格 Markdown 报告。 ``` aisbom scan . --format markdown --output report.md ``` ### SPDX 导出（企业合规） 生成 SPDX 2.3 软件物料清单。 ``` aisbom scan . --format spdx --output sbom.spdx.json ``` ## CI/CD 集成 将 AIsbom 添加到您的 GitHub Actions 流水线中。 **行为：** 如果发现 Critical（严重）风险，扫描器将返回 `exit code 1`，自动阻止构建/合并。 ``` name: AI Security Scan on: [pull_request] jobs: aisbom-scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Scan AI Models uses: Lab700xOrg/aisbom@v0 with: directory: '.' ``` ## 可视化报告 不喜欢阅读 JSON？您可以使用我们的**离线**查看器将您的安全状况可视化。 1. 运行扫描以生成 `sbom.json`。 2. 前往 [aisbom.io/viewer.html](https://aisbom.io/viewer.html)。 3. 拖放您的 JSON 文件。 4. 获取即时风险仪表板、许可证问题和合规性统计数据。 *注意：查看器仅限客户端运行。您的 SBOM 数据永远不会离开您的浏览器。* ## 为什么选择 AIsbom？ AI 模型不仅仅是文本文件；它们是可执行程序和 IP 资产。 * **安全风险：** PyTorch（`.pt`）文件是包含 Pickle 字节码的 Zip 存档。恶意模型在加载时可以立即执行任意代码（RCE）。 * **法律风险：** 开发者可能会下载“非商业用途”（CC-BY-NC）的模型并将其部署到生产环境。由于许可证隐藏在二进制文件头中，标准工具无法检测到它。 * **解决方案：** **我们深入内部查看。** 我们无需将庞大的权重加载到 RAM 中，即可反编译字节码并解析内部元数据头。 ## 遥测与隐私 AIsbom 会收集少量匿名的使用遥测数据——人们扫描的模型格式、出现严重发现的频率、扫描是否在 CI 中运行——以帮助我们优先确定构建内容。我们会像对待任何安全工具那样谨慎对待这些数据。了解我们收集的内容，如果您不想参与，可以选择退出。 ### 收集的内容 每次 `aisbom scan`：`target_type`（即**桶分类**：`local` / `huggingface` / `http` / `https` —— 绝不会是实际路径或 URL）、`model_format`（文件类型桶分类）、`risk_level_max`、`scan_duration_ms`、`file_count`、`parse_error_count`、`strict_mode`。当发现至少一个 CRITICAL 时，会添加一个带有计数的 `cli_scan_critical_found` 事件。 每次 `aisbom diff`：一个带有 `has_drift=true|false` 的 `cli_diff` 事件。 发生未处理异常时：`cli_error` 事件仅记录异常类名（例如 `JSONDecodeError`）—— 绝不会记录消息、回溯或任何文件内容。 每个事件都带有一个匿名的 `user_id`——这是您机器 MAC 地址加上应用盐值的 SHA-256 哈希，截断为 16 个十六进制字符。存储在 `~/.aisbom/config.json` 中。这让我们能看到回访用户，而无需识别任何人。 ### 绝不会收集的内容 文件路径、目录内容、模型名称、目标 URL、来自您 SBOM 的文件哈希、异常消息、回溯，或任何可能识别您、您的项目或您的组织的信息。 ### 选择退出 设置 `AISBOM_NO_TELEMETRY=1`。此设置优先于所有其他设置——遥测将不会触发，并且 `~/.aisbom/config.json` 也不会被写入。 ``` # 永久 export AISBOM_NO_TELEMETRY=1 # 单次调用 AISBOM_NO_TELEMETRY=1 aisbom scan ./my-project ``` ### 数据去向 事件会 POST 到 `https://api.aisbom.io/v1/telemetry`（由我们运营的 Cloudflare Worker），该服务会清理负载并将其转发到专用的 `cli.aisbom.io` 数据流上的 Google Analytics 4。我们不会共享、出售或将此数据用于广告定位。 ### CI 环境 当设置 `CI=true` 或 `GITHUB_ACTIONS=true` 时，`cli_install_first_seen` 事件会被阻止（因为容器是临时的，否则会刷爆指标）。其他事件仍会触发，并标记为 `is_ci=true`。 ### 预览状态 在当前版本中，遥测**默认关闭**，仅在设置 `AISBOM_TELEMETRY_V2=1` 时才会触发。下一个版本将翻转为默认开启；`AISBOM_NO_TELEMETRY=1` 是退出选项，并在两种状态下均有效。 ## 如何验证（“信任因素”） 安全工具需要信任。**我们不分发恶意二进制文件。** 然而，AIsbom 包含一个内置生成器，因此您可以创建安全的“模拟工件”来验证扫描器是否正常工作。 **1. 安装：** ``` pip install aisbom-cli ``` **2. 生成测试工件：** 运行以下命令，在当前文件夹中创建一个模拟的“Pickle 炸弹”和一个“受限许可”模型。 ``` aisbom generate-test-artifacts ``` *结果：将创建名为 `mock_malware.pt`、`mock_restricted.safetensors`、`mock_restricted.gguf` 和 `mock_broken.pt` 的文件。* **3. 扫描它们：** ``` aisbom scan . ``` *结果：您将看到 `mock_malware.pt` 被标记为 **CRITICAL**，法律风险被标记，如果您使用 `--lint` 运行，`mock_broken.pt` 将出现在迁移就绪表中。* ## 安全逻辑详情 AIsbom 使用静态分析引擎来反汇编 Python Pickle 操作码。它会寻找引用危险模块的特定 `GLOBAL` 和 `STACK_GLOBAL` 指令： * `os` / `posix`（系统调用） * `subprocess`（Shell 执行） * `builtins.eval` / `exec`（动态代码执行） * `socket`（网络反向 shell）

标签：AI安全, AI安全治理, Chat Copilot, CycloneDX, GGUF, Pickle, Python, PyTorch, Safetensors, SBOM, SPDX, 云安全监控, 人工智能供应链, 凭据扫描, 安全合规模板, 密钥泄露防护, 文档安全, 无后门, 机器学习安全, 模型文件解析, 模型权重分析, 深度二进制自省, 深度学习模型, 硬件无关, 离线安全工具, 离线部署, 许可证合规, 跌倒检测, 软件物料清单, 逆向工具, 静态分析