the-missing-pink/ai-repository-security-baseline

# AI 仓库安全基线 ## 为何存在此项目 AI 编码助手如今无处不在。Cursor、Copilot、Claude Code、Codex、Windsurf、Cline、Junie、Devin —— 每位开发者的编辑器中至少有一个处于开启状态，大多数团队会轮换使用多个。它们非常有用、高效，而且坦率地说，一旦你习惯了它们，就很难在没有它们的情况下工作。 但它们也会读取你的代码。它们会读取你的配置文件。它们会读取你指向的任何内容。如果没有适当的引导，它们会欣然窥探你的 `.env` 文件，建议一个实际上不存在（而攻击者已贴心地以该确切名称发布）的包，为了“修复”构建而编辑你的 CI 管道，或者在你要求它“为此函数添加文档”时，将数据库连接字符串粘贴到注释中。 这些行为并非助手心怀恶意。它们只是在遵循指令并试图提供帮助。问题在于，指令通常没有告诉它们*不应该*做什么。 本仓库旨在解决这一问题。 ## 这是什么 一套适用于最常见 AI 代理和 IDE 插件的、即插即用的指令文件。每个文件都指向一个共享文档 —— `AGENTS.md` —— 该文档列出了项目遵循的规则：不要动 `.env` 文件，不要未经询问就添加依赖项，不要修改 CI 管道，要编写测试，要遵守隐私规则，等等。 你只需将这些文件放入你的仓库，填写项目相关的占位符，提交，然后就完成了。从那时起，无论开发者碰巧使用哪个代理，它都会读取自己首选的配置文件，并最终与其他所有人遵循同一套规则。 目标不是让代理变得不那么有用。而是花一次十分钟，设置合理的默认值，然后就不用再操心了。 ## 如何使用 简短版本： 1. 将本仓库中的文件复制到你的项目中。 2. 打开 `AGENTS.md` 并填写标记为 `[PLACEHOLDER]` 的部分（项目名称、技术栈、命名约定等）。大多数代理会主动帮你完成这项工作——它们会读取你的代码并为你提出建议值，等待你批准。 3. 删除你未使用的任何工具配置文件。如果你的团队只使用 Cursor 和 Copilot，就没有必要保留 Aider 或 Devin 的文件。 4. 提交并推送。 就这样。下次有人在仓库中使用代理时，它们会自动识别这些文件。 如果你只想保留最低配置：保留 `AGENTS.md` 和 `.aiignore`。其他文件都是指向这两个文件的、针对特定工具的补充配置。 ## 包含内容 ### 核心中枢 - **`AGENTS.md`** —— 唯一的事实来源。共十五个部分，涵盖项目信息、安全规则、隐私规则、访问限制、测试要求、可访问性、CI/CD 策略、依赖规则以及代理自身的行为准则。这是其他所有文件指向的源头。 ### 工具特定配置 这些文件的存在是因为相关工具会读取其自身文件名。它们都将实际的规则委托给 `AGENTS.md`，因此你无需维护同一内容的十二个副本。 - `CLAUDE.md` —— Claude Code - `.cursor/rules/*.mdc` —— Cursor（六个规则文件，按文件类型划分作用域） - `.github/copilot-instructions.md` —— GitHub Copilot - `.windsurfrules` —— Windsurf - `.clinerules` —— Cline - `.continuerules` —— Continue.dev - `.aider.conf.yml` + `CONVENTIONS.md` —— Aider - `.amazonq/rules/` —— Amazon Q Developer - `.junie/guidelines.md` —— JetBrains Junie - `devin.md` —— Devin - `.sourcegraph/cody.json` —— Sourcegraph Cody - (OpenAI Codex 直接读取 `AGENTS.md`，无需额外文件) ### 忽略文件 这些文件告诉代理哪些文件完全不应该读取 —— `.env`、私钥、云凭证、SSH 密钥等等。思路与 `.gitignore` 类似，但针对的是 AI 工具。 - `.aiignore` —— 权威列表，作为其他文件的参考 - `.cursorignore`, `.clineignore`, `.aiderignore` —— 工具特定的副本 ## 规则实际涵盖的内容 `AGENTS.md` 中的指令围绕六个主要主题组织。以下是每个主题旨在防止的问题。 ### 安全性 最重要的部分。规则要求代理： - 绝对不要读取 `.env` 或任何其他密钥文件。（`.env.example` 可以。） - 不要硬编码 API 密钥、令牌、密码或连接字符串。 - 如果用户不小心将密钥粘贴到提示中，警告他们并建议他们轮换密钥。 - 注意常见的密钥模式（AWS 密钥、JWT、私钥、数据库 URL）并在出现时标记它们。 - 使用参数化查询、验证输入、编码输出。即标准的 OWASP Top 10 安全实践。 - 未经明确许可及提供前后差异对比，不得修改某些文件（CI 配置、Dockerfile、锁文件、基础设施代码、`CODEOWNERS`）。 ### 隐私性 讨论少于安全性，但同样重要： - 不要记录个人身份信息。 - 在错误消息中遮蔽或编辑个人信息。 - 未经真实的同意机制，不得添加跟踪、遥测或分析。 - 静态和传输中的敏感数据需加密。 - 代码应支持显而易见的 GDPR 权利 —— 访问、删除、导出。 ### 访问控制 代理被允许接触什么： - 停留在仓库范围内。不要访问 `~/.ssh`、`~/.aws` 或用户主目录。 - 除任务严格所需外，不得发起出站网络调用。 - 未经确认，不得运行破坏性命令（`rm -rf`、删除数据库、强制推送）。 - 不得安装全局包或修改系统配置。 ### 测试 一条简单的规则：每次提交前必须运行测试。新代码要有新测试。Bug 修复要有回归测试。不要为了通过新代码而禁用现有测试。不要使用 `--no-verify` 来跳过钩子。 ### 可访问性 如果项目包含用户界面，它必须遵循 WCAG 2.1 AA 标准。语义化 HTML、键盘导航、适当的对比度、替代文本 —— 将这些标准期望写下来，让代理在生成组件时心中有数。 ### CI/CD 与供应链 如果代理偏离脚本，可能在这两个领域造成最大破坏： - 未经明确批准，不得修改管道文件（`.github/workflows/`、`.gitlab-ci.yml` 等）。 - 未经询问不得添加依赖项。提议时需包含版本、流行度、许可证和任何已知漏洞。 - 验证包名称 —— 字符相似域名抢注是一种真实的攻击媒介，AI 代理特别容易受其影响，因为它们有时会编造不存在的包名。 - 不要重新生成锁文件。不要抑制漏洞警告。 ## 规则的结构 三点使此方案生效： **单一事实来源。** 每个工具特定文件都很简短，并以“实际规则请阅读 `AGENTS.md`”结尾。当你想更改某些内容时，只需在一个地方更改它。不会产生偏差。 **纵深防御。** 规则告诉代理该做什么。忽略文件防止代理即使尝试也读取不到敏感内容。规则还告诉代理在不确定时如何行事 —— 请求、显示差异、等待批准。 **占位符，而非假设。** 样板文件不会假装了解你的项目。诸如技术栈、命名约定、允许的命令和分支策略等都标记为 `[PLACEHOLDER]`。当代理第一次读取文件时，它通常会通过分析你的仓库来提议填写这些内容。你批准这些更改（或不批准），然后从那时起，该文件就会具体描述你的项目。 ## 为你的项目定制 当你第一次打开 `AGENTS.md` 时，你会看到针对以下内容的占位符部分： - 项目概述与架构 - 语言、框架和数据库 - 文件结构 - 命名约定 - Git 工作流和分支类型 - 允许的命令（构建、测试、检查） - 项目特定的受保护文件 你不必手动填写。在你喜欢的 AI 工具中打开项目并请求帮助。它会读取代码库，提出建议值，向你展示差异，并等待你的确认。规则要求它这样做，而不是擅自重写内容。 你也可以删除任何不需要的部分。如果你构建的是后端服务，可访问性规则就毫无意义。如果你还没有 CI，CI/CD 规则也无用武之地。删除不适用的内容。 ## 贡献 如果你发现缺失的规则、应该支持的工具，或者可以加强的模式，请提交一个 PR。唯一的实际期望是保持一致性：更改应首先落在 `AGENTS.md` 中，然后传播到工具特定的文件。 ## 许可证 Apache 2.0。随意使用。 ## 延伸阅读 如果你想深入了解安全方面： - [面向 LLM 应用的 OWASP Top 10](https://owasp.org/www-project-top-10-for-large-language-model-applications/) - [OWASP 智能体 AI 威胁](https://owasp.org/www-project-agentic-ai-threats/) - [SLSA 框架](https://slsa.dev/)（供应链完整性） - [OpenSSF 记分卡](https://securityscorecards.dev/) - [NIST AI 风险管理框架](https://www.nist.gov/artificial-intelligence/risk-management-framework)

标签：AI安全, AI编码代理, Chat Copilot, CI/CD安全, DevSecOps, Llama, Streamlit, TLS抓取, 上游代理, 代码仓库管理, 分支保护, 安全基线, 安全指南, 安全配置, 提示注入防御, 教学环境, 源代码安全, 秘密扫描, 网络安全研究, 访问控制, 软件安全, 防御加固