Claude Code 深度学习手册

主题

写代码时捕获安全问题 ​

安装 security-guidance 插件，让 Claude 在写代码时自审漏洞并当场修复。

是什么 ​

security-guidance 插件让 Claude 在工作过程中自动审查自己改动的代码，发现注入、不安全反序列化、不安全 DOM API 等常见漏洞，并在同一会话内修复，从而在代码进入 pull request 之前拦截问题，减少下游人工安全审查的负担。

它是 Code Review（在 PR 阶段运行）的会话内伴侣：本插件减少进入 PR 的问题量，Code Review 捕获已进入 PR 的问题。安装后插件自动运行，无需调用、也没有单独命令。

怎么工作 ​

  • 在三个时点以不同深度审查 Claude 的工作：每次文件编辑、每个 turn 结束、Claude 每次 commit 或 push
  • On each file edit：对新内容做已知风险模式匹配，纯字符串匹配、不调用模型、不产生用量成本；每个模式每文件每会话只告警一次
  • At the end of each turn：对该 turn 工作树的 git diff 发起独立的安全聚焦 Claude 审查，后台运行不阻塞回复，发现问题则把 findings 回灌给 Claude 跟进修复
  • On each commit or push：当 Claude 通过 Bash 工具运行 git commit/git push 时，后台运行更深入的 agentic 审查，会读取调用方、sanitizer、相关文件等周边代码以降低误报
  • 审查独立性：以全新 context 和安全聚焦 prompt 作为独立 Claude 调用运行，不让写代码的同一 Claude 给自己打分
  • 所有层都不阻塞写入或提交；findings 作为指令传给写代码的 Claude，审查模型也可能漏判，应视为纵深防御的一层
  • 基于 hooks 实现，注册 SessionStart、UserPromptSubmit、PostToolUse(Edit/Write/NotebookEdit)、Stop、PostToolUse(Bash 过滤 git commit/push) 等事件

怎么配置 / 用法 ​

安装（需 Claude Code CLI 2.1.144+ 与 Python 3.8+）：

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

安装时选择 user scope；若提示找不到 marketplace，先运行 /plugin marketplace add anthropics/claude-plugins-official。然后在当前会话激活：

text
/reload-plugins

云端会话或共享仓库需在 checked-in 设置中声明：

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

自定义：在 .claude/claude-security-guidance.md 写模型审查的威胁模型/检查清单（合并上限 8 KB）；在 .claude/security-patterns.yaml（或 .yml/.json）加 per-edit 字符串/regex 规则（最多 50 条）。两者仅为追加，不能停用内置检查。

什么时候用 ​

  • 希望 Claude 在编写代码时就自动捕获注入、不安全反序列化、不安全 DOM API 等常见漏洞
  • 想在代码进入 pull request 之前减少下游人工安全审查的负担
  • 需要按项目或组织定制威胁模型与审查规则（自定义 guidance 文件或 per-edit 模式）
  • 作为纵深防御的最早一层，配合 /security-review、Code Review 和 CI 静态扫描使用

限制 / 坑 ​

  • 所有层都不阻塞写入或提交，findings 仅作为指令传给 Claude，审查模型可能漏判，不是完整的安全方案
  • end-of-turn 与 commit 审查依赖 git 状态，非 git 仓库目录会静默跳过（per-edit 模式匹配仍可运行）
  • commit/push 审查只对 Claude 通过 Bash 工具发起的提交生效；用户自己 shell 或 ! shell escape 的提交不被审查
  • 自定义 guidance/patterns 只能追加规则，无法从这些文件停用内置检查
  • 会话无 Anthropic 鉴权时模型审查跳过，仅运行 per-edit 模式匹配

硬事实速查（12 条） ​

  • 前置要求：Claude Code CLI 2.1.144 或更高、PATH 上有 Python 3.8+、工作目录为 git 仓库
  • 首次运行在 ~/.claude/security/ 下创建虚拟环境并安装 Claude Agent SDK；失败时 commit 审查回退为单次 single-shot 审查；Windows 跳过 venv 步骤
  • end-of-turn 审查每 turn 最多覆盖 30 个改动文件，连续最多触发 3 次后交还给用户
  • commit 与 push 审查每滚动小时上限 20 次
  • 两个模型审查默认使用 Claude Opus 4.7；用 SECURITY_REVIEW_MODEL 指定 end-of-turn 审查模型，用 SG_AGENTIC_MODEL 指定 commit 审查模型
  • per-edit 模式检查不调用模型、零成本；模型审查计入正常 Claude 用量；插件在所有 plan 可用
  • 内置 per-edit 模式示例：eval(、new Function、os.system、child_process.exec、pickle、dangerouslySetInnerHTML、.innerHTML =、document.write，以及 .github/workflows/ 下的改动
  • security-patterns 字段：rule_name、reminder（上限 1 KB）、regex、substrings、paths、exclude_paths；最多 50 条；YAML 需可导入 PyYAML，否则改用 .json
  • 禁用各层环境变量：ENABLE_PATTERN_RULES=0、ENABLE_STOP_REVIEW=0、ENABLE_COMMIT_REVIEW=0、ENABLE_CODE_SECURITY_REVIEW=0、SECURITY_GUIDANCE_DISABLE=1
  • 暂停/卸载：/plugin disable 或 /plugin uninstall security-guidance@claude-plugins-official
  • 规则文件查找位置：用户级 ~/.claude/、项目级 .claude/、项目本地 .claude/*.local.md（gitignored）；存在的位置全部加载并拼接
  • 运行诊断日志写入 ~/.claude/security/log.txt

官方出处：https://code.claude.com/docs/en/security-guidance