如何在 Claude Code 安装 security-guidance 钩子拦截不安全代码写法并在需要时临时禁用-酒店常州论坛

如何在 Claude Code 安装 security-guidance 钩子拦截不安全代码写法并在需要时临时禁用

【免费下载链接】claude-skills380 Claude Code skills & agent skills & plugins (30+ Agents, 70+ custom commands, 380+ skills, customizable references, scripts)for Claude Code, Codex, Gemini CLI, Cursor, and 8 more coding agents — engineering, marketing, product, compliance, C-level advisory, research, business operations, commercial & finance, and your daily productivity skills.项目地址: https://gitcode.com/GitHub_Trending/cla/claude-skills

在 Claude Code 会话中让 Agent 修改代码时，eval(、os.system、pickle、f-string 拼接 SQL 这类写法可能在编辑落盘前就构成注入或反序列化风险。claude-skills 仓库里的security-guidance插件提供一个 PreToolUse 钩子：在Edit、Write、MultiEdit三个工具实际执行之前扫描目标文件路径与写入内容，命中已知反模式时向 stderr 输出警告并以退出码 2 阻断这次工具调用。安装后无需额外配置即可自动生效；当你确实在执行已验证安全的操作（比如写一个故意不安全的沙箱 REPL 或做安全研究）时，可以用环境变量ENABLE_SECURITY_REMINDER=0在单个会话内临时绕过钩子。本文覆盖：安装插件、验证拦截是否生效、临时禁用、以及状态文件与调试日志的位置。

安装前需要满足的条件

使用 Claude Code 的插件体系（/plugin命令可用），钩子通过插件自带的hooks.json接线，安装后自动运行；
系统上有python3。钩子实际执行的命令是python3 ${CLAUDE_PLUGIN_ROOT}/hooks/security_reminder_hook.py（见 hooks.json），脚本本身只依赖标准库、无第三方包（SKILL.md 注明 "Stdlib only — no dependencies"）。

安装 security-guidance 插件

在 Claude Code 中依次执行（命令原文来自 SKILL.md 的 Installation 一节）：

# In Claude Code: /plugin marketplace add alirezarezvani/claude-skills /plugin install security-guidance@claude-code-skills

第一行添加插件市场，第二行安装security-guidance这个独立插件。文档明确说明：安装完成后"no further configuration needed — the hook runs automatically"。

生成的文档页 docs/skills/engineering/security-guidance.md 顶部给出的安装入口是claude /plugin install engineering-advanced-skills，即通过engineering-advanced-skills领域包一并装入；两条路径都出现在仓库文档中，按需选择其一即可。

钩子如何拦截：触发时机与退出码

钩子的接线配置在 hooks.json：PreToolUse事件的 matcher 为Edit|Write|MultiEdit，只有这三个文件编辑工具会触发钩子。

工作流（引自 SKILL.md 的 How It Works）：

Claude Code 即将执行Edit/Write/MultiEdit；
PreToolUse 钩子触发，把工具输入以 JSON 形式通过 stdin 传给security_reminder_hook.py；
钩子提取file_path与写入内容，对照 12 条规则做子串/路径匹配；
命中且本会话内该"文件+规则"尚未警告过：向 stderr 打印警告（Claude 可见）、退出码 2 阻断工具调用，并把警告键写入~/.claude/security_warnings_state_<session>.json；
命中但本会话已警告过：放行（退出码 0）；
未命中：放行（退出码 0）。

PreToolUse 钩子的三个退出码语义（见 pretooluse_hook_canon.md）：0放行；1钩子自身出错，放行并记日志；2阻断工具调用。

拦截范围覆盖 12 条规则：基于路径的一条（.github/workflows/下的.yml/.yaml文件，提示工作流命令注入风险）加 11 条子串规则，包括child_process.exec、new Function、eval(、dangerouslySetInnerHTML、document.write、.innerHTML =、pickle、os.system、shell=True、f-string/.format拼 SQL、yaml.unsafe_load。完整规则与警告文案在 security_reminder_hook.py 的SECURITY_PATTERNS中可直接核对。

注意会话级缓存机制：同一会话内，同一文件命中同一规则只阻断一次，后续编辑放行（这是设计意图，防止重复警告消耗 token、也避免用户学会无视警告）。不同规则在同一文件上各自独立触发。

验证钩子是否生效

文档给出的可核对依据有两处：

拦截行为本身：让会话执行一次包含已知模式的写入（例如在某个测试文件中写入含eval(的内容，或编辑.github/workflows/下的 workflow 文件）。按文档行为，第一次命中时这次Edit/Write会被阻断，Claude 会看到 stderr 上的安全警告。若警告已被本会话显示过（状态文件里已有该键），同一文件同一规则的后续编辑会直接放行——这是预期行为，不是钩子失效。
状态文件：警告键会以<file_path>-<rule_name>的形式保存为 JSON 列表，位置是~/.claude/security_warnings_state_<session_id>.json，每个会话一个文件。可用通配符查看当前用户下所有会话的状态文件：

ls ~/.claude/security_warnings_state_*.json

<session_id>由 Claude 会话生成，对应你当前会话的那个文件里应能看到刚才命中的键。状态文件的作用范围是单个会话；钩子每次运行有 10% 概率清理超过 30 天的旧状态文件，因此文件会周期性减少。

调试日志：钩子的解码失败、状态文件保存失败等运行问题写入~/.claude/security-warnings-log.txt，排查误触发时用文档给出的方式跟踪：

tail -f ~/.claude/security-warnings-log.txt

需要放行时的临时禁用

文档给出的临时禁用方式是会话级环境变量（SKILL.md Configuration 一节）：

ENABLE_SECURITY_REMINDER=0 claude # Hook is bypassed for this session

脚本在入口处检查该变量，值为0时直接sys.exit(0)，即本次启动的整个会话内所有Edit/Write/MultiEdit都绕过钩子。文档对该用法的约束是明确的：

只在"已验证安全、否则会命中模式"的具体操作时使用，操作完成后立即恢复默认启用；
不要把export ENABLE_SECURITY_REMINDER=0写进 shell rc 文件——文档将其列为"训练自己无视警告"的反模式，默认开启才是安全默认值。

如果只是某个文件合理地需要eval()或pickle（例如沙箱 REPL、故意不安全的解析器），文档推荐的文件级做法是在该文件中用注释说明原因，例如：

# SAFETY: pickle is the required serialization format for this internal tool. # This file does NOT accept untrusted input. See SECURITY.md for boundary analysis. import pickle

按文档说明，这种注释不会让钩子静默：该文件本会话第一次编辑仍会警告一次，确认后的后续编辑由会话缓存放行。文档同时提醒：会话缓存不是长期安全策略，"本会话放过一次"不能替代文件内的说明注释。

状态文件维护

~/.claude/security_warnings_state_*.json可以安全删除（文档原文："You can safely delete ... at any time"），钩子会在下次运行时重新生成。若怀疑某个会话的缓存状态异常导致不再警告，删除对应会话的状态文件即可重置该会话的警告状态。

已知限制

子串匹配而非 AST 解析：模式在字符串字面量或注释中出现也会命中。pretooluse_hook_canon.md 给出了估计误报率，其中pickle约 30%（任何对该模块的引用都会命中），eval(约 5%，SQL f-string 约 15%，GitHub Actions 路径检查约 0%。高误报规则依赖会话缓存来避免反复打扰；若需要更严格的检测，文档建议把 semgrep、CodeQL 等 SAST 工具作为 CI 步骤叠加使用，而不是把复杂度推进 PreToolUse 钩子。
删除规则需要评审：文档规定任何人都可以添加模式，但删除模式需要安全评审，因为每条规则对应真实的 CVE 类别。
版本号不一致：仓库内 plugin.json 声明版本2.9.0，而 SKILL.md 页脚标注Version: 2.7.3，两处文档未对齐，以安装后实际生效的行为为准。
钩子设计为每工具调用约 10ms 的纯本地子串扫描，不做网络请求、不派生子进程（文档的 Hook Performance Discipline 一节要求保持该约束），因此它定位为写入前的安全网，不承担完整安全审计职能。

完成安装后，可以用一次故意包含eval(的写入做冒烟检查：预期看到警告且该次工具调用被阻断，会话状态文件中出现对应的<file_path>-ruleName键；确认无误后，日常会话保持默认启用，仅在已验证安全的操作中临时使用ENABLE_SECURITY_REMINDER=0。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析