Security guidance 插件：边写边查安全问题

安全指南（security guidance）插件让 Claude 在工作时审查自己代码改动里的常见漏洞，并在同一会话里修复发现的问题。它在代码到达 PR 之前就捕获注入、不安全反序列化、不安全 DOM API 之类的问题，减少下游人工评审者要承担的安全审查。安装后它自动运行，没有要调用的东西，也没有单独的命令要记。它是在 PR 上运行的代码评审的会话内搭档：这个插件减少到达 PR 的问题，代码评审捕获漏过的。

前提

• PATH 上有 Python 3.7 或更高版本。agentic 提交审查需要 Python 3.10 或更高版本，Claude Code 使用 Bedrock 或 Agent Platform 等第三方提供商时所有基于模型的审查也需要。插件优先选带版本号的解释器 python3.13 到 python3.10，然后回退到 python3、python 和 py -3
• 你工作的目录是 git 仓库。回合结束审查和提交审查基于 git 状态做 diff，在仓库之外会静默跳过；按编辑的模式检查在任何地方都能工作

首次运行时插件在 ~/.claude/security/ 下创建虚拟环境并把 Claude Agent SDK 装进去，这需要 pip 和网络。如果安装失败，或可用的 Python 低于 3.10，第一方认证下的提交审查会回退为一次性审查而不是 agentic 审查。

安装

在终端 Claude Code 会话里从官方 Anthropic 市场安装：

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

/plugin 在终端 CLI 里打开交互面板。如果 Claude 回答说 /plugin 在此环境不可用，换一种方式：Claude 桌面应用的本地或 SSH 会话，点提示框旁的 +，再点 Plugins、Add plugin；VS Code 扩展从 Manage plugins 对话框安装；云端会话不会从你的用户设置或仓库的 .claude/settings.json 加载插件，组织通过托管设置分发的插件见「为组织管理插件」。终端安装会询问范围，选用户范围会把插件写入你的用户设置，使它在你这台机器上启动的每个新本地会话里加载。安装失败时：Marketplace "claude-plugins-official" not found 就用 /plugin marketplace add anthropics/claude-plugins-official 添加市场再重试；插件在市场里找不到则检查插件名。如果安装摘要报告 Run /reload-plugins to activate.，见「不重启应用插件变更」。

在本地会话里为团队启用

要在队友于该仓库启动的本地会话里打开插件，在项目已提交的设置里声明：

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

管理员可在托管设置里设置 enabledPlugins 在组织范围启用。

插件检查什么

插件在三个点审查 Claude 的工作，每处深度不同：每次文件编辑时做快速模式匹配（不调用模型）；每个回合结束时对该回合改动的一切做后台模型审查；Claude 每次提交或推送时做阅读周边代码的更深入的 agentic 审查。每一层都可以添加你自己的规则，内置检查不能单个移除，但可以独立禁用每一层。

每次文件编辑时

Claude 写入文件时，插件扫描新内容里已知的风险模式。这是不调用模型的模式匹配，所以不增加用量成本。模式类别示例：动态代码执行（eval(、new Function、os.system、child_process.exec）、不安全反序列化（pickle）、DOM 注入（dangerouslySetInnerHTML、.innerHTML =、document.write）、workflow 文件（.github/workflows/ 下的编辑，可能授予仓库级权限）。检查在编辑落地后运行，并把警告附加到 Claude 下一步的上下文里；每个模式在每个文件每个会话里只触发一次，同一文件里的重复匹配不会刷屏。可以用 security-patterns.yaml 文件添加你自己的模式。

每个回合结束时

一个回合是 Claude 的一轮回应：你发消息、Claude 工作并回复、回合结束。每个回合之后，插件对该回合里工作树发生的所有变化（包括 Claude 的编辑工具、Bash 命令和子智能体的改动）计算 git diff，发给一个专注于安全的独立 Claude 审查，在后台运行。它能捕获字符串匹配抓不到的问题，如授权绕过、不安全的直接对象引用、注入、服务端请求伪造、弱加密。发现和 Claude 的处理都直接显示在你的会话里。每个回合最多覆盖 30 个改动文件，连续触发最多三次就把控制权交还给你。

Claude 每次提交或推送时

当 Claude 通过 Bash 工具运行 git commit 或 git push 时，插件在后台对改动运行更深入的 agentic 审查：它阅读周边代码（包括调用方、净化函数和相关文件）来判断某个发现是否真实再报告，额外的上下文让孤立看起来危险、实际上已被处理的模式保持低误报。这一层只对 Claude 通过 Bash 工具做的提交和推送触发；你在自己的 shell 里运行的提交（包括会话里用 ! shell 转义）不被审查。提交和推送审查每滚动一小时上限 20 次；如果提交审查的发现与回合结束审查已经报告的重复，不会再次提示 Claude。

审查的独立性与局限

插件不让写代码的同一个 Claude 实例给自己打分。按编辑的检查是不涉及模型的确定性字符串匹配；回合结束和提交审查作为带新上下文和安全导向提示的独立 Claude 调用运行：审查者从 diff 开始，对原来的做法没有投入。所有层都不阻止写入或提交：发现作为指令到达写代码的 Claude，由 Claude 在对话里处理，审查模型也可能漏掉问题。把插件当作纵深防御的一层，而不是完整的安全方案。

添加你自己的规则

两个扩展点：给基于模型的审查用的 Markdown 指南文件，和给按编辑字符串匹配用的 YAML 或 JSON 模式文件；二者都是增量的：可以添加检查，但不能从这些文件禁用内置检查。

给基于模型的审查加指南

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

# 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 `===`.

这些规则是给审查者的指引，不是确定性的护栏：插件把违规作为发现交给 Claude 修复，但不阻止写入，也不保证每个违规都被捕获。指南只增不减：写「忽略某类漏洞」的规则不会抑制这些发现。需要硬性强制，把插件与阻止相应操作的 hook 搭配。

添加自定义的按编辑模式

创建 .claude/security-patterns.yaml，给按编辑的模式检查添加正则或子串规则，它们作为确定性字符串匹配与内置模式一起运行：

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."

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

规则文件的查找位置

插件在同样的位置查找 claude-security-guidance.md 和 security-patterns.yaml，与插件如何被启用无关：用户范围 ~/.claude/claude-security-guidance.md（对你机器上每个项目生效）、项目范围 .claude/claude-security-guidance.md（随仓库提交）、项目本地 .claude/claude-security-guidance.local.md（个人覆盖，加进 .gitignore）。插件加载所有存在的位置并拼接，指南文件合计上限 8 KB。管理员可以通过设备管理把用户范围的文件推送到 ~/.claude/ 来分发组织范围的规则，security-patterns.yaml 适用相同的路径。

用量成本

按编辑的模式检查不调用模型，不增加成本。回合结束和提交审查各自消耗额外的模型用量，与其他 Claude 请求一样计入你的用量；提交审查是 agentic 的，每次提交可能需要几个模型回合。大致预期：每个改了文件的回合一次审查调用，每次提交一次更深入的审查，二者都受上面的上限约束。两种基于模型的审查默认用 Claude Opus 4.7；设置 SECURITY_REVIEW_MODEL 为回合结束审查选别的模型，设置 SG_AGENTIC_MODEL 为提交审查选别的模型。插件适用于所有套餐。

禁用或卸载

用对应的环境变量关闭单个层而保留其余：

在你的用户范围暂停插件：/plugin disable security-guidance@claude-plugins-official；从用户范围移除：/plugin uninstall security-guidance@claude-plugins-official。如果插件是通过项目的 .claude/settings.json 启用的，从 /plugin 卸载会在你的 .claude/settings.local.json 里写入一个覆盖，而不是编辑已提交的文件，所以插件对你保持关闭，队友不受影响；同一个对话框也提供通过从共享的 .claude/settings.json 里移除来为所有人卸载。

插件如何与 Claude Code 集成

插件完全基于 hooks 构建：

如果你自己写 hook，插件的源码是在 hook 里运行独立模型调用并把结果反馈给会话的可用示例。

与其他安全工具的关系

插件是纵深防御的一层，最早（代码还在编辑器里时）捕获问题，但不是保证，也不取代后面的检查。典型的栈：会话中 = 本插件（Claude 所写代码里的常见漏洞，同会话修复）；按需单遍 = /security-review；按需深度扫描 = Claude Security 插件；PR 时 = 代码评审（Team 和 Enterprise）；CI 中 = 你现有的静态分析和依赖扫描器（语言特定规则、供应链检查和策略强制，插件不尝试做的）。要在你已有的代码里找安全问题（而不是 Claude 正在写的改动），让 Claude 在会话里审查特定文件或目录的漏洞，或用 Claude Security 插件对整个仓库做更深的多智能体扫描；/security-review 只覆盖当前分支上的改动。

排障

插件把运行时诊断写到 ~/.claude/security/log.txt，审查没出现时先查这里。审查层在对话里没有消息就跳过的常见原因：目录不是 git 仓库（回合结束和提交审查需要 git 状态，在仓库之外会跳过）；会话没有 Anthropic 认证也没配置第三方提供商（基于模型的审查跳过，只有按编辑的模式检查运行）；存在 security-patterns.yaml 但 PyYAML 无法导入（文件被忽略，改用 security-patterns.json）。