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

安装 security-guidance 插件，让 Claude 在编写代码时审查自身代码变更中的漏洞，并在同一会话中修复发现的问题。

security-guidance 插件让 Claude 在工作过程中审查自身代码变更中的常见漏洞，并在同一会话中修复发现的问题。该插件可以在代码到达 Pull Request 之前捕获注入、不安全的反序列化和不安全的 DOM API 等问题，减少后续由人工审查员承担的安全审查工作量。

安装后，插件会自动运行。无需调用任何命令，也无需记住单独的指令。

该插件是 Code Review 的会话内配套工具，后者在 Pull Request 上运行。此插件减少到达 PR 的问题数量，Code Review 则捕获剩余问题。关于该插件如何与按需审查和 CI 扫描协同工作，请参阅 如何与其他安全工具配合。

前提条件

• Claude Code CLI 2.1.144 或更高版本
• PATH 上有 Python 3.8 或更高版本。插件会按顺序尝试 python3、python 和 py -3
• 工作目录是一个 git 仓库。回合结束审查和提交审查会与 git 状态进行 diff 比较，在仓库外会静默跳过。每次编辑的模式检查在任何地方都有效

首次运行时，插件会在 ~/.claude/security/ 下创建虚拟环境并安装 Claude Agent SDK，这需要 pip 和网络访问。如果安装失败，提交审查会回退到单次审查而非 agentic 审查。在 Windows 上，虚拟环境步骤会被跳过，因此 agentic 提交审查仅在 claude-agent-sdk 已可导入时运行，否则同样回退。

安装插件

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

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

安装时会提示选择作用域。选择用户作用域（user scope）可将插件写入用户设置，使其在你在此机器上启动的每个新本地会话中加载。如果 Claude Code 报告找不到市场，请先运行 /plugin marketplace add anthropics/claude-plugins-official，然后重试安装。

接着在当前会话中通过 /reload-plugins 激活它，该命令可在不重启的情况下应用待处理的插件变更：

/reload-plugins

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

用户作用域的插件不会带入 Claude Code Web 版，因为这些会话在 Anthropic 基础设施上运行，而非你的机器。要在那里启用插件，或为克隆仓库的每个人开启，请在项目已签入的设置中声明：

{
  "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
• 工作流文件：.github/workflows/ 下的编辑，可能授予仓库级权限

检查在编辑生效后运行，并将警告附加到 Claude 的上下文中供下一步使用。每个警告在每个会话中每个模式每个文件只触发一次，因此同一文件中的重复匹配不会淹没对话。

你可以通过 security-patterns.yaml 文件 添加自己的模式 到此层次。

每个回合结束时

一个回合（turn）是 Claude 响应的一轮：你发送消息，Claude 工作并回复，回合结束。每个回合结束后，插件会计算工作树在该回合中所有更改的 git diff，包括来自 Claude 编辑工具、Bash 命令和子代理的更改，并将其发送给专注于安全的独立 Claude 审查。审查在后台运行，因此不会延迟 Claude 的回复。如果审查发现问题，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，用 plain language 描述你的威胁模型和审查清单。模型支持审查会将其作为额外上下文加载，与内置漏洞清单一起使用。

以下示例适用于具有角色管控 admin 路由和客户数据日志策略的 Web 服务：

# 本仓库的安全指导

- 不要在 INFO 级别或更高级别记录 `customer_id` 或 `account_number`。
- `/admin` 下的所有路由必须在任何数据库读取之前调用 `require_role("admin")`。
- 使用 `crypto.timingSafeEqual` 进行令牌比较，而不是 `===`。

这些规则是审查员的指导，而非确定性的护栏。插件将违规作为发现呈现给 Claude 修复，但不会阻止写入或保证捕获每个违规。指导仅是附加的：一条说要忽略某类漏洞的规则不会抑制这些发现。对于硬强制执行，请将插件与 阻止编辑的 hook 或 CI 检查配对使用。

添加自定义每次编辑模式

创建 .claude/security-patterns.yaml 以向 每次编辑模式检查 添加 regex 或子字符串规则。这些与内置模式一起作为确定性字符串匹配运行：

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 条自定义规则，并跳过看起来容易产生灾难性回溯的 regex。

规则文件查找位置

插件会在以下位置查找 claude-security-guidance.md 和 security-patterns.yaml，与插件的启用方式无关：

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

使用成本

每次编辑模式检查 不进行模型调用，不产生成本。回合结束 和 提交 审查各消耗额外的模型使用量，计入你的 使用，与任何其他 Claude 请求一样。提交审查是 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 构建，hooks 是在 Claude 循环中特定点运行你自己代码的机制。它注册：

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

如何与其他安全工具配合

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

每个后续阶段捕获前面阶段遗漏的内容。插件的价值在于减少到达它们的问题数量，而非消除对它们的需求。

故障排查

插件将运行时诊断写入 ~/.claude/security/log.txt。如果审查未出现，请先检查那里。

审查层跳过且会话中未显示消息的常见原因：

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

相关资源

深入了解本页涉及的各个部分：

• Code Review：设置 PR 时的多 agent 审查
• 使用 hooks 自动化操作：在相同生命周期点构建你自己的检查
• 发现和安装插件：浏览其他官方插件