Claude Code 安全指导插件：让 AI 在写代码时自动修复安全漏洞
“
本文核心问题：在使用 AI 编程助手编写代码时，如何让 AI 自己发现并修复引入的安全漏洞，而不需要等到代码审查或上线后才被发现？
”
每一个使用 AI 辅助编程的开发者都遇到过这样的场景：AI 快速生成了一段看似完美的代码，但其中却隐藏着 eval() 执行用户输入、innerHTML 注入恶意脚本，或者未做权限校验的接口。这些漏洞在代码审查时可能被忽略，直到生产环境爆发事故才被发现。
Anthropic 为 Claude Code 推出的安全指导插件，正是为了解决这一问题。它让 Claude 在编写代码的过程中，自动审查自己产出的代码，发现并修复常见的安全问题，然后再将代码提交到仓库。这不是一个需要手动触发的命令，而是一个在后台默默运行的“安全搭档”。
本文将基于该插件的官方文档，深入解析它的工作原理、安装方法、自定义规则、成本控制以及与现有安全工具链的配合方式。无论你是独立开发者，还是大型团队的工程负责人，都能从中找到让 AI 编程更安全的实用方法。
安装与启用：三步让安全审查融入你的工作流
核心问题：我该如何快速安装这个安全插件，并让它在我每次使用 Claude Code 时自动生效？
前置要求
在安装之前，请确保你的环境满足以下条件（这些条件来自插件本身的依赖，缺一不可）：
| 条件 | 说明 |
|---|---|
| Claude Code CLI | 版本 2.1.144 或更高 |
| Python | 3.8 或更高版本，且位于 PATH 中（插件会依次尝试 python3、python、py -3） |
| Git 仓库 | 你的工作目录必须是一个 Git 仓库（否则部分审查功能会静默跳过） |
| 网络访问 | 首次运行需要从网络下载 claude-agent-sdk 并创建虚拟环境 |
“
反思：很多开发者会忽略 Python 和 Git 的依赖，导致插件“看似安装了却不工作”。我个人的经验是，先在一个干净的测试仓库中运行一次
/reload-plugins，观察控制台是否有环境初始化的日志，这样能最快确认插件是否正常加载。”
安装步骤
在 Claude Code 会话中，执行以下命令从官方市场安装：
/plugin install security-guidance@claude-plugins-official
安装过程中会询问 scope（作用范围）：
-
User scope：将插件写入你的用户设置，之后在本机启动的任何新 Claude Code 会话都会自动加载。 -
Project scope：仅对当前项目生效。
如果系统提示找不到 marketplace，需要先添加官方市场：
/plugin marketplace add anthropics/claude-plugins-official
安装完成后，激活当前会话中的插件：
/reload-plugins
在云端会话和团队仓库中启用
核心问题：如果我在 Claude Code on the Web（云端）上工作，或者希望团队所有成员都默认开启这个插件，该怎么做？
用户级别的插件设置不会同步到云端会话（因为云端运行在 Anthropic 的基础设施上）。要让插件在云端或整个仓库中生效，你需要将配置提交到项目的 .claude/settings.json 文件中：
{
"enabledPlugins": {
"security-guidance@claude-plugins-official": true
}
}
将此文件提交到 Git 仓库后，任何克隆该仓库并使用 Claude Code 的开发者都会自动启用该插件。对于企业管理员，还可以通过托管设置进行组织范围内的统一启用。
三层防御机制：从模式匹配到深度代码审查
核心问题：这个插件具体检查哪些内容？它是在什么时候、以什么方式发现安全问题的？
插件不会在单一时刻做一次“大扫除”，而是在 Claude 编码生命周期的三个关键节点进行不同深度的检查。这种分层设计既保证了性能（浅层检查无 AI 调用），又确保了深度（深层检查会阅读上下文）。
第一层：每次文件编辑后的模式匹配（零成本，无 AI 调用）
当 Claude 使用 Edit、Write 或 NotebookEdit 工具修改文件后，插件会立即扫描新写入的内容，匹配预设的危险模式。这一层不调用任何 AI 模型，因此不会产生任何使用成本，延迟几乎为零。
典型的匹配模式包括：
-
动态代码执行： eval(、new Function、os.system、child_process.exec -
不安全的反序列化： pickle -
DOM 注入： dangerouslySetInnerHTML、.innerHTML =、document.write -
CI/CD 工作流文件： .github/workflows/目录下的任何修改（因为这些文件可能赋予代码仓库过高权限）
“
场景示例：假设 Claude 正在帮你写一个 Node.js 脚本，它生成了
const result = eval(userInput)。在文件保存的瞬间，插件就会检测到eval(这个子串，并将警告附加到 Claude 的上下文中。Claude 在下一步会看到：“检测到危险模式：eval 调用，请改用更安全的方式”，然后它可能主动将代码改为JSON.parse或函数映射。”
每个警告在同一会话、同一文件、同一模式上只触发一次，避免重复警告淹没对话历史。
第二层：每轮对话结束时的 Diff 审查（后台模型调用）
核心问题：如果模式匹配无法发现逻辑漏洞（比如权限绕过），插件还能做什么？
一轮对话（Turn）是指你发送一条消息，Claude 执行工具调用并给出最终回复的过程。当这一轮结束时，插件会计算工作目录中所有文件的 Git diff（包括 Claude 通过文件编辑工具、Bash 命令、子代理做出的所有更改），然后将这个 diff 发送给一个独立的、专门负责安全的 Claude 模型进行审查。
这个审查在后台运行，不会延迟 Claude 对当前消息的回复。如果审查发现问题，Claude 会被重新提示并主动修复——你会在对话中直接看到“安全审查发现 X 问题，正在修复……”的过程。
这一层能捕获模式匹配无法发现的漏洞：
-
授权绕过（Authorization bypass） -
不安全的直接对象引用（IDOR） -
SQL / NoSQL / 命令注入（更复杂的变种） -
服务端请求伪造（SSRF） -
弱加密算法（如使用 MD5 或 ECB 模式）
技术限制：
-
每次审查最多覆盖 30 个已更改的文件 -
同一轮对话中最多连续触发 3 次修复迭代，之后会将控制权交还给你
“
场景示例：Claude 为你生成了一个 REST API 端点：
/admin/users/:id。它正确地在代码开头调用了requireRole('admin')，但在后续的一个数据库查询中，它意外地写成了db.users.find({ id: req.params.id })而没有附加orgId过滤。模式匹配无法发现这个逻辑问题，但独立的模型审查会读取req.params.id的来源，结合路由的语义，判断是否存在越权风险，然后要求 Claude 添加组织 ID 过滤条件。”
第三层：Commit / Push 时的深度代理审查（读取上下文）
核心问题：如果代码已经被提交到本地 Git 仓库，插件还能再做什么？
当 Claude 通过 Bash 工具执行 git commit 或 git push 时，插件会触发一个更深度的代理审查。这个审查不仅仅是看 diff，而是会主动读取周围的代码：调用方、清理函数（sanitizers）、相关文件，以判断一个看似危险的模式在当前的代码库上下文中是否真正构成威胁。
为什么需要这一层？
有些代码片段孤立看起来是危险的，但在你的项目中却可能是安全的。例如，一个 eval 调用如果只处理硬编码的数学表达式，或者一个 innerHTML 赋值之前经过了严格的 DOMPurify 清理，那么它可能是可接受的。深度代理审查通过阅读更多上下文，能够大幅降低误报。
重要限制：
-
只审查 Claude 通过 Bash 工具发起的 commit / push。你在自己的终端（或通过 !shell 转义）执行的 commit 不会被审查。 -
每小时最多审查 20 次（滚动计数）。 -
如果 commit 审查发现的问题与第二层（端末审查）已经报告过的问题重复，Claude 不会再次被提示，因此一个干净 commit 不会产生任何可见输出。
“
反思：这种分层设计体现了一个重要的安全原则——不信任单一判断来源。第一层是确定性规则，第二层是无上下文的模型审查，第三层是有上下文的模型审查。每一层都试图弥补上一层的不足，同时控制成本。实际使用中，大多数常见漏洞会在第二层被捕获，第三层更多是用于处理复杂的、与代码库特定逻辑相关的问题。
”
定制你自己的安全规则：适配项目的特殊需求
核心问题：插件内置的检查规则不能满足我的项目需求，我能添加自己的规则吗？应该怎么做？
插件提供了两个扩展点：一个是给模型审查团队阅读的 Markdown 指引文件，另一个是给模式匹配层使用的 YAML/JSON 模式文件。两者都是增量添加的——你不能删除内置规则，但可以增加自己的规则。
添加模型审查指引（.claude/claude-security-guidance.md）
创建一个 Markdown 文件，用自然语言描述你的项目特有的威胁模型和审查清单。这个文件会被加载到第二层（端末审查）和第三层（commit 审查）的模型上下文中。
示例（适用于一个多租户 Web 服务）：
# Security guidance for this repo
- Do not log `customer_id` or `account_number` at INFO level or above.
- All routes under `/admin` must call `require_role("admin")` before any database read.
- Use `crypto.timingSafeEqual` for token comparison instead of `===`.
查找位置（按优先级合并，总计上限 8 KB）：
| 作用域 | 路径 | 说明 |
|---|---|---|
| 用户级 | ~/.claude/claude-security-guidance.md |
适用于本机所有项目 |
| 项目级 | .claude/claude-security-guidance.md |
提交到仓库，团队共享 |
| 项目本地 | .claude/claude-security-guidance.local.md |
被 .gitignore 忽略，个人覆盖 |
“
注意：这些指引是建议，不是硬性阻断。插件会将违反指引的情况作为“发现”提交给 Claude 修复，但不会直接阻止写入。如果需要强制阻断，应配合 hook 机制或 CI 检查。
”
添加自定义模式匹配规则（security-patterns.yaml）
创建 YAML 或 JSON 文件，添加你希望正则或子串匹配的规则。这些规则会在第一层（每次文件编辑后）同步执行。
示例：
patterns:
- rule_name: internal_api_key
substrings: ["sk_live_", "AKIA"]
reminder: "Hardcoded API key prefix. Load credentials from the secret manager."
- rule_name: tenant_unfiltered_query
regex: "\\.objects\\.all\\(\\)"
paths: ["**/src/tenants/**"]
reminder: "Multi-tenant code must filter by org_id."
字段说明：
| 字段 | 类型 | 描述 |
|---|---|---|
rule_name |
string | 警告中显示的名称 |
reminder |
string | 附加到 Claude 上下文的警告文本（上限 1 KB） |
regex |
string | Python 正则表达式，匹配编辑后的内容 |
substrings |
list | 文字子串列表（与 regex 二选一） |
paths |
list | 可选，仅对匹配这些 glob 模式的文件生效（建议以 **/ 开头） |
exclude_paths |
list | 可选，排除匹配这些 glob 模式的文件 |
插件会加载最多 50 条自定义规则，并跳过可能导致灾难性回溯的正则表达式。
文件格式：.claude/security-patterns.yaml、.claude/security-patterns.yml 或 .claude/security-patterns.json 均可。JSON 格式无需额外依赖，YAML 需要 PyYAML（插件不会自动安装，建议使用 JSON 以避免依赖问题）。
“
场景示例：你的项目规范禁止在代码中硬编码任何以
AKIA开头的 AWS 访问密钥。内置规则可能没有覆盖这个自定义前缀。通过添加上述规则，每当 Claude 写入包含AKIA的字符串时（即使它只是测试代码），插件都会提醒“请从密钥管理器加载凭据”。然后 Claude 可能会建议改用环境变量或 AWS Secrets Manager。”
成本、性能与集成：不影响效率的安全防线
核心问题：启用这个插件会额外消耗多少 Claude API 额度？会影响我的开发体验吗？
成本构成
| 检查层 | 是否有模型调用 | 成本影响 |
|---|---|---|
| 每文件编辑模式匹配 | 否 | 零成本 |
| 每轮结束 Diff 审查 | 是 | 每次审查按正常模型调用计费 |
| 每 commit / push 深度审查 | 是（代理式，可能多轮） | 每次审查按多轮模型调用计费 |
默认模型：两个模型支持的审查都使用 Claude Opus 4.7。你可以通过环境变量更改：
-
SECURITY_REVIEW_MODEL：控制端末审查的模型 -
SG_AGENTIC_MODEL：控制 commit 审查的模型
使用量估算：粗略情况下，每轮修改文件的对话会触发一次端末审查，每个 commit 会触发一次深度审查。上限为每小时 20 次 commit 审查。对于正常的开发节奏，成本的增加是有限的，尤其考虑到它可能避免一次生产事故。
禁用特定层次（不卸载插件）
如果某些场景下你想暂时关闭某一层，可以设置相应的环境变量：
| 变量 | 效果 |
|---|---|
ENABLE_PATTERN_RULES=0 |
禁用第一层（模式匹配） |
ENABLE_STOP_REVIEW=0 |
禁用第二层（端末审查） |
ENABLE_COMMIT_REVIEW=0 |
禁用第三层（commit/push 审查） |
ENABLE_CODE_SECURITY_REVIEW=0 |
一次性禁用所有模型支持的审查（保留模式匹配） |
SECURITY_GUIDANCE_DISABLE=1 |
完全禁用插件（不卸载） |
与其他安全工具的分层配合
核心问题：这个插件能完全替代我现有的 SAST、DAST 或人工代码审查吗？
不能。 它是最早的一道防线，但不是唯一的防线。官方文档提供了一个典型的分层防御栈：
| 阶段 | 工具 | 覆盖范围 |
|---|---|---|
| 编写时（会话内） | 安全指导插件 | 捕获 Claude 产出的常见漏洞，在同一会话中修复 |
| 按需 | /security-review 命令 |
对当前分支进行一次性的安全扫描 |
| PR 时 | Code Review（Team/Enterprise 计划） | 多代理的正确性与安全审查，拥有完整代码库上下文 |
| CI 中 | 现有的静态分析、依赖扫描器 | 语言特定的规则、供应链检查、策略强制执行 |
“
反思：我见过一些团队试图只用这一个插件就放弃所有其他安全措施，结果上线后仍然出现了业务逻辑漏洞。记住：插件减少的是“低级错误”和“常见漏洞”到达 PR 的流量，而不是消除所有漏洞的可能性。一个成熟的工程团队应该把它看作“守门员的第一反应”，而不是整条防线。
”
故障排除：插件不工作怎么办？
核心问题：我按照步骤安装了插件，但似乎没有看到任何审查输出，如何排查？
插件会将运行时诊断信息写入 ~/.claude/security/log.txt。这是第一排查入口。
常见静默跳过原因（会话中无任何消息）
| 原因 | 说明 |
|---|---|
| 目录不是 Git 仓库 | 端末审查和 commit 审查需要 Git 状态，非仓库会静默跳过 |
| 会话未通过 Anthropic 认证 | 模型支持的审查会跳过，只有模式匹配层运行 |
security-patterns.yaml 存在但 PyYAML 不可导入 |
该文件被忽略。改用 security-patterns.json 解决 |
| 自定义正则表达式导致灾难性回溯 | 插件会跳过该正则，检查日志确认 |
如何确认插件已加载？
在 Claude Code 会话中输入：
/plugin list
应该能看到 security-guidance@claude-plugins-official 出现在已启用的插件列表中。
卸载或临时禁用
-
临时禁用（用户级）： /plugin disable security-guidance@claude-plugins-official -
完全卸载： /plugin uninstall security-guidance@claude-plugins-official -
项目级启用时的个人禁用：插件会将你的禁用偏好写入 .claude/settings.local.json，不影响队友
如果插件是通过组织托管设置启用的，只有管理员可以禁用。
一页速览与操作清单
快速落地清单
-
[ ] 确认 Claude Code CLI ≥ 2.1.144，Python 3.8+ 在 PATH 中 -
[ ] 在项目根目录执行 /plugin install security-guidance@claude-plugins-official -
[ ] 执行 /reload-plugins激活 -
[ ] （可选）添加 .claude/claude-security-guidance.md撰写团队特定审查规则 -
[ ] （可选）添加 .claude/security-patterns.json扩展模式匹配 -
[ ] （团队共享）将 .claude/settings.json中的enabledPlugins配置提交到仓库 -
[ ] 正常使用 Claude Code，观察对话中是否出现“安全审查发现…”的修复过程 -
[ ] 遇到问题时查看 ~/.claude/security/log.txt
关键指标速查
| 特性 | 值 |
|---|---|
| 每编辑检查成本 | 零 |
| 端末审查默认模型 | Claude Opus 4.7 |
| 端末审查最大文件数 | 30 |
| 端末审查连续触发上限 | 3 次 |
| Commit 审查上限 | 20 次 / 小时 |
| 自定义规则数量上限 | 50 |
| 指引文件大小上限 | 8 KB |
| 警告文本大小上限 | 1 KB |
常见问答（FAQ）
Q1：这个插件会审查我手工编写的代码吗？
插件审查的是 Claude 通过文件编辑工具、Bash 命令和子代理所做的更改。如果你手工修改了文件，但 Claude 并没有在那一轮对话中主动写入，那么该更改不会触发审查。不过，如果你在对话中要求 Claude “审查当前所有未提交的更改”，它可能会手动调用 /security-review 命令。
Q2：插件扫描出的问题，Claude 会自动修复吗？
是的。对于端末审查和 commit 审查发现的问题，Claude 会收到重新提示，并尝试在当前会话中修复。修复过程是可见的，你会看到 Claude 说“安全审查发现 X 问题，正在修复……”然后执行编辑。但并不是 100% 保证所有问题都能被自动修复——有些问题可能需要你介入确认。
Q3：我在 Windows 上使用 Claude Code，插件能正常工作吗？
支持，但有差异：Windows 上虚拟环境步骤被跳过，因此代理式 commit 审查只在 claude-agent-sdk 已经可导入的情况下运行，否则会回退到单次审查模式。模式匹配和端末审查不受影响。
Q4：插件会读取我未提交的本地更改作为上下文吗？
对于第三层（commit 审查），它会主动读取周围的代码文件，包括未提交的更改。但这些读取行为发生在 Claude Code 的安全边界内，不会上传到外部（除了发送给 Anthropic API 用于模型推理，这是正常使用）。审查完成后，上下文不会保留。
Q5：我可以让插件忽略某些文件或目录吗？
可以通过自定义模式规则中的 exclude_paths 字段排除特定路径。如果要完全让某目录不参与任何审查，最直接的方法是将其添加到 .gitignore 或确保它不在 Git 工作树中（因为审查基于 Git diff）。
Q6：如果我不小心重复安装了多个版本，会发生什么？
插件系统通常只会加载最新启用的一个实例。你可以通过 /plugin list 查看当前加载的版本。建议先卸载旧版本再安装新版。
Q7：插件是否支持除了 JavaScript/Python 之外的语言？
模式匹配层对语言无感知——它只是扫描文本中的子串或正则。模型审查层则能够理解任何 Claude 模型支持的语言（包括 Java、Go、Rust、C# 等），因为它阅读的是代码语义而非仅仅词法。
Q8：安全审查的发现会写入日志或留存吗？
审查过程本身会记录在 ~/.claude/security/log.txt 中，供故障排除使用。但具体的漏洞细节不会自动提交到任何外部系统。如果团队需要审计，建议将 Claude Code 会话记录保存下来。
总结
让 AI 编写的代码变得安全，不能依赖“运气”或事后的人工复查。Claude Code 安全指导插件通过嵌入开发会话的三层检查机制，在不打断流畅编码体验的前提下，大幅降低了常见漏洞进入代码库的概率。
它的价值不在于完美无缺，而在于早期和自动化。一个漏洞在 AI 刚写完时被修复，成本是零；等到 PR 审查才发现，成本是 10 倍；等到生产环境被利用，成本是 1000 倍。
对于任何严肃使用 AI 编程助手的团队，安装并配置这个插件，应该成为启动新项目的默认步骤之一。
