在 Claude 写代码时捕获安全问题¶

安装 security-guidance 插件，让 Claude 在工作时自动审查自己的代码变更中的漏洞，并在同一会话中修复。

该插件捕获注入、不安全反序列化、不安全 DOM API 等问题——在代码到达 PR 之前——减少下游人工安全审查的负担。

安装后，插件自动运行。无需调用，无需记住命令。

该插件是 Code Review 的会话内搭档——Code Review 在 PR 阶段运行。插件减少到达 PR 的问题量，Code Review 捕获漏过的。关于插件如何与按需审查和 CI 扫描分层配合，或如何扫描已有代码而非 Claude 正在编写的变更，参见与其他安全工具的配合。

前提条件¶

• Claude Code CLI v2.1.144 或更高版本
• Python 3.7 或更高版本在 PATH 中。agentic 提交审查需要 Python 3.10 或更高版本，当 Claude Code 使用第三方 provider（如 Amazon Bedrock 或 Google Cloud Agent Platform）时，所有模型审查也需要 3.10+。插件优先使用带版本号的解释器 python3.13 到 python3.10，然后回退到 python3、python、py -3
• 工作目录是 git 仓库（end-of-turn 和 commit 审查基于 git state，非仓库静默跳过；逐编辑模式匹配在任何地方工作）

首次运行时，插件会在 ~/.claude/security/ 下创建虚拟环境并安装 Claude Agent SDK，需要 pip 和网络访问。如果安装失败，或可用 Python 版本低于 3.10，在使用 Anthropic 一方认证时提交审查会回退到单次审查而非 agentic 审查；在第三方 provider（如 Amazon Bedrock 或 Google Cloud Agent Platform）上模型审查本身需要该 SDK，因此会跳过。当 Python 版本过低导致降级时，插件会显示一次性提示。

安装插件¶

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

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

/plugin 会打开交互面板，仅在终端 CLI 中可用。如果 Claude 回复 /plugin 在当前环境不可用，请用其他方式安装：

• Claude 桌面应用（本地或 SSH 会话）：打开插件浏览器，点击 prompt 旁的 + 按钮，然后 Plugins，再 Add plugin
• Claude Code on the web 或桌面云会话：在 .claude/settings.json 中声明插件，如在云会话中启用所示

终端安装时会提示选择 scope。选择 user scope 写入用户设置，使其在每个新本地会话加载。如果 Claude Code 报告 Marketplace "claude-plugins-official" not found，先用 /plugin marketplace add anthropics/claude-plugins-official 添加市场。如果报告在市场中找不到插件，说明本地副本过期：用 /plugin marketplace update claude-plugins-official 刷新，然后重试安装。

激活当前会话：

/reload-plugins

在云会话和共享仓库启用¶

用户作用域插件不会带入 Claude Code on the web，因为那些会话运行在 Anthropic 基础设施上而非你的机器。要在那里启用，或为克隆仓库的所有人启用，在项目的提交设置中声明：

// .claude/settings.json
{
  "enabledPlugins": {
    "security-guidance@claude-plugins-official": true
  }
}

管理员可通过管理设置中的 enabledPlugins 组织级启用。

三层检查¶

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

• 逐编辑模式匹配：对风险调用做快速模式匹配，无模型调用
• 每轮 Diff 审查：后台模型审查本轮所有变更
• 提交/推送审查：更深的 agentic 审查，读取周围代码

你可以通过添加自定义规则扩展每一层。内置检查不能单独移除，但你可以独立禁用每一层。

逐编辑模式匹配¶

Claude 写入文件时，插件扫描已知风险模式。无模型调用，零成本。

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

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

你可以通过 security-patterns.yaml 文件为此层添加自定义模式。

每轮 Diff 审查¶

一轮是 Claude 响应的一个回合。轮结束后，插件计算工作树中本轮所有变更的 git diff——包括 Claude 的编辑工具、Bash 命令和子 agent 产生的变更——发送给独立 Claude 做安全审查。后台运行不延迟回复。如果审查发现问题，Claude 会被重新提示并在后续处理。

能捕获模式匹配无法发现的问题：
- 授权绕过
- IDOR（不安全的直接对象引用）
- 注入
- SSRF
- 弱加密

你可以在会话中直接看到发现和 Claude 的修复。每轮最多覆盖 30 个变更文件，连续最多触发三次。

提交/推送审查¶

Claude 通过 Bash 工具运行 git commit 或 git push 时，插件在后台运行更深的 agentic 审查。此审查读取周围代码（调用者、清洁器、相关文件）判断发现是否为真，降低误报。额外上下文使得那些孤立看来危险、但在你代码库中安全的模式不会被误报。

此层仅在 Claude 通过 Bash 工具执行的提交和推送时触发。你自己在 shell 中运行的提交（包括会话中的 ! shell 转义）不会被审查。每滚动小时上限 20 次。如果提交审查的发现与每轮审查已报告的重复，不会重复提示，因此干净的提交不会产生此层的可见输出。

审查独立性与局限¶

插件不会让编写代码的同一个 Claude 实例来给自己打分。逐编辑检查是确定性字符串匹配，无模型参与。每轮和提交审查作为独立 Claude 调用运行，有新鲜上下文和安全聚焦的 prompt：审查者从 diff 出发，对原始方案没有投入，仅被指示寻找问题。

没有任何层阻止写入或提交。发现作为指令传达给写代码的 Claude，Claude 在对话中处理它们，审查模型也可能遗漏问题。将插件视为纵深防御的一层，而非完整安全方案。参见与其他安全工具的配合。

添加自定义规则¶

插件有两个扩展点：用于模型审查的 Markdown 指导文件，和用于逐编辑字符串匹配的 YAML 或 JSON 模式文件。两者都是增量式的——你可以添加检查，但无法从这些文件中禁用内置检查。

模型审查的指导文件¶

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

以下示例适用于一个有角色门控管理员路由和客户数据日志策略的 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 `===`.

这些规则是对审查者的指导，不是确定性护栏。插件将违规作为发现呈现给 Claude 修复，但不会阻止写入，也不保证每次违规都被捕获。指导是纯增量的：声称忽略某类漏洞的规则不会抑制相关发现。如需硬性执行，可配合使用阻止编辑的 hook 或 CI 检查。

自定义逐编辑模式¶

创建 .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，与插件的启用方式无关：

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

使用成本¶

逐编辑模式匹配不调用模型，零成本。每轮审查和提交审查产生额外模型用量，像其他 Claude 请求一样计入你的 usage。提交审查是 agentic 的，每次提交可能花费多轮模型调用，上限每滚动小时 20 次。大致预期：每个有文件变更的轮一次审查调用，每次提交一次更深审查，均受上述上限约束。

两种模型审查默认使用 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 v2.1.203 或更高版本。如果插件通过管理设置启用，只有管理员可以禁用。

插件如何与 Claude Code 集成¶

插件完全基于 hooks 构建——即在 Claude 循环特定时间点运行你自己代码的机制。它注册：

如果你构建自己的 hooks，插件源码是一个从 hook 运行独立模型调用并将结果反馈到会话的工作示例。

与其他安全工具的配合¶

插件是纵深防御方案中的一层。它在最早期——代码还在编辑器中时——捕获问题，但不保证万无一失，也不替代后续检查。典型技术栈：

每个后续阶段捕获前面阶段遗漏的。插件的价值是减少到达它们的体量，而非消除对它们的需求。

如需扫描已有代码（而非 Claude 正在编写的变更），可以在会话中让 Claude 审查特定文件或目录的漏洞，或使用 Claude Security 插件对整个仓库做更深的多 agent 扫描；/security-review 仅覆盖当前分支的变更。无论哪种方式，审查读取的是你 checkout 中的源代码，而非运行中的站点或已部署的服务。

故障排查¶

插件将运行时诊断写入 ~/.claude/security/log.txt。审查没出现时先查看这里。

常见跳过原因：
- 目录不是 git 仓库：end-of-turn 和 commit 审查需要 git state，非仓库时跳过
- 会话无 Anthropic 认证且未配置第三方 provider：模型审查跳过，仅逐编辑模式匹配运行
- security-patterns.yaml 存在但 PyYAML 不可导入：文件被忽略，用 security-patterns.json 替代

相关资源¶

• Code Review — 设置 PR 时的多 agent 审查
• Hooks guide — 在相同生命周期点构建自己的检查
• Discover plugins — 浏览其他官方插件