Supply Chain Guard (SCG)

一个用于 npm/yarn 和 Python（pip/poetry/uv）供应链攻击的应急响应工具包 —— 免费、本地化、零依赖。

SCG 不是一个在覆盖范围上与商业工具竞争的扫描引擎。它是一个 Claude Code 技能和独立 shell 工具包，擅长三件事：(1) 当特定事件发生时，提供快速、可重复的第一响应（"我的机器现在是否受影响？"），(2) 将现有 OSS 扫描器（npm audit、osv-scanner、pip-audit）编排为一次结构化扫描，(3) 记录来之不易的设计卫生经验教训 —— 尤其是针对 AI 开发环境 —— 这是通用扫描器无法覆盖的。

它是在真实事件中构建并经受锤炼的，包括：

[email protected] RAT 事件（2026-03-31） —— npm 维护者账户被接管（UNC1069/DPRK-APT），注入了幽灵依赖 RAT
Starlette BadHost（CVE-2026-48710，2026-05-22） —— Python HTTP 框架 Host 头路径注入 → SSRF/RCE，影响 FastAPI、vLLM、LiteLLM 以及更广泛的 AI 智能体生态系统

v4 新增功能（2026-05-27）

Python 供应链扫描 —— scripts/project-scan-py.sh，支持 pip-audit / osv-scanner / CVE 标记版本检测
CVE 标记版本层（L3-CVE） —— 通过严格的 semver 规范评估跟踪合法包的已知易受攻击版本（开箱即用地包含 BadHost CVE-2026-48710）
设计卫生指南 —— stdio-first MCP 传输、版本固定纪律、GCP 默认计算 SA 编辑器加固（请参阅 SKILL.md §D.7 DesignHygiene）
Guild-CLI Devil lense 集成 —— 从 guild-cli 工作流中将 SCG 作为 Devil lense 调用（请参阅下文"Guild-CLI Devil 集成"）

为何存在

2026 年 3 月 31 日，广泛使用的 axios npm 包（v1.14.1 和 v0.30.4）因维护者账户被接管而遭到入侵，攻击归因于 UNC1069/DPRK-APT（据 Google Threat Intelligence Group 报道）。该攻击注入了一个幽灵依赖（[email protected]），通过 postinstall 脚本部署了一个跨平台 RAT，并伪装成合法的系统进程。

Supply Chain Guard（SCG） 是在事件期间构建的，旨在提供：

即时检测 —— 我的机器或项目现在是否受影响？
结构化评估 —— 严重程度如何？爆炸半径有多大？
引导式响应 —— 带安全确认的分步修复
持续防御 —— 一个 8 门验证框架，以防再次发生

SCG 与现有工具的区别

SCG 不是现有安全工具的替代品。它将多个检测层与结构化验证框架和引导式修复相结合 —— 专为活跃事件期间使用或作为现有工具之外的定期检查而设计。

工具	功能	SCG 的关系
`npm audit`	检查注册表中已知漏洞	SCG 将 npm audit 作为其 L1 层，然后在此基础上添加 IOC 文件系统/网络扫描、恶意包检测和结构化响应工作流
`osv-scanner`	针对 Google OSV 数据库扫描锁文件	SCG 将 OSV 作为其 L2 层。osv-scanner 不会检查文件系统上的 RAT 工件或活跃的 C2 连接
Snyk / Socket.dev	商业 SaaS，提供实时监控、PR 检查、许可证扫描	SCG 免费、本地优先、无需账户、不向第三方发送数据。专为即时应急响应而非持续监控而设计
手动 IR	使用自定义脚本进行临时调查	SCG 提供可重复的框架（8 个验证门、收敛循环、严重性矩阵），而不是每次事件各不相同的临时检查清单

何时使用 SCG：

供应链事件刚刚发生，你需要立即检查你的机器和项目
你想要一个结构化的、可重复的流程来验证入侵已被完全解决
你需要一个无需 SaaS 依赖即可在本地运行的轻量级检查

何时使用其他工具：

你需要持续的实时监控 → Snyk、Socket.dev
你需要许可证合规扫描 → Snyk、FOSSA
你需要超出 npm/yarn 的覆盖范围 → osv-scanner（支持 pip、cargo、go 等）

SCG 是什么（以及不是什么）

我们宁愿诚实地说明边界，也不愿过度推销。SCG 是三件事：

一份以代码形式呈现的应急响应行动手册。 当指定事件发生时（axios RAT、Shai-Hulud、新的 CVE），SCG 将"我是否受影响，如果是该怎么办？"转化为可执行的检查清单 —— 8 个验证门、一个严重性矩阵以及一个修复脚本，其中每一个破坏性操作都需要明确的 [y/N] 确认。这是它的主要价值：商业监控工具不适合提供的快速、结构化的第一响应。
现有 OSS 扫描器的编排器。 L1/L2 层封装了 npm audit / pip-audit / osv-scanner。大部分原始检测能力是借用的；SCG 的贡献在于将它们捆绑为一次扫描，添加注册表工具不会做的文件系统/IOC 检查，并让输出可读且可操作。
真实设计卫生经验教训的文档（SKILL.md §D.7）—— 我们实际遇到或调查过的事情：MCP 传输选择、GCP 默认 SA 加固、安装时执行向量，以及针对 AI 开发工具链的威胁（Shai-Hulud 读取 .claude/settings.json、SANDWORM_MODE 投毒 MCP 配置）。这一细分领域 —— AI 辅助开发的供应链卫生 —— 是 SCG 真正差异化所在。

SCG 刻意不是什么

不是覆盖范围的竞争者。 威胁数据库（SKILL.md D.2、L3 静态列表）是手工维护的 —— 它收录的是我们读到的相关事件，而不是商业实时源跟踪的数万个恶意包。手工策划的列表无法跟上真实的新威胁产生速度，我们也不假装它可以。
不是行为分析引擎。 SCG 匹配已知模式。混淆的载荷和没有公开公告的真正零日漏洞，按设计就不在范围内。
不是持续监控。 它是在事件期间或作为定期扫描运行的时点检查 —— 不是监视依赖图的服务。

SCG 的未来方向

由于手工策划的数据库无法在覆盖范围上获胜，我们有意投资于 SCG 难以被替代的领域，而不是它永远会输的领域：

更深入的应急响应行动手册（#1）—— 更好的第一响应体验、更多的事件模板。
AI 开发环境卫生（#3）—— 针对 Claude Code / Cursor / MCP 服务器及类似工具链的威胁检测和指导，商业供应链扫描器大多不解决这些问题。

静态威胁数据库（#2）将在重大事件发生时持续更新，但它明确不是我们试图竞争的领域。

架构

### 扫描管道

相同的 5 层管道适用于两个生态系统，每一层都有针对特定生态系统的扫描器：```
L1 ──→ L2 ──→ L3 ──→ IOC ──→ LF ──→ assess(SeverityMatrix) ──→ VERDICT

层级	npm/yarn (`project-scan.sh`)	Python (`project-scan-py.sh`)
L1	`npm audit`	`pip-audit`
L2	`osv-scanner` / OSV.dev API	`osv-scanner`
L3	静态列表（恶意 + 仿冒）	静态列表（恶意 / 仿冒 + CVE 标记的版本）
IOC	文件系统 + 网络痕迹	文件系统 + 进程痕迹（Python 风格）
LF	`npm ci --dry-run` + 完整性计数	锁文件完整性（uv.lock / poetry.lock / requirements*.txt）

两条流水线都会汇入同一个 SeverityMatrix 和 Devil Gate Framework。

快速开始

作为 Claude Code 技能

将 SKILL.md 复制到你的 Claude Code 技能目录：```bash

Global (all projects)

cp SKILL.md ~/.claude/skills/supply-chain-guard.md

Or project-specific

mkdir -p .claude/skills cp SKILL.md .claude/skills/supply-chain-guard.md

然后在 Claude Code 中调用：```
> /supply-chain-guard
> "Check this project for supply chain issues"
> "Is my machine affected by the axios compromise?"

作为独立脚本```bash

Environment-wide scan (IOC + all projects) [READ-ONLY]

./scripts/env-scan.sh

npm/yarn project scan (requires package.json in cwd) [READ-ONLY]

./scripts/project-scan.sh

Python project scan (requires pyproject.toml / requirements*.txt / poetry.lock / uv.lock in cwd) [READ-ONLY, added in v4]

./scripts/project-scan-py.sh

IOC-only scan (filesystem + network artifacts) [READ-ONLY]

./scripts/ioc-scan.sh

Remediation (interactive, every action requires confirmation)

./scripts/respond.sh --critical # Full RAT cleanup (npm + Python) ./scripts/respond.sh --high axios 1.14.0 # Pin npm package to safe version ./scripts/respond.sh --high urllib3 2.7.0 # Pin Python package (auto-detects pip/poetry/uv)

> **Python 修复方案在设计上偏向保守。** 对于 npm，`--high` 会自动应用
> override。对 Python 则是 *引导式*：它会检测你的包管理器
> (pip/poetry/uv)，打印出精确的固定（pin）命令，并且只执行安全步骤 —
> 会显示修改锁文件和重建 venv 的命令供你运行。这样可避免
> 误报导致在碎片化的 Python 打包生态系统中触发连带性强制重装。

对于包含多语言（npm + Python）的仓库，请分别在相关子目录中依次运行两个项目扫描器。

> **安全设计：** 所有扫描脚本均为严格只读 — 它们绝不修改、删除或安装任何内容。修复脚本 (`respond.sh`) 是唯一执行破坏性操作的脚本，并且**每个操作都需要明确的 `[y/N]` 确认**，默认值为 NO。

---

## 扫描模式

### 环境扫描 (`env_scan`)

扫描整个开发机器以查找失陷指标。

| 检查 | 描述 |
|-------|-------------|
| **IOC：文件系统** | RAT 二进制文件、持久化机制、暂存文件 |
| **IOC：网络** | 活跃的 C2 连接（IP + 域名） |
| **IOC：进程** | 正在运行的恶意进程 |
| **跨项目** | 扫描所有 `package-lock.json` 文件以查找已受侵害的版本 |
| **恶意包** | 任何锁文件中的已知恶意包名 |

**触发词：** "this PC"、"environment check"、"machine-wide"

### 项目扫描 — npm/yarn (`project_scan`)

对单个 npm/yarn 项目进行深度扫描。在包含 `package.json` 的目录中运行。

| 层级 | 扫描器 | 描述 |
|-------|---------|-------------|
| **L1** | `npm audit` | 通过 npm registry 发现的已知漏洞 |
| **L2** | `osv-scanner` / OSV.dev API | Google 的开源漏洞数据库 |
| **L3** | 静态列表 | 硬编码的已知恶意包检查 |
| **IOC** | 文件系统 + 网络 | RAT 工件检测 |
| **LF** | 锁文件完整性 | `npm ci --dry-run` + 完整性哈希计数 |

**触发词：** "this project"、"npm audit"、或当前工作目录中存在 `package.json`

### 项目扫描 — Python (`project_scan_py`，v4 新增)

对单个 Python 项目进行深度扫描。在包含 `pyproject.toml`、`requirements*.txt`、`poetry.lock` 或 `uv.lock` 的目录中运行。

supply-chain-guard

最受欢迎