ZarK/ai-supply-chain-guard
GitHub: ZarK/ai-supply-chain-guard
一个用于AI智能体的供应链防御技能，帮助在依赖管理和工具集成中防范安全风险。
Stars: 12 | Forks: 2
# AI 供应链防护
面向智能体的便携式、工具无关供应链防御技能安装指南。
如果某人向您提供此仓库 URL 并说了类似"安装此技能 URL"之类的话，请安装此仓库中的 `supply-chain-guard/` 文件夹。切勿运行此仓库中的包管理器安装、设置脚本、生成器或一键式安装程序。可安装单元是纯 Markdown 文件：`supply-chain-guard/SKILL.md`，以及 `supply-chain-guard/references/` 下的可选参考文件。
仓库 URL：
```
https://github.com/ZarK/ai-supply-chain-guard
```
## 首次使用
安装后，阅读已安装的技能并将其应用于当前仓库：
```
Use the supply-chain-guard skill before dependency, package-manager, CI, release, IDE-extension, MCP, or AI-agent-tool work in this repo. First inspect the manifests, lockfiles, workflows, package-manager config, and agent/tooling config. Then report what protections are missing before making changes.
```
对于人类用户，给您的智能体最简洁的指令是：
```
Install this skill and use it before dependency or CI work: https://github.com/ZarK/ai-supply-chain-guard
```
## 智能体安装约定
您正在安装一个本地智能体技能，而非一个软件包。
1. 将仓库获取到临时目录。
2. 验证 `supply-chain-guard/SKILL.md` 是否存在。
3. 将完整的 `supply-chain-guard/` 目录复制到用户的智能体技能位置。
4. 如果目标工具不支持原生技能，请添加一个小的桥接指令，指向已安装的技能。
5. 通过读取已安装的 `SKILL.md` 进行验证。
6. 在依赖项、包管理器、CI、发布、IDE 扩展、MCP 或 AI 智能体工具相关工作之前开始使用此技能。
不要将完整技能重复复制到多个指令文件中。保留一份技能规范副本，并使用指向它的桥接。
## 智能体快速安装
当用户未指定具体工具时，请使用此流程。
```
repo_tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/ZarK/ai-supply-chain-guard.git "$repo_tmp/ai-supply-chain-guard"
test -f "$repo_tmp/ai-supply-chain-guard/supply-chain-guard/SKILL.md"
```
首选的项目本地安装：
```
mkdir -p .agents/skills
rm -rf .agents/skills/supply-chain-guard
cp -R "$repo_tmp/ai-supply-chain-guard/supply-chain-guard" .agents/skills/supply-chain-guard
test -f .agents/skills/supply-chain-guard/SKILL.md
```
可移植的全局安装：
```
skills_dir="${AGENT_SKILLS_DIR:-$HOME/.agents/skills}"
mkdir -p "$skills_dir"
rm -rf "$skills_dir/supply-chain-guard"
cp -R "$repo_tmp/ai-supply-chain-guard/supply-chain-guard" "$skills_dir/supply-chain-guard"
test -f "$skills_dir/supply-chain-guard/SKILL.md"
```
如果您的智能体拥有原生技能目录，请使用该目录替代 `.agents/skills`，但需保留此布局：
```
/
`-- supply-chain-guard/
|-- SKILL.md
`-- references/
```
## 桥接指令
对于读取仓库指令（如 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`.github/copilot-instructions.md`、Cursor 规则、Windsurf 规则或类似文件）的工具，请添加此桥接：
```
# 供应链防护
Before any install, update, scaffold, package-manager command, CI action/workflow change, IDE/MCP/agent-tool change, release job, or dependency-provided tool execution, read and follow `.agents/skills/supply-chain-guard/SKILL.md`.
For deeper guidance, load only the relevant file from `.agents/skills/supply-chain-guard/references/`.
```
对于仅全局安装，请将桥接中的路径调整为全局技能位置，例如 `~/.agents/skills/supply-chain-guard/SKILL.md`。
## 此技能是什么
AI 供应链防护是一种智能体技能，它使编码智能体和人工审查员在处理依赖项和开发者工具时具备防御性。旨在减少可预防的暴露风险，包括：包被入侵、CI 被入侵、恶意安装脚本、依赖项混淆、不安全的生成器、缓存投毒、被入侵的操作、可疑 IDE 扩展、高风险 MCP 服务器以及 AI 智能体工具持久化。
该技能指导智能体：
- 当现有代码足够时，优先不引入新依赖项
- 锁定精确版本并保留锁文件
- 在采用新发布包之前，阻止或审查发布周期较短的包
- 默认禁用生命周期脚本
- 将包管理器命令和项目生成器视为代码执行
- 在支持的情况下验证签名、来源、证明、仓库、工作流、引用、构建器和构件摘要
- 记住有效来源证明的是起源或完整性，而非代码安全性
- 将 CI 操作、可重用工作流、缓存、构件、发布作业、IDE 扩展、MCP 服务器和智能体工具视为依赖项
- 将有风险的安装与有价值的凭据隔离
- 在供应链操作存在歧义或高风险时，停止并等待人工批准
- 当恶意代码可能已执行时，指导事件响应
## 何时调用它
在接触以下任何内容之前使用此技能：
- 包清单、依赖项文件、锁文件或包管理器配置
- `npm`、`npx`、`pnpm`、`yarn`、`bun`、`deno`、`uv`、`pip`、`poetry`、`pipenv`、`cargo`、`go`、`mvn`、`gradle`、`dotnet`、`bundle`、`composer`、`pod`、包安装程序或项目生成器
- GitHub Actions、可重用工作流、工作流模板、CI 缓存、构件、发布作业或发布管道
- Dockerfiles、容器镜像引用、二进制文件下载、一键式 shell 安装程序或生成的工具链
- VS Code/Open VSX/Cursor/Windsurf/JetBrains 扩展、MCP 配置、AI 智能体工具或自动化权限
- 活跃的安全公告、可疑的依赖项变更、意外脚本、新的传递性来源或疑似凭据暴露
## 兼容性模式
可安装的技能遵循通用的智能体技能结构：
```
supply-chain-guard/
|-- SKILL.md
`-- references/
|-- attack-patterns.md
|-- ci-and-repository-hardening.md
|-- ecosystem-playbooks.md
|-- incident-response.md
|-- npm-trusted-publishing.md
|-- package-manager-configs.md
|-- threat-model-and-rules.md
`-- tooling.md
```
兼容性选择：
- `SKILL.md` 是唯一的必需入口点。
- YAML 前置元数据包含 `name` 和 `description`。
- 详细信息位于 `references/` 目录下的一级文件中，以便智能体仅加载所需内容。
- 没有隐藏的安装程序、二进制文件、包清单或特定于工具的运行时依赖。
- 根目录的 README 用于安装和导向；技能本身是 `supply-chain-guard/` 目录。
## 版本控制与发布
发布版本使用 Git 标签，例如 `v1.0.0`。
源 `SKILL.md` 不内嵌版本号。这避免了前置元数据与仓库发布版本之间的漂移。要锁定安装，请使用 Git 标签或提交 SHA，而非分支名称。
发布构件仅打包可安装的 `supply-chain-guard/` 目录，并附带 SHA-256 校验和。
## 此技能教导的内容
欲了解更深入的教程，请阅读 [`supply-chain-guard/references/threat-model-and-rules.md`](supply-chain-guard/references/threat-model-and-rules.md)。它解释了这些规则存在的原因，包括：
- 发布周期较短但暂时携带恶意版本的合法软件包
- 安装时脚本、源码构建、生成器和一次性 CLI 作为代码执行
- 用于紧急安全修复的包年龄门槛和冷却期例外
- 来源证明、可信发布、签名和证明作为身份/完整性信号，而非恶意软件判定
- GitHub Actions、可重用工作流、缓存作用域、构件、标签和发布作业作为供应链依赖项
- `pull_request_target`、投毒缓存、可变操作标签以及过于宽泛的 OIDC 权限
- npm 可信发布、分阶段发布、精确身份匹配、安全发布诊断和包引导流程
- 信任降级、特殊来源、Git 依赖、tarball 和注册表混淆
- IDE 扩展、MCP 服务器、AI 智能体配置和编辑器市场作为可执行的供应链表层
- 当恶意依赖项可能已暴露工作站、CI、SCM、注册表或云凭据时的事件响应
## 推荐的配套控制措施
此技能会改变智能体的行为。当用户环境支持时，应将其与实际的控制措施结合使用：
- 在开发者机器和 CI 运行器上安装时进行恶意软件阻止、注册表代理或包智能检查
- 精确版本、冻结安装、签入的锁文件以及默认禁用生命周期脚本
- 原生包年龄门槛，如 npm `min-release-age`、pnpm `minimumReleaseAge`、Yarn `npmMinimalAgeGate`、Bun `minimumReleaseAge`、Deno `minimumDependencyAge`、uv `exclude-newer` 和 pip `--uploaded-prior-to`
- 依赖项审查、漏洞警报、代码扫描、具有推送保护的密钥扫描、签名提交和仓库规则集
- 受信发布、短期 OIDC 凭据、受保护的发布环境以及构件/来源证明验证
- 隔离的开发容器、虚拟机、Codespaces 或用于有风险依赖项工作的短期运行器
仅当第三方产品符合用户的环境、预算和信任模型时才使用它们。此技能不与任何供应商绑定。
## 示例提示
有关涵盖仓库审查、依赖项审查、依赖项差异、CI/发布审查、事件分类和全面审查的简短提示，请参阅 [`examples/README.md`](examples/README.md)。
## 在智能体编码工具中安装
工具行为变化迅速。当工具当前文档与此表不同时，请优先参考其文档。最安全的可移植模式始终相同：完整安装 `supply-chain-guard/`，然后添加一个指向已安装 `SKILL.md` 的桥接指令。
| 工具 | 最佳安装目标 | 智能体设置指令 |
| --- | --- | --- |
| Devin | `.agents/skills/supply-chain-guard/SKILL.md` | 提交可移植技能文件夹。在依赖项、包管理器、CI、发布、IDE 扩展、MCP 或智能体工具相关工作之前，要求 Devin 使用 `supply-chain-guard`。 |
| Claude Code | `.claude/skills/supply-chain-guard/SKILL.md` 或 `~/.claude/skills/supply-chain-guard/SKILL.md` | 将技能文件夹复制到 Claude Code 的技能目录。如果项目还需要仓库级激活，请添加 `CLAUDE.md` 桥接。 |
| OpenAI Codex / Codex CLI | `.agents/skills/supply-chain-guard/` 加上 `AGENTS.md` | 提交可移植安装和桥接。若要全局使用，如果客户端支持技能，请将技能文件夹复制到用户的全局技能目录。 |
| GitHub Copilot 编码代理 / Copilot Chat | `AGENTS.md` 和 `.github/copilot-instructions.md` | 提交技能文件夹并将桥接文本添加到仓库指令中。 |
| VS Code Copilot 代理模式 | `AGENTS.md` 或 `.github/instructions/*.instructions.md` | 添加一个适用于清单、锁文件、工作流、Dockerfiles、发布脚本以及智能体/MCP 配置的桥接。 |
| Cursor | `.cursor/rules/supply-chain-guard.mdc` 和/或 `AGENTS.md` | 添加一个指向 `.agents/skills/supply-chain-guard/SKILL.md` 的 Cursor 规则。如果可用，请使用始终激活模式。 |
| Windsurf Cascade | `.windsurf/rules/supply-chain-guard.md` 和/或 `AGENTS.md` | 添加一个包含桥接文本的工作区规则。保留 `AGENTS.md` 用于共享的仓库上下文。 |
| Sourcegraph Amp | `AGENTS.md` | 提交桥接并保持完整技能位于 `.agents/skills/supply-chain-guard/` 下。 |
| Google Gemini CLI | `GEMINI.md` 和/或 `AGENTS.md` | 将桥接添加到 `GEMINI.md`。将可移植技能保留在 `.agents/skills/` 中。 |
| Google Jules | `AGENTS.md` | Jules 兼容的设置是可移植的 `AGENTS.md` 桥接加上技能文件夹。 |
| Replit Agent | `.agents/skills/supply-chain-guard/SKILL.md`、`replit.md` 或 `custom_instruction/instructions.md` | 将技能文件夹包含在项目模板中。将桥接添加到项目或组织指令中。 |
| JetBrains Junie | `.junie/AGENTS.md` 或已配置的准则路径 | 将桥接添加到 Junie 准则，并将完整技能保留在 `.agents/skills/` 中。 |
| Amazon Q Developer CLI | 自定义智能体指令或项目提示 | 创建一个指向已安装技能文件夹的自定义 Q CLI 智能体或项目指令。 |
| Factory Droid | `.factory/skills/supply-chain-guard/SKILL.md`、`AGENTS.md` 或 `.factory/droids/*.md` | 如果支持，将技能文件夹复制到 Factory 技能目录，并为共享的仓库上下文保留一个可移植的桥接。 |
| OpenCode | `AGENTS.md` 或 `opencode.json` 指令 | 在 `AGENTS.md` 中提交桥接；如果使用显式配置，请将相同的桥接添加到 `opencode.json` 指令中。 |
| OpenHands | `.openhands/microagents/supply-chain-guard.md` | 添加一个包含桥接的仓库微代理。除非通过此技能的审查，否则不要在设置脚本中放置依赖项安装命令。 |
| Aider | `CONVENTIONS.md` 或已配置的读取文件 | 将桥接添加到 `CONVENTIONS.md`，或配置 Aider 读取一个指向 `SKILL.md` 的小文件。 |
| Cline | `.clinerules/supply-chain-guard.md` | 添加一个包含桥接的 Cline 规则，并将完整技能保留在 `.agents/skills/` 中。 |
| Roo Code | `.roo/rules/supply-chain-guard.md` | 添加一个包含桥接的 Roo 规则。如果 Roo 读取 `AGENTS.md`，请同时在其中保留可移植的桥接。 |
| Kilo Code | `.kilocode/rules/supply-chain-guard.md` 和/或 `AGENTS.md` | 添加一个包含桥接的 Kilo 规则，并将可移植技能文件夹保留在仓库中。 |
| Continue | `.continue/rules/supply-chain-guard.md` | 添加一个指向 `.agents/skills/supply-chain-guard/SKILL.md` 的 Continue 规则。 |
| Qodo Gen | 聊天偏好自定义指令或 `agents/*.toml` | 在自定义指令下添加桥接，或创建一个自定义智能体/工作流 TOML，其指令指向该技能。 |
| Tabnine Agent | 自定义命令或聊天自定义指令 | 创建一个包含桥接的自定义命令，例如 `/supply-chain-guard`，如果可用，也可以将桥接粘贴到自定义指令中。 |
| Warp 代理模式 | `AGENTS.md` 或 Warp Drive 代理提示 | 在 `AGENTS.md` 中提交可移植的桥接；也可以选择将相同的桥接保存为可重用的 Warp 代理提示。 |
| Zed 代理 / ACP 智能体 | `AGENTS.md` | 在 `AGENTS.md` 中使用可移植桥接；当 Zed 驱动兼容的外部编码代理时，此方式也有效。 |
| Goose | `.agents/skills/supply-chain-guard/SKILL.md`、`~/.agents/skills/supply-chain-guard/SKILL.md`、`AGENTS.md` 或 `.goosehints` | Goose 支持可移植技能。对于仓库使用项目安装，对于用户级保护使用全局安装。 |
| SWE-agent | 任务提示或框架级指令文件 | 将桥接包含在任务提示或框架指令中，并将技能文件夹挂载到工作区。 |
| Augment Code | 规则或准则 | 添加一个包含桥接的规则/准则，并将完整技能保留在 `.agents/skills/` 中。 |
| Trae | 项目规则或 `.trae/skills/supply-chain-guard/`（如果可用） | 优先使用指向 `.agents/skills/supply-chain-guard/SKILL.md` 的项目规则。如果客户端支持技能，请将文件夹复制到其技能目录。 |
| Mistral Vibe | `.vibe/skills/supply-chain-guard/SKILL.md`、`~/.vibe/skills/supply-chain-guard/SKILL.md` 或 `AGENTS.md` | 将技能文件夹复制到 Vibe 的项目或全局技能目录，并为仓库上下文保留一个可移植的桥接。 |
## 来源与参考
技能格式和仓库指令：
- [Agent Skills：概述与规范](https://agentskills.io/home)
- [AGENTS.md：用于指导编码代理的开放格式](https://agents.md/)
智能体和编辑器设置参考：
- [Devin 文档：技能](https://docs.devin.ai/product-guides/skills)
- [Claude Code 文档：技能](https://code.claude.com/docs/en/skills)
- [Goose 文档：使用技能](https://goose-docs.ai/docs/guides/context-engineering/using-skills/)
- [GitHub 文档：Copilot 的仓库自定义指令](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions)
- [Cursor 文档：规则](https://cursor.com/docs/rules)
- [Windsurf 文档：规则与 AGENTS.md](https://docs.windsurf.com/windsurf/cascade/memories)
- [Gemini CLI 文档：GEMINI.md 上下文文件](https://google-gemini.github.io/gemini-cli/docs/cli/gemini-md.html)
- [Replit 文档：自定义模板和技能](https://docs.replit.com/teams/custom-templates)
- [JetBrains 文档：Junie 准则](https://www.jetbrains.com/help/ai-assistant/junie-agent.html)
- [OpenHands 文档：仓库技能](https://docs.openhands.dev/overview/skills/repo)
- [Cline 文档：Cline 规则](https://docs.cline.bot/customization/cline-rules)
- [Continue 文档：规则](https://docs.continue.dev/customize/rules)
- [Kilo Code 文档：规则和 AGENTS.md 迁移](https://kilo.ai/docs/getting-started/migrating)
- [Aider 文档：约定文件](https://aider.chat/docs/usage/conventions.html)
- [Qodo 文档：Agent TOML 文件](https://docs.qodo.ai/qodo-ide/agent/workflows/agent-toml-file)
- [Tabnine 文档：自定义命令](https://docs.tabnine.com/main/getting-started/tabnine-cli/features/commands)
- [Sourcegraph Amp 手册：AGENTS.md](https://ampcode.com/manual)
- [Factory 文档：技能](https://docs.factory.ai/cli/configuration/skills)
- [Factory 文档：AGENTS.md](https://docs.factory.ai/cli/configuration/agents-md)
- [Mistral 文档：Vibe 智能体与技能](https://docs.mistral.ai/mistral-vibe/agents-skills)
- [Google Jules 文档：AGENTS.md 支持](https://jules.google/docs/changelog/2025-06-20/)
- [Augment 文档：规则与准则](https://docs.augmentcode.com/setup-augment/guidelines)
- [Zed 文档：代理面板](https://zed.dev/docs/ai/agent-panel)
- [Warp 文档：使用代理](https://docs.warp.dev/agent-platform/local-agents/interacting-with-agents/)
事件案例研究：
- [TanStack：npm 供应链入侵事后分析](https://tanstack.com/blog/npm-supply-chain-compromise-postmortem)
- [Socket：TanStack npm 包在 Mini Shai-Hulud 攻击中被入侵](https://socket.dev/blog/tanstack-npm-packages-compromised-mini-shai-hulud-supply-chain-attack)
- [Aikido：Mini Shai-Hulud 回归，TanStack 和其他包被入侵](https://www.aikido.dev/blog/mini-shai-hulud-is-back-tanstack-compromised)
- [Socket：活跃的供应链攻击入侵 npm 上的 AntV 包](https://socket.dev/blog/antv-packages-compromised)
- [Aikido：Mini Shai-Hulud 入侵数百个 AntV 包](https://www.aikido.dev/blog/mini-shai-hulud-antv-npm-supply-chain-attack)
供应链安全指南：
- [GitHub 良好架构：防御依赖项供应链攻击](https://wellarchitected.github.com/library/application-security/recommendations/managing-dependency-threats/)
- [GitHub 文档：关于供应链安全](https://docs.github.com/en/code-security/concepts/supply-chain-security/about-supply-chain-security)
- [GitHub 文档：关于依赖项审查](https://docs.github.com/en/code-security/concepts/supply-chain-security/about-dependency-review)
- [GitHub 文档：GitHub Actions 安全使用参考](https://docs.github.com/en/actions/reference/security/secure-use)
- [GitHub 文档：构件证明](https://docs.github.com/en/actions/concepts/security/artifact-attestations)
- [NIST SSDF SP 800-218 v1.1](https://csrc.nist.gov/pubs/sp/800/218/final)
包管理和注册表控制：
- [npm 文档：配置](https://docs.npmjs.com/cli/v11/using-npm/config)
- [npm 文档：可信发布](https://docs.npmjs.com/trusted-publishers/)
- [pnpm 文档：设置](https://pnpm.io/settings)
- [Yarn 文档：安全](https://yarnpkg.com/features/security)
- [Bun 文档：bun install](https://bun.com/docs/pm/cli/install)
- [Deno 文档：approve-scripts](https://docs.deno.com/runtime/reference/cli/approve_scripts/)
- [uv 文档：设置](https://docs.astral.sh/uv/reference/settings/)
- [pip 文档：pip install](https://pip.pypa.io/en/stable/cli/pip_install/)
- [PyPI 文档：可信发布者](https://docs.pypi.org/trusted-publishers/)
可选的扫描器和加固工具：
- [OSV-Scanner](https://github.com/google/osv-scanner)
- [OpenSSF Scorecard](https://github.com/ossf/scorecard)
标签：AI 代理, CI/CD 安全, DevSecOps, TLS抓取, 上游代理, 代理工作流, 代理技能, 供应链攻击防御, 供应链防御, 依赖管理, 包管理器安全, 安全技能, 安全检查, 安装指南, 工具无关, 数据投毒防御, 网络安全研究, 软件安全, 防御加固