supply-chain-advisory

概述

供应链攻击通过破坏上游依赖项，绕过传统代码审查。本技能提供用于检测、防止和响应 Python 生态系统中遭破坏软件包的模式。

适用场景

• 发布供应链安全公告后
• 审计新项目或现有项目的依赖项时
• 响应疑似安全事件期间
• 为项目添加 SessionStart 钩子时

不适用场景

• 与依赖项供应链无关的一般 CVE 分诊
• 应用层漏洞扫描（请使用 SAST 工具）
• 许可证合规审计（属于不同的问题）

已知恶意版本屏蔽列表

屏蔽列表位于 ${CLAUDE_SKILL_DIR}/known-bad-versions.json。 以下内容会使用它：

1. SessionStart 钩子：检测到受破坏版本时，在每个会话发出警告
2. make supply-chain-scan：CI／本地扫描目标
3. 本技能：手动审计指南

屏蔽列表格式

{
  "package_name": [{
    "versions": ["x.y.z"],
    "date": "YYYY-MM-DD",
    "description": "What the attack did",
    "indicators": ["files or patterns to search for"],
    "source": "advisory URL",
    "severity": "critical|high|medium"
  }]
}

添加新条目

1. 将条目添加到 ${CLAUDE_SKILL_DIR}/known-bad-versions.json
2. 在受影响的 pyproject.toml 文件中添加版本排除项（!=x.y.z）
3. 在 docs/dependency-audit.md 的 Supply Chain Incidents 下记录
4. 运行 make supply-chain-scan，验证检测是否有效

快速扫描命令

检查机器上所有锁文件中的已知恶意版本

# Scan uv.lock files for a specific compromised version
grep -r "package_name.*version" --include="uv.lock" /path/to/projects

# Search for malicious artifacts
find /path/to/projects -name "suspicious_file.pth" 2>/dev/null

# Check installed versions in virtualenvs
find /path/to/projects -path "*/.venv/lib/*/PACKAGE*/METADATA" \
  -exec grep "^Version:" {} +

验证锁文件哈希完整性

uv.lock 包含每个软件包的 SHA256 哈希。如果软件包在相同版本下重新发布了不同内容，uv sync 将因哈希不匹配而失败。这是你最有效的自动防护措施。

防御层

层	工具	可检测内容
锁文件哈希	uv.lock SHA256	被篡改后重新发布的版本
版本排除项	pyproject.toml !=	全新解析时的已知恶意版本
SessionStart 钩子	sanctum hook	每个会话针对受破坏依赖项的警告
CI 扫描	OSV、Safety	CVE 数据库及安全公告匹配
构件扫描	make supply-chain-scan	恶意文件（.pth、脚本）

局限性

• 零日供应链攻击发生时没有先前的安全公告：攻击窗口期间，锁文件哈希是唯一的自动防御措施
• Safety／CVE 数据库的更新落后于现实中的安全事件
• OSV 覆盖范围更广，但仍是被动响应

完成标准

• 已使用 ${CLAUDE_SKILL_DIR}/known-bad-versions.json 检查范围内的所有锁文件；如有匹配项，报告软件包名称、恶意版本、严重程度和安全公告 URL
• 添加新的已知恶意条目时：在受影响的 pyproject.toml 中添加版本排除项（!=x.y.z），在 docs/dependency-audit.md 中记录条目，并运行 make supply-chain-scan 确认检测有效
• 已验证 uv.lock 的 SHA256 哈希完整性；哈希不匹配导致的 uv sync 失败应明确提示为供应链警告，而不是一般安装错误
• 会话继续之前，构件扫描会在虚拟环境路径中检查恶意文件模式（.pth 文件、意外脚本）