AI 编程 工具

让 Claude Code 边写代码边查安全漏洞：security-guidance 插件详解

Anthropic 官方推出的 security-guidance 插件，能让 Claude Code 在写代码的同时审查自己产出的漏洞，并在同一个会话里修复。本文用中文梳理它的安装方式、三层检查机制、自定义规则、用量成本，以及它如何与 /security-review、Code Review 和 CI 扫描配合，构成纵深防御。

阅读时长: 9 分钟
共 4412字
作者: longlikun
#Claude Code #代码安全 #AI Agent #Anthropic #安全审查

用 AI 写代码越来越快，但有一个问题随之被放大：模型生成的代码可能引入安全漏洞——注入、不安全的反序列化、危险的 DOM 操作等等。这些问题如果一路漏到 Pull Request，最后只能靠人去逐行 review，成本很高。

Anthropic 官方给出的方案是一个叫 security-guidance 的插件。它的思路很直接：让 Claude 在写代码的同时审查自己改动的安全性，并在同一个会话里把发现的问题修掉，而不是等到 PR 阶段才暴露。

装好之后插件会自动运行，没有需要记住的命令，也不用手动触发。它是 Code Review（在 PR 阶段运行）的「会话内伙伴」：插件减少进入 PR 的问题数量，Code Review 兜住剩下的。

前置条件

  • Claude Code CLI 版本 2.1.144 或更高
  • 系统 PATH 上有 Python 3.8 或更高（插件会依次尝试 python3、python、py -3）
  • 工作目录是一个 git 仓库。「回合结束审查」和「提交审查」依赖 git diff，不在仓库里就会静默跳过；而「逐次编辑」的模式检查在任何地方都能跑

首次运行时，插件会在 ~/.claude/security/ 下创建一个虚拟环境，并把 Claude Agent SDK 装进去，这一步需要 pip 和网络。如果安装失败，提交审查会退回到「单次审查」而非「智能体审查」。在 Windows 上虚拟环境这一步会被跳过，因此只有在 claude-agent-sdk 已经可被导入时才会运行智能体提交审查，否则同样退回。

安装插件

在 Claude Code 会话里，从官方 Anthropic 插件市场安装：

/plugin install security-guidance@claude-plugins-official

安装时会让你选择作用域（scope）。选 user 作用域会把插件写入你的用户设置，这样这台机器上每个新开的本地会话都会加载它。如果 Claude Code 提示找不到市场，先运行下面这条再重试安装：

/plugin marketplace add anthropics/claude-plugins-official

然后在当前会话里激活它，/reload-plugins 会在不重启的情况下应用挂起的插件改动：

/reload-plugins

在云端会话和共享仓库中启用

user 作用域的插件不会带到 Claude Code on the web，因为那些会话跑在 Anthropic 的基础设施上，而不是你的机器。要在那里启用，或者想让所有克隆这个仓库的人都开启它，就在项目签入的设置里声明：

{
  "enabledPlugins": {
    "security-guidance@claude-plugins-official": true
  }
}

管理员可以在托管设置里设置 enabledPlugins，从而在整个组织范围内启用。

插件检查什么

插件会在三个不同的点位审查 Claude 的工作，每一层深度不同：

  • 每次文件编辑：对危险调用做一次快速的模式匹配，不调用模型
  • 每个回合结束：对这一回合所有改动做一次后台模型审查
  • Claude 每次提交或推送：做一次更深入的、会阅读上下文代码的智能体审查

每一层都可以通过添加自己的规则来扩展。内置检查不能单独移除，但你可以独立关闭每一层。

1. 每次文件编辑

当 Claude 写入文件时，插件会扫描新内容里已知的危险模式。这是一次纯字符串匹配，不调用模型，所以不产生用量成本。

示例模式类别：

  • 动态代码执行：eval(、new Function、os.system、child_process 的 exec
  • 不安全的反序列化：pickle
  • DOM 注入：dangerouslySetInnerHTML、.innerHTML =、document.write
  • 工作流文件：对 .github/workflows/ 下文件的编辑（可能授予仓库级权限）

检查在编辑落地后运行，并把警告追加到 Claude 下一步的上下文里。每个模式在每个文件每个会话里只触发一次，所以同一文件里的重复匹配不会刷屏。

你可以用 security-patterns.yaml 文件给这一层添加自定义模式。

2. 每个回合结束

一个「回合」就是 Claude 响应的一轮：你发消息，Claude 干活并回复，回合结束。每个回合结束后，插件会计算这一回合工作区里所有改动的 git diff——包括 Claude 编辑工具、Bash 命令和子智能体造成的改动——然后发给一个专注安全的、独立的 Claude 审查。审查在后台运行，所以不会拖慢 Claude 的回复。如果发现问题，Claude 会被重新提示，并作为后续步骤去处理。

这一层能抓到字符串匹配抓不到的问题，比如：

  • 授权绕过（Authorization bypass）
  • 不安全的直接对象引用（IDOR）
  • 注入
  • 服务端请求伪造（SSRF）
  • 弱加密

你会在会话里直接看到「发现」和 Claude 的「修复」。这层审查每回合最多覆盖 30 个改动文件，并且连续最多触发三次，之后把控制权交还给你。

3. Claude 每次提交或推送

当 Claude 通过它的 Bash 工具运行 git commit 或 git push 时，插件会在后台对这次改动做一次更深的智能体审查。这次审查会阅读周围的代码——包括调用方、净化逻辑（sanitizer）和相关文件——再判断一个发现是不是真问题。额外的上下文能在「孤立看危险、放到你代码库里其实安全」的模式上把误报压低。

这一层只对 Claude 通过 Bash 工具发起的提交和推送生效。你在自己 shell 里跑的提交（包括会话里 ! 这种 shell escape）不会被审查。提交和推送审查的上限是每滚动小时 20 次。如果提交审查的发现和回合结束审查已经报过的重复，Claude 不会被再次提示——所以一次干净的提交在这一层不会产生可见输出。

审查的独立性与边界

插件不会让写代码的那个 Claude 实例给自己打分。逐次编辑检查是确定性的字符串匹配，完全不涉及模型；回合结束审查和提交审查则作为独立的 Claude 调用运行，拥有全新的上下文和专注安全的提示词：审查方从 diff 出发，对原始方案没有任何「投入感」，只被要求去找问题。

需要注意：这些层都不会阻止写入或提交。发现会作为指令送到写代码的 Claude 那里，由它在对话中处理，而审查模型也可能漏掉问题。请把这个插件当作纵深防御中的一层，而不是完整的安全方案。

添加自己的规则

插件有两个扩展点：给模型审查用的 Markdown 指引文件，以及给逐次编辑字符串匹配用的 YAML/JSON 模式文件。两者都是追加式的——你可以加检查，但不能从这些文件里禁用内置检查。

给模型审查添加指引

在项目里创建 .claude/claude-security-guidance.md，用自然语言描述你的威胁模型和审查清单。模型审查会把它和内置漏洞清单一起作为额外上下文加载。

下面这个例子针对一个带角色限制的 admin 路由、且有客户数据日志策略的 Web 服务：

# 本仓库的安全指引

- 不要在 INFO 及以上级别记录 `customer_id` 或 `account_number`。
- 所有 `/admin` 下的路由必须在任何数据库读取前调用 `require_role("admin")`。
- token 比较用 `crypto.timingSafeEqual`，不要用 `===`。

这些规则是给审查方的指引，而非确定性护栏。插件会把违规作为发现交给 Claude 去修，但不会阻止写入，也不保证每条违规都被抓到。指引只能追加：一条「忽略某类漏洞」的规则并不会压制那类发现。如果需要硬性强制，请把插件和阻止编辑的 hook 或 CI 检查搭配使用。

添加自定义的逐次编辑模式

创建 .claude/security-patterns.yaml，给逐次编辑模式检查加上正则或子串规则。它们和内置模式一样作为确定性字符串匹配运行：

patterns:
  - rule_name: internal_api_key
    substrings: ["sk_live_", "AKIA"]
    reminder: "硬编码的 API key 前缀。请从密钥管理器加载凭据。"
  - rule_name: tenant_unfiltered_query
    regex: "\\.objects\\.all\\(\\)"
    paths: ["**/src/tenants/**"]
    reminder: "多租户代码必须按 org_id 过滤。"
字段 类型 说明
rule_name string 警告里显示的标识符
reminder string 追加到 Claude 上下文的警告文本，上限 1 KB
regex string 对编辑内容匹配的 Python 正则
substrings list 字面子串；和 regex 二选一
paths list 可选 glob 模式，规则只对匹配文件生效。glob 匹配完整路径，项目相对路径要加 **/ 前缀
exclude_paths list 可选 glob 模式，跳过匹配文件；匹配规则同 paths

插件也会读取 .claude/security-patterns.yml 和 .claude/security-patterns.json，schema 相同。JSON 在任何 Python 安装上都能用；YAML 形式需要能导入 PyYAML，而插件不会替你安装它。插件最多加载 50 条自定义规则，并会跳过那些看起来容易引发灾难性回溯的正则。

规则文件查找位置

插件在以下相同位置查找 claude-security-guidance.md 和 security-patterns.yaml，与插件是怎么启用的无关：

作用域 路径 说明
User ~/.claude/claude-security-guidance.md 对这台机器上每个项目生效
Project .claude/claude-security-guidance.md 随仓库签入
Project local .claude/claude-security-guidance.local.md 被 gitignore，用于个人覆盖

插件会加载所有存在的位置并拼接起来，指引文件合计上限 8 KB。管理员可以通过设备管理把 user 作用域的文件推送到 ~/.claude/，从而分发组织级规则。security-patterns.yaml 适用同样的路径。

用量成本

逐次编辑模式检查不调用模型，不产生成本。回合结束和提交审查则各自消耗额外的模型用量，和其他 Claude 请求一样计入你的用量。提交审查是智能体式的，每次提交可能跑好几个模型回合，上限是每滚动小时 20 次。大致预期：每个改动文件的回合一次审查调用，每次提交一次更深的审查，都受上述上限约束。

两种模型审查默认都用 Claude Opus 4.7。可以用 SECURITY_REVIEW_MODEL 给回合结束审查换模型，用 SG_AGENTIC_MODEL 给提交审查换模型。

该插件在所有套餐上都可用。

关闭或卸载

想关掉某一层、保留其余，设置对应的环境变量：

变量 效果
ENABLE_PATTERN_RULES=0 关闭逐次编辑模式检查
ENABLE_STOP_REVIEW=0 关闭回合结束 diff 审查
ENABLE_COMMIT_REVIEW=0 关闭提交和推送审查
ENABLE_CODE_SECURITY_REVIEW=0 一次性关闭所有模型审查
SECURITY_GUIDANCE_DISABLE=1 不卸载，直接整体禁用插件

在 user 作用域暂停插件：

/plugin disable security-guidance@claude-plugins-official

从 user 作用域移除：

/plugin uninstall security-guidance@claude-plugins-official

如果插件是通过项目的 .claude/settings.json 启用的，从 /plugin 禁用它会把一个覆盖写到你的 .claude/settings.local.json，而不是改签入的文件——这样它对你关闭，但不影响队友。如果是通过托管设置启用的，就只有管理员能禁用。

它如何与 Claude Code 集成

插件完全建立在 hooks 之上——也就是在 Claude 循环的特定点位运行你自己代码的机制。它注册了：

Hook 事件 用途
SessionStart 引导插件的 Python 环境
UserPromptSubmit 捕获回合结束审查所对比的工作区基线
PostToolUse（Edit、Write、NotebookEdit） 逐次编辑模式匹配
Stop 回合结束 diff 审查，后台运行
PostToolUse（Bash，过滤到 git commit 和 git push） 提交和推送审查，后台运行

如果你想构建自己的 hook，插件源码是一个「从 hook 里发起独立模型调用、再把结果喂回会话」的可用示例。

它在整个安全工具链里的位置

这个插件是纵深防御的一层。它最早抓问题——代码还在编辑器里时——但不是保证，也不替代后续检查。典型的工具栈：

阶段 工具 覆盖什么
会话内 security-guidance 插件 Claude 写的代码里的常见漏洞，同会话修复
按需 /security-review 你发起时，对当前分支做一次性安全扫描
PR 阶段 Code Review（Team 和 Enterprise 套餐） 带完整代码库上下文的多智能体正确性与安全审查
CI 阶段 你现有的静态分析和依赖扫描器 语言相关规则、供应链检查、插件不涉及的策略强制

每个后续阶段都兜住前面漏掉的。插件的价值在于减少进入后续阶段的量，而不是消除对它们的需要。

排错

插件把运行时诊断写到 ~/.claude/security/log.txt。如果审查没出现，先去那里看。

某一审查层静默跳过、对话里没消息，常见原因：

  • 目录不是 git 仓库：回合结束审查和提交审查需要 git 状态，仓库外会跳过
  • 会话没有 Anthropic 身份认证：模型审查跳过，只运行逐次编辑模式检查
  • 存在 security-patterns.yaml 但 PyYAML 不可导入：文件被忽略，改用 security-patterns.json

小结

security-guidance 把安全审查从「PR 之后的人工负担」前移到了「写代码的当下」。三层设计很有层次感：纯字符串匹配零成本兜底常见危险调用，回合结束的独立模型审查抓逻辑类漏洞，提交时的智能体审查再带上下文压低误报。配合 .claude/ 下的自定义规则，你还能把团队自己的威胁模型喂给它。

但要记住作者反复强调的一点：它不阻断、会漏报，只是纵深防御的一层。把它和 /security-review、Code Review、CI 扫描叠在一起用，才是它真正的用法。

本文译写自 Anthropic 官方文档 Catch security issues as Claude writes code。

关于

关注我获取更多资讯

月球基地博客公众号二维码，扫码关注获取更多 AI 与编程资讯
📢 公众号
月球基地博客作者个人微信二维码，扫码交流 AI 与编程话题
💬 个人号

本文链接地址：https://blog.eimoon.com/p/claude-code-security-guidance-plugin/

作者：eimoon.com

分享转载说明：本文由作者原创，转载请注明出处。

© 2023 - 2026 longlikun
使用 Hugo 构建
主题 Stack 由 Jimmy 设计