d01ki/AIBOM-Inspector

## 标题：AIBOM Inspector emoji: 🧬 colorFrom: blue colorTo: indigo sdk: docker app_port: 8000 pinned: false license: apache-2.0 # AIBOM Inspector [](https://github.com/d01ki/AIBOM-Inspector/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/) `aibom` 扫描代码仓库，并生成其所依赖的 AI 组件（模型、数据集、prompt、agent 和外部 AI 服务）的**有证据支撑的清单**，这是迈向完整 **AIBOM**（AI Bill of Materials）和供应链风险分析的第一步。 它报告的每个实体都通过匹配到的模式固定在具体的 `file:line` 上。**无证据，不声明** —— 这就是该工具的信任契约。 ## 为什么 现有的 SBOM 工具（Trivy、Syft）仅停留在包级别，对模型、数据集、prompt 和 agent 视而不见。AIBOM 生成器只能为*单一*已知模型生成物料清单。**AIBOM Inspector 能够在整个代码库中发现 AI 的使用情况**，对其进行解析，并在此基础上添加图谱和风险分析。 | 工具 | AIBOM Inspector 填补的空白 | |---|---| | OWASP AIBOM Generator | 为单一 HF 模型生成 AIBOM。AIBOM Inspector 能够*发现*整个代码库中的 AI 使用情况，并添加图谱和风险分析。 | | Trivy / Syft (SBOM) | 仅限包级别；对模型、数据集、prompt、agent 视而不见。 | | Dependency-Track | 消费 SBOM；没有针对 AI 的特定发现或风险规则。 | | `modelscan` / `picklescan` | 扫描*给定的*模型文件以查找不安全的 pickle。AIBOM Inspector 会*首先找出代码仓库使用了哪些模型*，然后结合上下文标记出 pickle 风险。 | ## 状态 **早期 alpha 版本 (v0.1, M1–M4)。** 目前已实现： - ✅ 用于 OpenAI、Anthropic 和 Hugging Face 的 **Python AST 检测器**，包括导入别名、实际 API 调用以及可审计的值解析 - ✅ **使用与可达性证据** —— 声明/导入/实例化/调用状态、同文件入口路径、置信度因子、检测器 ID 以及生产/测试/示例/文档源上下文 - ✅ **可复现的基准测试套件** —— 类别级别的 Precision/Recall/F1，以及明确的假阳性 (false-positive) 和假阴性 (false-negative) 报告 - ✅ **依赖清单收集器** —— 在 `requirements*.txt`、`pyproject.toml`、`Pipfile`、`package.json` (PyPI + npm) 中查找 AI/ML 库及其版本和 purl，使得 AIBOM 对真实仓库（而不仅仅是带有内联 `from_pretrained` 的仓库）也能发挥作用 - ✅ **漏洞映射** —— 使用 `--resolve` 时，会将锁定的包与 [OSV.dev](https://osv.dev) 进行比对，匹配的 CVE/GHSA 安全通告将转化为有证据支撑的发现 - ✅ **Web 应用** —— FastAPI 后端 (`aibom serve`) + 静态单页 UI：粘贴公开的仓库 URL，即可在浏览器中获取 AIBOM、发现的问题和评分 - ✅ **交互式依赖图** —— 应用 → agent → 模型 / prompt / 服务，节点按风险着色；点击节点查看其有证据支撑的发现（无需 JS 依赖） - ✅ 统一的 Pydantic schema，具备强制证据要求 - ✅ 静态代码仓库收集器（模型、数据集、prompt、agent、服务） - ✅ 去重清单 + 类型化关系图 - ✅ **Hugging Face 解析器** —— 通过 license、model-card 是否存在、序列化格式、作者、下载量、gated 状态来丰富 HF 模型/数据集的信息（支持可选联网、基于缓存、对离线友好；**从不下载或加载权重**） - ✅ **CycloneDX 1.6 (ML-BOM) 导出** —— `machine-learning-model` / `data` 组件、服务、依赖图，以及位于 `aibom:*` 属性命名空间中的特定于 AIBOM 的数据；**已在测试套件中通过官方 CycloneDX 1.6 JSON schema 验证** - ✅ **确定性风险规则 (TDR-001…010)** + 针对完整性 / 来源 / 许可证 / 配置的可复现 0–100 安全评分 - ✅ **自包含 HTML 报告**（评分、有证据支撑的发现、清单） - ✅ CLI (`aibom scan`)，支持 JSON 清单、CycloneDX、HTML 报告和严重程度退出代码 - ✅ Golden-fixture 测试套件 路线图 → [SPEC.md](SPEC.md)：依赖图可视化、插件收集器。 ## 安装 ``` # 从 PyPI pip install aibom # CLI only pip install "aibom[server]" # + the web API/UI (aibom serve) ``` ``` # 从 source（推荐使用 uv） git clone https://github.com/d01ki/AIBOM-Inspector cd AIBOM-Inspector uv venv && uv pip install -e ".[dev]" ``` ## 用法 ``` # 扫描 repo 并打印 inventory aibom scan ./path/to/repo # 将完整 inventory（entities + relationships + evidence）写为 JSON aibom scan ./path/to/repo --output inventory.json # 生成 CycloneDX 1.6 (ML-BOM) AIBOM — 导入到 Dependency-Track aibom scan ./path/to/repo --cyclonedx aibom.cdx.json # 在线 enrichment：Hugging Face 元数据（license、formats 等）以及 OSV # 针对 pinned AI packages 的 vulnerability 映射 aibom scan ./path/to/repo --resolve --cyclonedx aibom.cdx.json # 缓存 HF 元数据以供离线 / air-gapped 重复扫描 aibom scan ./path/to/repo --resolve --hf-cache ~/.cache/aibom # 风险分析：编写独立的 HTML 报告（score + findings + inventory） aibom scan ./path/to/repo --report report.html # CI gate：如果任何 finding 达到或超过某个 severity，则以非零状态退出 aibom scan ./path/to/repo --fail-on high # 丢弃低置信度的检测结果 aibom scan ./path/to/repo --min-confidence 0.8 # 在调试或强制执行组织 profile 时禁用单个 detector aibom scan ./path/to/repo --disable-detector python.openai.ast # 根据已审查的 ground truth 评估已检出的 repositories python benchmark/evaluate.py ``` 可复现的测试报告包含一个确定性的本地 fixture 和一份[双代码仓库公开评测](benchmark/reports/external-latest.md)。公开报告是用于回归测试的证据，而非声称具有广泛的生态覆盖面。 ## 风险规则与评分 发现是**确定性的且基于规则的**（过程中不涉及 LLM）。每项发现都带有严重程度、`file:line` 证据追踪以及修复建议。 | ID | 检查内容 | 默认严重程度 | 需要 `--resolve` | |---|---|---|---| | TDR-001 | 基于 Pickle 的权重格式（加载时会导致任意代码执行） | High | — | | TDR-002 | 模型引用未锁定 revision | Medium | — | | TDR-003 | 名称仿冒热门模型家族 (typosquat) | High | — | | TDR-004 | 缺少 model card | Low | ✔ | | TDR-005 | 缺少 license / 非 SPDX / 无法识别 | Medium–Low | ✔ | | TDR-006 | 采用率极低（需验证作者） | Medium | ✔ | | TDR-007 | 在 AI 调用附近硬编码 secret | Critical | — | | TDR-008 | 无来源元数据的数据集 | Low | — | | TDR-009 | `trust_remote_code=True` | High | — | | TDR-010 | 引用了已弃用 / 被取代的模型 | Medium | — | | TDR-011 | MCP server 暴露了可由 LLM 调用的 tool 接口 | Low | — | | TDR-012 | 声明了 AI package 但未锁定版本 | Low | — | | OSV-* | 锁定的 AI package 中的已知漏洞 (OSV.dev) | 视安全通告而定 | ✔ (网络) | **安全评分 (0–100)：** 四个类别 {完整性、来源、许可证、配置} 中的每一个都从 100 分开始，并根据每项发现扣分（Critical 扣 40 / High 扣 20 / Medium 扣 10 / Low 扣 3，最低降至 0，每条规则最多计算 3 项发现）。总体评分为 `0.55 × 平均分 + 0.45 × 最差类别分`，这样一个彻底崩盘的类别是无法通过其他没有组件的类别平均掉的。空清单会显示为“未检测到 AI 组件”，而不是 100/A。该公式会打印在报告本身中，以保证可复现性。 针对内置的故意带有漏洞的演示应用进行测试： ``` aibom scan tests/fixtures/vulnerable-ai-app ``` ## Web 应用 在本地运行 HTTP API + 浏览器 UI（粘贴仓库 URL，获取 AIBOM + 评分）： ``` uv pip install -e ".[server]" # or: pip install 'aibom[server]' aibom serve # http://127.0.0.1:8000 ``` 后端将 URL 浅层克隆到一个一次性的临时目录中，运行与 CLI 相同的静态 pipeline，并返回 JSON —— 它**从不执行被克隆的代码**。克隆 URL 会根据主机白名单（github.com、gitlab.com、bitbucket.org、codeberg.org）进行验证，并作为 argv 传递给 git，而不是作为 shell 字符串。 | Endpoint | 用途 | |---|---| | `POST /api/scan` `{repo_url, resolve?}` | 清单 + CycloneDX + 发现 + 评分 + 依赖图 (JSON) | | `POST /api/report` `{repo_url, resolve?}` | 自包含的 HTML 报告 | | `GET /api/health` | 存活状态 + 版本 | UI 从 `/api/scan` 的 `graph` (`{nodes, edges}`) 中渲染交互式依赖图：节点按其最严重的发现程度进行着色；点击其中一个可查看组件及其证据追踪。 ## 部署 后端是一个同时提供 UI 服务的小型容器，因此一个免费服务即可从一个 URL 运行整个应用。 **Render（免费，无需信用卡，推荐）。** 扫描器需要服务器端计算（它负责克隆和分析仓库），因此它必须运行在计算主机上 —— 而不是纯静态主机上。[`render.yaml`](render.yaml) 是一个蓝图：在 [render.com](https://render.com) 上 → **New → Blueprint** → 选择此仓库 → **Apply**。 几分钟后，整个应用（UI 位于 `/`，API 位于 `/api/*`）即可在 `https://aibom-inspector-api.onrender.com` 上线。空闲约 15 分钟后，免费实例会进入休眠，并在收到下一个请求时冷启动。 **在任何安装有 Docker 的地方运行镜像：** ``` docker build -t aibom . docker run -p 8000:8000 aibom # UI + API at http://localhost:8000 ``` **纯静态主机（GitHub Pages / HF *Static* Spaces）。** 这些平台可以免费托管 [`web/`](web/) UI，但**不能**托管扫描器 —— 请使用 `?api=https://your-backend` 打开页面，以便它与计算后端（例如您的 Render URL）通信，并在后端上将 `AIBOM_CORS_ORIGINS` 设置为该 UI 的源。如果由后端自身提供服务，则 UI 根本无需任何配置。 [`.github/workflows/pages.yml`](.github/workflows/pages.yml) 会在 push 到 `main` 时将 `web/` 发布到 Pages（需启用 *Settings → Pages → Source = GitHub Actions*）。 - `AIBOM_CORS_ORIGINS` —— 以逗号分隔的允许源（您的 Pages 源；本地演示默认为 `*`）。如果后端也提供 UI 服务，则不需要此项。 - `AIBOM_WEB_DIR` —— 后端查找 UI 以便同时在 `/` 提供服务的目录位置（已在镜像中设置）。对于**无 CORS 的全单源部署**非常方便 —— 例如，Hugging Face Space 可以通过同一个 URL 同时提供 UI 和 API 服务。 ## 检测内容 | 组件 | 信号 | |---|---| | **模型** | 经 Python AST 确认的 OpenAI/Anthropic 调用、`from_pretrained(...)`、`pipeline(model=...)`、变量/字典/f-string/环境变量默认值、`repo_id=`、HF URL 以及权重文件（`.safetensors`、`.gguf`、`.pkl`、`.bin` 等） | | **数据集** | `load_dataset(...)` | | **Prompt** | 模板文件（`prompts/`、`*.prompt`、`*.jinja`）、硬编码的 system prompt | | **Agent** | LangChain/LangGraph 构造函数（`create_react_agent`、`AgentExecutor` 等） | | **服务** | 在 Python **以及 JS/TS** 中的 provider SDK 导入（`openai`、`anthropic`、`@anthropic-ai/sdk` 等）、显式的 `base_url`、MCP client 配置（`mcpServers`）、**MCP server 实现**（Python 的 `mcp`/`FastMCP`、TS 的 `@modelcontextprotocol/sdk`） | | **包** | 在 `requirements*.txt`、`pyproject.toml`、`Pipfile`、`package.json` (PyPI + npm) 中声明的**每一个**依赖项，包含版本 + purl —— 构成完整的 BOM。AI/ML 生态系统包（包括 `mcp`/`fastmcp`/`@modelcontextprotocol/*`）会被标记为 `ai`，而风险规则、图谱和评分正是聚焦于这一 AI 层 | ## 设计原则 - **仅限静态。** 扫描器只读取文本。它从不导入、执行或反序列化任何内容。 - **有证据支撑。** 每个实体都带有 `file:line` + 匹配模式 + 置信度。 - **确定性。** 检测和（计划中的）评分是基于且可复现的；LLM 协助是可选的，且仅限于*解释*发现，绝不用于生成发现。 - **本地优先。** 无 SaaS，无遥测，支持气隙隔离。 ## 开发 ``` uv run pytest # tests uv run ruff check . # lint uv run mypy # types python benchmark/evaluate.py # precision/recall benchmark ``` 实现细节：[架构](docs/architecture.md)、[检测方法](docs/detection-methodology.md)、[基准测试方法](docs/benchmark-methodology.md) 和[已知局限性](docs/limitations.md)。 ### 发布 发布过程已通过 [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) 自动化（使用 OIDC —— 无需 token）。一次性设置：在 PyPI 上为此代码仓库、工作流 `release.yml` 和环境 `pypi` 添加受信任的发布者。然后推送 tag： ``` git tag v0.1.0 && git push origin v0.1.0 # builds, twine-checks, and publishes ``` ## 许可证 Apache-2.0 —— 详见 [LICENSE](LICENSE)。

标签：AIBOM, AI供应链, Python, SBOM, 代码分析, 依赖管理, 凭证管理, 安全合规, 无后门, 硬件无关, 网络代理, 请求拦截, 逆向工具