supply-chain-audit

供应链审计技能

审计 CI/CD 流水线、容器镜像和语言包生态系统中的软件供应链安全。生成结构化的发现结果，包括严重性评级、file:line 引用和可操作的修复模板。

何时使用此技能

• CI/CD 安全审查：未固定的 Action 引用、权限过多、机密泄露
• 依赖固定：缺少锁定文件、未进行哈希验证、可变的 semver 引用
• 容器供应链：可变的基础镜像标签、非 root 执行、SBOM 生成
• 凭证卫生：从长期有效的机密迁移到 OIDC、主体约束缺失
• 合规映射：SLSA L1-L4 就绪情况评估、SBOM 生成指南
• 合并前门禁：阻止引入高危/严重供应链回归问题的 PR

---

前置条件 — 外部工具检查

运行审计前，检查是否缺少外部工具，并提供安装选项：

from supply_chain_audit.external_tools import check_missing_tools, install_tool

missing = check_missing_tools()
if missing:
    # Show the user what's missing and what each tool does
    for tool in missing:
        print(f"Missing: {tool['name']} — {tool['description']}")
        for opt in tool['install_options']:
            print(f"  Install: {opt}")

    # Ask the user if they want to install
    # If yes, install each one:
    for tool in missing:
        success, msg = install_tool(tool['name'])
        print(f"  {tool['name']}: {msg}")

无需这些工具也可运行审计（离线/降级模式），但发现的问题会更少：

工具	缺少该工具时无法完成的操作
gh	无法通过 GitHub API 将 Action 标签解析为 SHA
crane	无法解析容器镜像摘要
syft	无法生成 SBOM（SPDX/CycloneDX）
grype	无法扫描已知 CVE
cosign	无法验证镜像签名或证明

---

生态系统检测

运行检查前，检测适用的维度：

信号	生态系统	触发的维度
.github/workflows/*.yml	GitHub Actions	1, 2, 3, 4
Dockerfile / docker-compose.yml	容器	5, 12
包含 secrets.* 的 .github/workflows/	凭证	6
*.csproj / NuGet.Config	.NET / NuGet	7
requirements*.txt / pyproject.toml / setup.cfg	Python	8
Cargo.toml / Cargo.lock	Rust	9
package.json / package-lock.json / yarn.lock	Node.js	10
go.mod / go.sum	Go	11

运行所有已触发的维度，并明确报告跳过的维度。

---

12 个审计维度

维度 1-4：GitHub Actions

参见 reference/actions.md

#	名称	检查内容
1	Action SHA 固定	uses: 引用必须为 @<40-char-SHA> # vX.Y.Z
2	工作流权限	顶层设置 permissions: read-all；作业级仅授予最小权限
3	机密泄露	不得在 run: 的 echo/env 中使用机密；设置 ACTIONS_STEP_DEBUG 防护
4	缓存投毒	actions/cache 键冲突；restore-keys 范围过宽

维度 5 和 12：容器

参见 reference/containers.md

#	名称	检查内容
5	基础镜像固定	使用 FROM image@sha256:<digest>，而非 :latest 或 semver 标签
12	Docker 构建链	多阶段构建的最终阶段使用 scratch/distroless；使用非 root 的 USER

维度 6：凭据

参见 reference/credentials.md

#	名称	检查内容
6	OIDC 与长期有效密钥	优先使用 id-token: write OIDC；验证 subject 约束

维度 7：.NET / NuGet

参见 reference/dotnet.md

#	名称	检查内容
7	NuGet 锁定与审计	RestoreLockedMode、已授权的软件源、NuGetAudit 严重性门槛

维度 8：Python

参见 reference/python.md

#	名称	检查内容
8	Python 依赖完整性	--require-hashes、--extra-index-url 风险、仿冒包信号

维度 9：Rust

参见 reference/rust.md

#	名称	检查内容
9	Cargo 供应链	是否已提交 Cargo.lock、build.rs 风险、[patch]/[replace] 的作用范围

维度 10：Node.js

参见 reference/node.md

#	名称	检查内容
10	Node.js 完整性	使用 npm ci 而非 npm install、npx 解析、postinstall 脚本

维度 11：Go

参见 reference/go.md

#	名称	检查内容
11	Go 模块完整性	是否存在并已提交 go.sum、GONOSUMCHECK、replace 指令的作用范围

---

5 步审计工作流

步骤 1：范围检测

# Detect active ecosystems
ls .github/workflows/*.yml 2>/dev/null && echo "GHA detected"
ls Dockerfile docker-compose.yml 2>/dev/null && echo "Containers detected"
ls requirements*.txt pyproject.toml 2>/dev/null && echo "Python detected"
ls package.json 2>/dev/null && echo "Node detected"
ls go.mod 2>/dev/null && echo "Go detected"
ls Cargo.toml 2>/dev/null && echo "Rust detected"
ls *.csproj 2>/dev/null && echo ".NET detected"

记录启用的维度。在报告中跳过未启用的维度并注明。

步骤 2：静态分析（按生态系统）

根据每个参考文件运行相应维度的检查。收集原始发现并记录：

• 维度编号
• 文件路径和行号（file:line）
• 当前值（存在问题的模式）
• 预期值（修复方案）
• 严重性：严重 / 高 / 中 / 信息

步骤 3：严重性评分

将发现映射到与 CVSS 对齐的严重性等级：

严重性	CVSS 范围	示例
严重	9.0-10.0	未固定版本的第三方操作，同时拥有写入权限和密钥访问权限
高	7.0-8.9	可变的操作引用；:latest 容器；作用范围宽泛的长期有效密钥
中	4.0-6.9	缺少 permissions: read-all；未提交 Cargo.lock
信息	0.1-3.9	第一方组织操作使用 Semver 操作引用；仅提供建议的 NuGet 发现

步骤 4：生成报告

生成结构化的 Markdown 报告：

## Supply Chain Audit Report

**Date**: YYYY-MM-DD
**Scope**: [list active ecosystems]
**Skipped**: [list inactive ecosystems with reason]

### Summary

| Severity | Count |
| -------- | ----- |
| Critical | N     |
| High     | N     |
| Medium   | N     |
| Info     | N     |

### Findings

#### CRITICAL-001 · Dim 1 · Unpin third-party action

- **File**: `.github/workflows/release.yml:14`
- **Current**: `uses: actions/checkout@v4`
- **Expected**: `uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2`
- **Fix**: Look up SHA at https://github.com/actions/checkout/releases

### SLSA Readiness

[See reference/sbom-slsa.md for compliance table]

### Recommended Next Steps

1. Fix all Critical findings before next deployment
2. Delegate lock-file issues to `dependency-resolver` skill
3. Install SHA-pinning pre-commit hooks via `pre-commit-manager` skill

步骤 5：修复优先级排序

按以下顺序处理修复：

1. 优先处理严重问题：未固定版本 + 写入权限 + 密钥访问权限的组合
2. 高优先级：生产工作流中的任何可变引用
3. 委派：将锁定文件生成工作交给 dependency-resolver
4. 自动化：通过 pre-commit-manager 强制执行提交前检查
5. 合规性：生成 SBOM、SLSA 来源证明——参见 reference/sbom-slsa.md

---

输出格式约定

• 每项发现都包含 file:line（例如，.github/workflows/ci.yml:23）
• 修复模板可直接复制粘贴，不含需要猜测的占位符
• SHA 查询始终引用官方发布页面 URL
• 每项发现都明确标注严重程度，不得含糊
• 报告以“后续步骤”部分结尾，区分手动修复和可自动化修复

---

集成点

技能	何时委派
dependency-resolver	锁文件冲突、过时的传递依赖、版本不兼容
pre-commit-manager	安装 SHA 固定钩子、强制执行 npm ci、安装 go mod verify 钩子
cybersecurity-analyst	运行时威胁建模、网络暴露分析、事件后审查
silent-degradation-audit	CI 可靠性问题、掩盖安全回归问题的不稳定测试

---

评估场景

有关三个评分场景，请参阅 reference/eval-scenarios.md：

• 场景 A：GitHub Actions 单体仓库 — GHA + Python + Node（植入 7 项发现）
• 场景 B：容器化 Go 服务 — 容器 + Go + 凭据（5 项发现）
• 场景 C：.NET + Rust 混合仓库 — .NET + Rust + SLSA 就绪情况（6 项发现）

---

其他参考资料

• SBOM 生成、CVSS 评分、SLSA L1-L4 映射、修复 PR 工作流
• 调用接口、发现项架构、技能间契约、错误处理
• GitHub Actions SHA 查询：gh api repos/{owner}/{repo}/git/ref/tags/{tag}
• SLSA 框架：https://slsa.dev
• OpenSSF Scorecard：https://securityscorecards.dev

---

相关技能

• dependency-resolver — 锁文件冲突解决
• pre-commit-manager — 自动化质量强制执行钩子
• cybersecurity-analyst — 运行时安全与威胁建模
• silent-degradation-audit — CI 可靠性与回归检测
• pr-review-assistant — 结合理念考量的 PR 审查，包括供应链检查