rzawadzk/ai-supply-chain-auditor

# AI供应链审计师 一个智能体AI工具，用于在5个维度上审计软件项目的供应链风险：**库存、来源、完整性、合规性、行为**。将其指向一个目录，即可获得一份带有修复步骤的优先级风险报告。 如果你不知道你的AI堆栈里有什么，你就无法理解自己的风险画像。这个工具会照亮它。 ## 它能发现什么 一份非穷尽的列表，列出了审计器将捕获的内容： - 源代码中的硬编码API密钥（`sk-`、`sk-ant-`、`hf_`） - 没有 `weights_only=True` 的 `pickle.load()` 或 `torch.load()` —— 任意代码执行风险 - 包含危险操作码（`GLOBAL`、`REDUCE`、`INST`、`BUILD`）的Pickle模型文件 - 未固定版本的依赖，可能在你毫无察觉下被悄悄替换 - 没有组织前缀的HuggingFace模型（命名空间劫持风险） - 来自匿名或未验证作者的模型 - 你的使用场景（商业/研究/内部/开源）与组件许可证之间的冲突 - 没有校验和验证的远程数据下载 - `exec()` / `eval()` 与字符串插值 - 缺少 `MODEL_CARD.md` / `LICENSE` 文档 - 模型加载代码中的后门指示和可疑网络模式 ## 快速开始 ``` # 克隆 git clone https://github.com/rzawadzk/ai-supply-chain-auditor.git cd ai-supply-chain-auditor # 安装 pip install -r requirements.txt # 确保您已登录 Claude Code # （该工具使用 Claude Agent SDK — 无需 API 密钥） # 运行包含的演示审计 python main.py ``` 默认运行会审计 `sample_project/` —— 一个故意植入8个以上问题的演示项目 —— 这样你可以在指向真实项目之前看到输出形态。 要审计你自己的项目： ``` python main.py /path/to/your/project ``` 添加 `--verbose` 以观察智能体的推理、工具选择和迭代过程： ``` python main.py /path/to/your/project --verbose ``` ### 使用不同的LLM 该审计器与模型无关。使用 `--backend` 选择任何受支持的后端： ``` # Claude（默认，使用 Claude Code 登录 — 无需 API 密钥） python main.py --backend claude # OpenAI（需要 OPENAI_API_KEY） OPENAI_API_KEY=sk-... python main.py --backend openai # Groq — 默认快速，使用 Llama 3.3 70B（需要 GROQ_API_KEY） GROQ_API_KEY=gsk_... python main.py --backend groq # Together AI（需要 TOGETHER_API_KEY） TOGETHER_API_KEY=... python main.py --backend together # OpenRouter — 统一访问多种模型（需要 OPENROUTER_API_KEY） OPENROUTER_API_KEY=... python main.py --backend openrouter # Ollama — 完全本地，完全私有。需要运行 `ollama serve` ollama pull llama3.1 python main.py --backend ollama ``` 通过 `OPENAI_MODEL=...` 覆盖每个后端的默认模型。指向一个 自定义的OpenAI兼容端点（例如本地vLLM）使用 `OPENAI_BASE_URL=...`。 **关于Ollama和开源模型的说明：** 工具使用质量因模型而异。 Llama 3.1/3.2/3.3、Qwen 2.5 和 Mistral-Nemo 工作可靠； 较小的模型往往无法完成完整的审计循环。该适配器会先检查Ollama服务器健康状态，并验证请求模型是否已拉取，同时会对不支持工具的模型发出警告。 ## 三种运行方式 ### 1. CLI（自包含） 该工具运行自己的智能体循环并打印完整报告。适用于定时审计和CI/CD。 ``` python main.py /path/to/project ``` ### 2. 在任意 Claude Code 会话中（MCP 模式） 注册一次审计器，即可在任意 Claude Code 对话中调用它。适用于需要调用会话上下文进行交互式调查的场景。 **项目范围**（打开此仓库时自动加载）—— 本仓库中的 `.mcp.json` 已配置好。 **全局范围** —— 添加到 `~/.claude.json` 以便随处可用： ``` { "mcpServers": { "ai-supply-chain-auditor": { "command": "python", "args": ["/absolute/path/to/ai-supply-chain-auditor/mcp_server.py"] } } } ``` 然后在任何 Claude Code 会话中： 五个工具将变为可用：`scan_inventory`、`check_provenance`、`verify_integrity`、`audit_compliance`、`probe_behavior`。调用会话负责编排它们。 ### 跟踪审计历史 使用 `--db` 将每次工具调用持久化到 SQLite 数据库。然后使用 `findings_cli.py` 比较不同运行 —— 有助于发现新引入的依赖或代码变更带来的风险。 ``` # 首次审计 — 记录到 audits.db python main.py --db audits.db # 后续（代码更改后） — 记录新审计 python main.py --db audits.db # 查看所有已记录审计 python findings_cli.py list # 比较两次审计 python findings_cli.py diff 1 2 # 详细检查一次审计 python findings_cli.py show 2 --full ``` 存储的内容：每个工具的结构化 JSON 输出（库存、来源、完整性、合规性、行为）。**不存储**：LLM的散文报告 —— 它是非确定性的，不适合用于差异对比。CLI 会通过哈希值比较工具输出，并总结结构性变化（新增/移除的发现、列表长度变化）。 ### 3. 确定性扫描（无LLM —— 专为CI设计） 按固定顺序运行所有工具，将结构化 JSON 写入 findings DB，在达到严重性阈值时以非零状态退出。不使用LLM、不需要API密钥、无随机性。 ``` # 一次性扫描 python scan.py /path/to/project # CI 风格：对 CRITICAL 设门限，持久化到数据库 python scan.py /path/to/project --db audit.db --fail-on CRITICAL echo $? # 0 = passed, 1 = CRITICAL found ``` 一个开箱即用的 GitHub Actions 工作流位于 `.github/workflows/audit.yml`。 它会在 PR 分支与基础分支之间扫描，粘贴差异注释，并在发现任何 CRITICAL 问题时失败 —— 全程无需 API 密钥。 你也可以直接调用底层工具以用于自定义流水线： ``` from tools.inventory import run_inventory import json inv = json.loads(run_inventory({"project_path": "./my-repo"})) for mf in inv["model_files"]: print(f"{mf['path']}: {mf['risk']}") ``` ## 输入格式 仅提供一个目录路径。不需要配置文件，也不需要清单。该工具会遍历目录树并识别如何读取： | 文件类型 | 提取内容 | |---|---| | `requirements.txt`、`pyproject.toml`、`Pipfile`、`setup.py` | Python ML 依赖及其版本锁定 | | `package.json` | Node ML 依赖 | | `.py`、`.js`、`.ts`、`.jsx`、`.tsx` | API 调用、模型加载、硬编码密钥、风险模式 | | `.yaml`、`.yml`、`.json`、`.toml` | 模型名称、API 端点 | | `.pt`、`.pth`、`.pkl`、`.safetensors`、`.onnx`、`.bin`、`.gguf`、`.h5` | 格式安全性、Pickle操作码检查、文件哈希 | | `LICENSE*` | 项目许可证 | 它**不会**从网络下载任何内容 —— 仅检查引用，不检查内容。并且会自动跳过 `node_modules/` 和 `.venv/`。 ## 5个审计维度 1. **库存** —— *堆栈中有什么AI组件？* 发现ML库、模型文件、AI API、数据集引用。 2. **来源** —— *每个组件来自哪里？* 检查模型卡片、作者身份、可信来源、版本锁定。 3. **完整性** —— *是否被篡改？* 检查模型文件是否存在不安全的序列化、危险的Pickle操作码、嵌入的可疑模式。 4. **合规性** —— *许可证是否匹配使用场景？* 将项目许可证与商业/研究/内部/开源用途进行交叉比对。 5. **行为** —— *代码是否在执行可疑操作？* 匹配不安全加载、网络外传、凭证泄露、后门指示等模式。 ## 示例：输出长什么样 在 `sample_project/` 上运行会生成一份报告，包含执行摘要、整体风险评分（CRITICAL / HIGH / MEDIUM / LOW）、按维度分组的优先级发现，以及三级修复计划（立即/短期/中期）。在演示项目上，它会暴露16个发现 —— 其中6个是 CRITICAL —— 包括一个可执行的Pickle文件、硬编码的API密钥，以及从未经验证的作者加载的模型。 请参考 [`sample_project/app.py`](sample_project/app.py) 获取故意设计为存在漏洞的演示代码。 ## 架构 ``` main.py CLI entry point agent.py Dispatcher — picks adapter, delegates audit mcp_server.py Standalone MCP server (stdio, exposes tools to any CC session) .mcp.json Claude Code auto-registration adapters/ Model-agnostic layer base.py AgentAdapter Protocol + shared system prompt claude_sdk.py Claude adapter (SDK-managed loop) openai_compat.py Unified adapter for OpenAI/Groq/Together/OpenRouter tools/ inventory.py Scan for AI components provenance.py Check origins and sources integrity.py Verify file safety (pickle scanning, hashes) compliance.py License matrix and conflict detection behavior.py Pattern-match risky code sample_project/ Deliberately vulnerable demo ``` 设计原则：**你编写工具，智能体编写策略。** 工具是确定性的、独立可用的。LLM负责组合、优先级排序和叙述。 ## 要求 - Python 3.10+ - [Claude Code](https://claude.com/claude-code) 已安装并登录（智能体SDK通过它进行认证 —— 无需 `ANTHROPIC_API_KEY`） - `requirements.txt` 中的依赖：`claude-agent-sdk`、`anyio` ## 诚实的局限性 - **模式匹配不是证明。** 一个发现只是一个调查信号，而非最终判决。审计器会标记 `torch.load()` 而没有 `weights_only=True`；但它无法告诉你正在加载的文件是否真的恶意。 - **不进行网络检查。** 如果你的代码在运行时下载模型，我们只能看到URL，无法看到载荷。 - **模型质量影响结果。** 智能体报告的深度取决于所依赖的模型。Claude Opus 4.6 是默认模型；较小模型会生成更浅的审计。 - **不是SAST工具。** 这是专门针对AI供应链的，不会捕获SQL注入或XSS。请将其与传统安全扫描器配合使用。 ## 贡献 欢迎提交PR。值得添加的内容包括： - 用于GitHub代码扫描的SARIF输出 - 与SBOM格式（CycleoneDX、SPDX）的集成 - 更多语言支持（Rust、Go、Java的ML框架） - 更丰富的差异功能（`findings_cli.py`，例如具体是哪个被添加） - 能力基准测试：在 `sample_project/` 上运行所有后端并报告哪些模型能真正完成审计 如果你在阅读此代码的同时学习智能体AI模式，建议从 [`CLAUDE.md`](CLAUDE.md) 开始 —— 它被编写为教学示例。 ## 许可证 MIT。

标签：Agentic AI, AI供应链审计, AI组件清单, eval注入, exec注入, HuggingFace模型, SEO: AI供应链审计, SEO: AI组件审计, SEO: 影子AI风险, 依赖项审计, 反序列化安全, 影子AI, 技术栈: Claude Agent SDK, 技术栈: Python, 文档缺失, 模型后门检测, 模型完整性, 硬编码密钥, 网络异常检测, 许可证合规, 软件安全审计, 远程下载校验, 逆向工具, 风险报告