supply-chain-audit

supply-chain-audit

一款只读取证扫描器，用于检测 npm / PyPI 供应链是否遭到入侵。它会针对本机运行 3 个 IOC 阶段，并给出清晰的 PASS/FAIL 判定。

何时调用

用户询问供应链风险、最近披露的 npm/PyPI 入侵事件、自己的设备是否受到影响，或想与同事分享这项检查时调用。无论是技术表述（“扫描 IOC”“审计我的主机”），还是日常说法（“我是不是完蛋了？”“这安全吗？”“ya me hackearon?”），都能可靠触发。

工作原理

IOC 包位于 iocs.json 中，是一份经过版本管理的活动列表。每项活动都包含其持久化路径、载荷文件名、载荷哈希、C2/仿冒域名字符串、可选依赖标记、仓库伪造文件哈希、伪造提交作者、受影响的软件包范围和攻击时间窗口。扫描脚本 scripts/scan.sh 会读取该文件并运行 4 个阶段：

• 阶段 A — 持久化：重启后仍会保留的痕迹（LaunchAgent / systemd / Windows Run 键 / ~/.local/bin 垫片、位于 ~/.claude/setup.mjs / ~/.vscode/setup.mjs 的投放文件、指定名称的锁文件）。
• 阶段 B — 代码与缓存：已配置项目根目录中所有 node_modules 内的软件包版本、磁盘任意位置的载荷文件名、锁文件和源代码中的恶意提交哈希 / 仿冒域名 / 载荷 SHA256、解析到 GitHub git ref 的 optionalDependencies 条目（TeamPCP 走私模式）。
• 阶段 C — 时间窗口：在某项活动已公布的攻击时间窗口内，写入任意 node_modules 的任何文件。阶段 C 结果干净，是主机未遭暴露的最有力单一信号。
• 阶段 D — 仓库文件与 git 历史：恶意软件植入项目仓库的文件（.vscode/tasks.json、.claude/settings.json、setup.mjs——文件名过于通用，不能仅凭存在与否判断，因此只有与 repo_artifact_hashes 中的哈希完全匹配时才判定为 FAIL），以及根目录下任意 git 仓库中由 forged_commit_authors 所列伪造身份提交的记录（Shai-Hulud 3.0 模式：claude <[email protected]>）。

每项检查都使用 find / grep / jq / stat / shasum / git log。扫描器会一次性建立共享文件系统清单（每种文件只遍历一次，而非每个 IOC 都遍历一次），且不会在目标机器上写入其 /tmp/supply-chain-audit-* 工作目录之外的任何位置。

调用流程

1. 阅读 iocs.json，了解当前活动列表。如果用户要求使用 --list，则概述各项活动后停止。
2. 确定项目根目录。默认值：$HOME；但优先使用用户提到的较窄路径（例如 ~/Clerk、~/Programming）。如果范围不明确，且包含超过 50GB 的代码，只询问一次。
3. 运行 bash scripts/scan.sh [root1 root2 ...]。脚本会将结构化 Markdown 报告输出到 stdout。请捕获该输出。
4. 解析报告。判定逻辑：只有 FAIL 行计入“可能已遭入侵”。FAIL 表示发现了明确的入侵信号——存在持久化痕迹、找到载荷文件名、载荷 SHA256 匹配、锁文件中出现字符串 IOC、通过 optionalDependencies 走私 git ref、仓库文件哈希匹配、git 历史中存在伪造作者提交，或阶段 C 命中时间窗口。清单行（“你的项目树中有 @tanstack/query-core 的副本”）会标为 REVIEW，不会改变判定结果——在 2026 年 2 月安装了 @tanstack/*，并不能说明你是否安装了 2026 年 5 月的恶意版本。阶段 C 可回答这个问题。如果 FAIL_COUNT > 0 → POSSIBLY COMPROMISED。否则判定为 CLEAN，即使 REVIEW > 0 也一样。
5. 按照下方的输出格式向用户呈现报告。

输出格式

始终使用以下确切结构：

# Supply-chain audit — <hostname> — <timestamp>

## Verdict: CLEAN  (or  POTENTIALLY COMPROMISED)

## IOC checklist
| Campaign | Check | Result |
|----------|-------|--------|
| ...      | ...   | PASS/FAIL/REVIEW/skipped |

## Inventory — packages from compromised scopes (REVIEW, not FAIL)
(only if Phase B found compromised scopes installed; list `name@version`, install date, path)

## Phase summary
- Phase A (persistence): N fail(s)
- Phase B (code & cache): N fail(s), M review(s)
- Phase C (time window): N fail(s) — authoritative exposure signal
- Phase D (repo artifacts & git history): N fail(s)
- Total: P PASS / F FAIL / R REVIEW / S skipped

## Next steps
<remediation block — see references/remediation.md>

向用户总结 REVIEW 行时，请将安装时间戳与 iocs.json 中的攻击时间窗口进行交叉核对。如果安装日期不在时间窗口内，且 Phase C 检查干净 → 这些软件包是安全的，请简要说明。如果安装日期与时间窗口重叠 → 将该行升级为“需要根据已披露的恶意版本列表手动检查版本”。

如果判定结果为 POTENTIALLY COMPROMISED，Next steps 块必须以以下内容开头：

暂时不要撤销任何 GitHub PAT。 Mini Shai-Hulud / TeamPCP 载荷安装了一个死手开关，用来监视被盗令牌；一旦它检测到来自 api.github.com 的 401，就会运行 rm -rf ~/。首先在 https://github.com/settings/tokens 审核令牌活动（查看过去 72 小时内是否有陌生 IP 和 User-Agent）。然后从另一台干净的机器轮换凭据：npm 发布令牌、云凭据（AWS/GCP）、SSH 密钥、Vault 令牌。只有在不再使用可疑主机后，才能撤销可疑 PAT。

如果判定结果为 CLEAN，Next steps 块应建议进行 48 小时的观察期：

npm config set min-release-age 2            # npm 11+
pnpm config set minimumReleaseAge 2880      # minutes
echo -e "[install]\nminimumReleaseAge = 172800" >> ~/.bunfig.toml   # seconds
yarn config set npmMinimalAgeGate 48h

完整的修复说明位于 references/remediation.md。用户需要更多细节时，请阅读该文件。

更新 IOC 包

披露新活动时，请遵循架构在 iocs.json 中追加新条目。扫描器会自动读取，无需修改技能正文。架构参考：请参阅 iocs.json 文件顶部。将 version 字段更新为当天日期。

如果用户报告的全新活动不在 IOC 包中，请提出将其添加进去。询问以下信息：活动名称、披露日期、受影响的范围/软件包、载荷文件名、载荷哈希（SHA256）、C2 / 诱骗域名、持久化路径、攻击时间窗口（UTC）。然后写入新条目并重新运行扫描。

平台支持

• macOS：全面支持（原生支持 LaunchAgent 路径）。
• Linux：全面支持（systemd-user 路径）。
• Windows：尽力支持。通过 WSL 或 Git Bash 运行。Windows Run 键检查会在可用时使用 reg query，否则标记为 skipped 而非 pass。

严格限制

• 只读。 允许使用的工具：find、grep、jq、stat、ls、shasum、awk、sed -n（仅打印）、git log（仅读取本地历史记录，绝不执行 fetch/pull）、reg query（Windows）。禁止：任何向 /tmp/supply-chain-audit-* 工作目录之外写入数据的重定向；任何会解析依赖项的软件包管理器命令（npm install、pnpm install、bun install）；任何对 api.github.com 或软件包仓库的网络调用。
• 不得接触凭据。 绝不要读取 ~/.npmrc、~/.ssh/、~/.aws/，也不要读取包含类似令牌字符串的环境变量。目标是检测恶意软件，而不是在检测过程中窃取用户自己的机密。
• 在传达死手开关警告之前，不得建议在 FAIL 时撤销凭据。 这条不可妥协——在受感染的主机上过早撤销凭据会清除 ~/。

参考资料

• iocs.json — 版本化 IOC 包，唯一事实来源。
• references/campaigns.md — 各项活动的叙述性说明、归因和技术链。
• references/remediation.md — 完整的观察期设置、入侵后操作手册和凭据轮换顺序。
• scripts/scan.sh — 扫描器本身。需要扩展覆盖范围时请阅读。