SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场python-supply-chain

python-supply-chain

安全与审计

查看项目

更新于 10-16 07:50

技能介绍

用途

python-supply-chain 用于在 GitHub 上的 Python 包仓库中安装分层的供应链控制措施。它面向的场景是：攻击面已从代码本身转向自动化流程和发布后的最初数小时，因此需要多层防护，且机器人产出的 PR 应与人工 PR 受到同等审查。

该技能明确列出不适用的情况：CI 质量门禁工作流、分支规则集、action SHA 固定、zizmor 属于 python-ci 技能；PyPI 可信发布（OIDC）和标签触发的发布工作流属于 python-release 技能；pre-commit 钩子接线（含本地 gitleaks 钩子）属于 python-precommit 技能；打包与锁定文件设置（uv init、pyproject.toml）属于 python-packaging；Agent 钩子 / AGENTS.md 规则属于 agent-guardrails。本技能仅通过 CODEOWNERS 保护 agent 配置路径。活跃事件响应超出凭据轮换基础范围时应升级给人工，不要尝试对实时入侵进行自主清理。

主要能力与工作流程

技能按顺序执行以下步骤，每一步独立有价值，可在用户范围结束时停止。更改 GitHub 设置的步骤需要 gh 以仓库管理员权限认证，否则打印命令供用户自行运行。

  1. 审计当前姿态：从仓库根目录运行捆绑的只读检查器 python3 "${CLAUDE_SKILL_DIR}/scripts/check_supply_chain.py" --root .（文件级检查）或加 --github（通过 gh 检查 GitHub 侧设置）。它按控制项打印 PASS|WARN|FAIL|NOTE 行，FAIL 时以非零退出。修复 FAIL，将 WARN 视为待办。不要重复已存在的控制，应调整它。

  2. 基线：已提交的锁定文件。所有控制都假设依赖集已固定并提交：uv.lock（首选）、poetry.lock/pdm.lock，或哈希固定的 requirements（pip-tools 的 --generate-hashes）。若无锁定文件，属于 python-packaging 问题，应标记并停止。

  3. 依赖更新自动化（Dependabot）：编写 .github/dependabot.yml，包含 uv 或 pip 生态条目、每周计划、cooldown（default-days: 7）、分组 minor/patch 更新，以及 github-actions 条目。关键决策：cooldown 是供应链控制而非计划本身，它延迟采用新发布版本，且对安全公告更新自动绕过；分组 minor+patch 是解决 PR 噪音的公认方案，major 保持不分组；绝不对机器人 PR 一概自动合并。Renovate 是需要配置即代码灵活性时的替代方案，其等价物是 minimumReleaseAge。只选一个机器人。

  4. 锁定文件漏洞审计（pip-audit）：从锁定文件导出后审计，例如 uv export --format requirements-txt --no-emit-project -o /tmp/audit-req.txt 然后 uvx --from pip-audit==2.10.1 pip-audit -r /tmp/audit-req.txt --no-deps。不要运行不带 -r 的裸 uvx pip-audit，它会审计自身临时环境而非项目。--no-deps 因导出已完全固定而正确。报告每个包的修复版本，不要盲目升级全部，避免在自动化中使用 pip-audit --fix。替代方案：osv-scanner、uv audit（预览）。

  5. 解析新鲜度窗口（uv 项目）：在 pyproject.toml 中添加 [tool.uv] exclude-newer = "2026-06-27T00:00:00Z" 或相对窗口 exclude-newer = "7 days"，并运行 uv lock。注意固定时间戳会冻结解析直到有人更新，且与 Dependabot cooldown 不同，它也会延迟安全修复，因此两者都要运行。

  6. 密钥扫描、推送保护与 CI 兜底：通过 gh api 启用 secret_scanning 和 secret_scanning_push_protection。推送保护在密钥进入历史前阻止，但只覆盖高置信度模式子集，需添加 CI gitleaks 扫描作为兜底。若发现密钥，先轮换凭据。

  7. 代码扫描（CodeQL）：纯 Python 仓库默认设置即可，gh api -X PATCH "repos/{owner}/{repo}/code-scanning/default-setup" -f state=configured。公开仓库免费，私有仓库需 GitHub Code Security 许可。

  8. 针对自动化定义路径的 CODEOWNERS：注意最后匹配规则生效，将通配规则放最前，安全路径放后。CODEOWNERS 在启用“要求代码所有者审查”前不强制执行，且无写权限的所有者会被静默忽略。

  9. 姿态仪表盘（OpenSSF Scorecard，可选）：添加每周工作流获取 0–10 分，视为分诊仪表盘而非门禁。

  10. SBOM 与发布来源证明：两条 SBOM 路径——仓库级 SPDX（gh api "repos/{owner}/{repo}/dependency-graph/sbom" --jq .sbom > sbom.spdx.json）和构建时 CycloneDX（uvx --from cyclonedx-bom==7.3.1 cyclonedx-py requirements /tmp/sbom-req.txt -o sbom.cdx.json）。发布时用 actions/attest-build-provenance 和 actions/attest-sbom 证明产物。诚实说明：证明只证明构建位置和方式，不证明安全。

  11. 重新审计并交接：重跑步骤 1，应无 FAIL。列出剩余 WARN/NOTE 及一行原因。

输出规格

完成状态包括：.github/dependabot.yml 含 pip 或 uv 生态条目、每周计划、cooldown、分组 minor/patch 及 github-actions 条目；已提交锁定文件；有文档的固定 pip-audit 调用（或计划扫描）；密钥扫描+推送保护已启用（或提供确切命令）；CodeQL 已启用；CODEOWNERS 覆盖 /.github/ 和 agent 配置路径；可选 Scorecard 工作流、SBOM 产物、证明步骤；scripts/check_supply_chain.py --root . 退出 0。

失败模式与注意事项

不带 -r 的 uvx pip-audit 审计错误环境并报告零发现；Dependabot cooldown 可能卡住频繁发布的依赖；包管理器级 cooldown 会阻止安全修复而 Dependabot 的不会；cooldown 对传递依赖未经验证；机器人 PR 携带不应得的信任；Dependabot 不对 SHA 固定的 action 告警；gitleaks-action 对组织仓库需要许可证密钥；CODEOWNERS 最后匹配生效；推送保护是子集过滤器；Scorecard 可被博弈；安装 Python 包会执行代码，切勿为检查而安装，先在 inspector.pypi.io 阅读，警惕仿冒名和 LLM 幻觉包名（slopsquatting）；免费层边界：依赖图、Dependabot 告警和安全更新处处免费，密钥扫描和 CodeQL 仅公开仓库免费。

文件

references/dependabot.md（完整注释的 dependabot.yml、cooldown 语义与 bug 细节、Renovate 比较、噪音调优、自动合并政策证据）；references/scanning-and-provenance.md（gitleaks/TruffleHog CI 工作流、高级 CodeQL 工作流、Scorecard 工作流、SBOM/证明片段与权限、验证命令）；scripts/check_supply_chain.py（只读姿态审计，--github 增加 GitHub 设置检查，FAIL 时非零退出）。