rules

你有没有过这样的经历：AI 助手帮你写了一段代码，你很开心地点了采纳，结果上线后发现里面有 SQL 注入漏洞，或者 API 密钥直接硬编码在代码里？这种「看起来能用，上线就出事」的场景，正是 Project CodeGuard 要解决的问题。

一、项目起源与行业背景

Project CodeGuard 诞生于 2025 年 10 月，由 Cisco 团队发起，旨在为 AI 编程工具打造一套模型无关的安全规则体系。2026 年初，项目被正式捐赠给 CoSAI（Coalition for Secure AI）——一个由 OASIS Open 主导的 AI 安全联盟，获得了更广泛的行业认可和长期维护保障。

当前主流 AI 编程工具（如 Claude Code、GitHub Copilot、Cursor 等）在代码生成时往往缺乏系统性的安全约束，生成的代码可能包含 SQL 注入、XSS、硬编码密钥等常见漏洞。Project CodeGuard 的核心思路是：在 AI 生成代码之前，先给它一套安全规则，让它在生成阶段就知道什么不该做。

图1：AI 在安全规则指导下的代码生成效果（来源：Project CodeGuard 官方文档）

项目已积累 409 GitHub Stars，吸引了来自 Cisco、Google、OpenAI 等企业的贡献者，形成了覆盖 12+ 编程语言的全面安全规则库。

二、核心设计理念

2.1 规则即代码（Rules as Code）

CodeGuard 采用了「规则即代码」的理念：安全规则不是配置文件，而是 Markdown 文件——开发者可以像写代码一样维护、版本控制、审查和贡献规则。每条规则包含以下元数据：

• description：规则的文字描述，告诉 AI 应该怎么做
• languages：规则适用的编程语言（如 Python、JavaScript、Go）
• tags：规则分类标签（如 authentication、sql-injection、supply-chain）
• alwaysApply：是否对所有文件强制应用

这种设计的好处是：规则本身具备可读性，非安全专家也能理解和贡献规则。规则的评审流程与代码评审完全一致，通过 Pull Request 提交、社区 review 后合并。

2.2 模型无关（Model-Agnostic）

CodeGuard 的另一个核心理念是模型无关——同一套规则可以同时作用于多个 AI 编程工具。项目内置了 5 种主流 IDE 格式的转换器：

目标工具	输出路径	文件格式
Cursor	.cursor/rules/	.mdc
Windsurf	.windsurf/rules/	.mdc
GitHub Copilot	.github/instructions/	.instructions.md
Agent Skills（OpenAI Codex / Claude Code）	skills/software-security/rules/	.md
Antigravity	.agents/rules/	.md

这意味着安全团队只需要维护一套规则源文件（位于 sources/ 目录），运行 uv run convert-to-ide-formats 就能同时为所有工具生成适配的规则包，真正实现「一次编写，处处生效」。

三、规则库内容详解

3.1 核心规则（Core Rules）

项目包含 22 条核心规则，覆盖最常见的安全风险领域：

• 输入验证与注入防御（SQL、LDAP、OS 命令、模板注入）
• 身份认证与 MFA
• 授权与访问控制
• 硬编码凭证检测
• 供应链安全（依赖管理、SBOM、SLSA）
• 日志记录与隐私保护
• Kubernetes / 云原生安全
• MCP（Model Context Protocol）安全
• 加密算法与密钥管理

以硬编码凭证检测为例，规则明确禁止在代码中直接写入 API 密钥、密码、数据库凭证等敏感信息，要求统一使用环境变量或密钥管理服务（如 AWS Secrets Manager、HashiCorp Vault）。规则还提供了具体代码示例，展示正确的「从环境变量读取」写法以及错误的「硬编码」写法。

3.2 OWASP 规则集

除了核心规则外，项目还从 OWASP（Open Web Application Security Project）导入了 90+ 条规则，全面覆盖 OWASP Top 10 各类漏洞：

• SQL 注入预防（参数化查询、最小权限数据库账户）
• 跨站脚本 XSS（内容安全策略、CSP）
• 敏感数据暴露（传输加密、密钥管理）
• XML 外部实体（XXE）预防
• 访问控制失效（IDOR 预防）
• 安全配置错误（HTTP 头、Docker 安全）
• CSRF 防御

这些 OWASP 规则来自 OWASP 官方指南，规则内容经过社区充分评审，可信度高。对于企业用户来说，直接复用 OWASP 规则比自己编写更省力，也更符合行业标准。

图2：同一 AI 会话中，有安全规则（右侧）与无规则（左侧）的上下文窗口对比，展示了规则如何影响 AI 的代码生成行为（来源：Project CodeGuard 官方文档）

四、技术实现解析

4.1 规则转换引擎

项目的技术核心是 RuleConverter 类（位于 src/converter.py），它负责：

1. 解析 Markdown 规则文件，提取 YAML frontmatter 元数据和 Markdown 正文内容
2. 将编程语言映射到 glob 文件匹配模式（如 Python → *.py，JavaScript → *.js）
3. 为每种 IDE 格式生成对应文件，保留原始规则描述的同时添加格式特定的元数据

每种格式的实现都是 BaseFormat 的子类（位于 src/formats/），通过策略模式实现了格式的轻松扩展——添加新工具支持只需继承 BaseFormat 并实现 generate() 方法，无需修改核心转换逻辑。

4.2 版本管理与插件同步

CodeGuard 使用 uv 作为包管理器（uv.lock），Python 版本要求 >= 3.11。项目还支持通过 Claude Code 插件系统安装（.claude-plugin/plugin.json），实现与 Claude Code 的无缝集成——用户安装插件后，Claude Code 会自动加载所有安全规则，无需手动配置路径。

规则版本通过 pyproject.toml 统一管理，每次发布时使用 set_plugin_version() 和 set_marketplace_version() 自动同步到各插件元数据文件，确保工具端显示的版本号与规则内容一致。

4.3 持续验证机制

项目内置了两套验证流程：

• validate_unified_rules.py：验证所有 Markdown 规则文件的 frontmatter 格式是否合规
• validate_versions.py：确保各插件元数据中的版本号与 pyproject.toml 保持同步
• GitHub Actions CI：validate-rules.yml 在每次 PR 时自动运行验证，防止不合规规则进入主分支

这套机制保证了规则库的质量可控——即使社区贡献者众多，规则内容也不会出现格式混乱或版本不一致的问题。

五、安装与上手

5.1 安装方式

CodeGuard 支持多种安装路径，具体取决于使用场景：

1. 用户级别安装：将规则下载到 ~/.config/project-codeguard/，对该用户的所有项目生效
2. 项目级别安装：将规则放入特定项目目录，仅对该项目生效，适合团队统一安全要求
3. AI 工具插件安装：通过 Claude Code 的 .claude-plugin 插件系统安装，自动激活

基础安装命令只需两步：

uv sync
uv run convert-to-ide-formats

5.2 部署门槛评估

作为一个纯 Python CLI 工具，CodeGuard 的部署门槛极低：

• 无需 GPU：纯文本处理工具，不需要 CUDA
• 无需容器：Python >= 3.11 + uv 即可运行
• 无需服务器：规则在本地生成和加载，无网络依赖（除初始安装外）
• 磁盘占用 < 100MB：规则文件本身是轻量 Markdown

对于企业场景，建议通过 Git Submodule 或 CI/CD 钩子在项目初始化时自动拉取最新规则，确保团队所有成员始终使用最新版本。

六、项目现状与局限

尽管设计理念先进，Project CodeGuard 仍处于相对早期的阶段，存在以下不足：

1. 规则覆盖仍有空白：虽然 OWASP 规则库丰富，但对于新兴领域（如 LLM API 安全、RAG 系统安全）覆盖不足，规则更新速度可能跟不上 AI 编程工具的进化。

2. 实际效果依赖 AI 遵循度：规则只是提示词增强，并不能强制 AI 遵守。研究表明，AI 对复杂规则的遵循率明显低于简单指令，对于需要多步判断的安全规则，AI 可能选择性忽略。

3. 缺少规则冲突检测：当多条规则对同一代码行为有不同要求时，项目没有提供冲突检测机制，可能导致 AI 收到相互矛盾的指令。

从行业视角看，CodeGuard 代表了一种新兴趋势：将安全左移到 AI 编程阶段。传统安全流程中，安全审查通常在代码提交后进行（SAST/DAST 扫描），而 CodeGuard 的思路是让安全约束在 AI 生成代码时即刻生效，从源头减少漏洞。

项目已捐赠给 CoSAI 联盟，这意味着它将获得更长期的维护和更广泛的行业采纳基础。随着更多 AI 编码工具支持 Agent Skills 等开放标准，CodeGuard 的规则格式转换能力将成为连接安全规则库与 AI 工具的桥梁，其价值有望持续放大。

如果你正在使用 Claude Code、Cursor、Windsurf 等 AI 编程工具，不妨试试 Project CodeGuard——在 AI 帮你写代码之前，先给它上一堂安全课。