security-guidance

Security Guidance Hook

一个 PreToolUse 钩子，在 Claude Code 写入代码之前拦截 12 种常见安全反模式。

本技能是一个钩子，而不是斜杠命令。安装后，它会在每次 Edit、Write 或 MultiEdit 操作之前自动运行，一旦检测到已知危险模式，就会发出警告并阻止操作。

检测范围

该钩子会扫描以下两项内容：

• 正在编辑的文件路径：标记包含有风险 ${{ }} 表达式的 GitHub Actions 工作流文件
• 正在写入的内容：对 11 种反模式进行子字符串匹配

模式	类别	风险
GitHub Actions 工作流表达式	基于路径	通过不可信输入进行工作流命令注入
child_process.exec、exec(、execSync(	子字符串	Node.js 命令注入
new Function	子字符串	JS 代码注入
eval(	子字符串	JS 代码注入
dangerouslySetInnerHTML	子字符串	React XSS
document.write	子字符串	DOM XSS
.innerHTML =	子字符串	DOM XSS
pickle	子字符串	Python 反序列化 RCE
os.system、from os import system	子字符串	Python 命令注入
shell=True（subprocess）	子字符串	Python 命令注入
f-string SQL 或 .format SQL	子字符串	SQL 注入
yaml.load(、yaml.unsafe_load	子字符串	YAML 反序列化 RCE

工作原理

1. Claude Code 即将运行 Edit、Write 或 MultiEdit
2. PreToolUse 钩子触发，并通过标准输入以 JSON 形式传入工具输入，调用 security_reminder_hook.py
3. 钩子提取 file_path 和 content，并与模式表进行比对
4. 如果某个模式匹配，且该文件与规则的组合在本次会话中尚未显示过此警告：
   • 将警告输出到 stderr（Claude 会看到）
   • 退出码 2，阻止该工具调用
   • 将警告键保存到 ~/.claude/security_warnings_state_<session>.json
5. 如果某个模式匹配，但本次会话中已经显示过该警告：
   • 允许该工具调用（退出码 0），因为 Claude 已经看过一次警告
6. 如果没有任何模式匹配：
   • 允许该工具调用（退出码 0）

安装

该插件以 Claude Code 插件的形式发布，并通过 hooks.json 进行配置：

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

安装后无需进一步配置，钩子会自动运行。

配置

通过环境变量在单次会话中禁用：

ENABLE_SECURITY_REMINDER=0 claude
# Hook is bypassed for this session

请谨慎使用。当你在赶工期、想要发布一些自己清楚有问题的代码时，这个钩子最有用，而这也恰恰是最想禁用它的时候。

单文件覆盖模式

如果某个特定文件确实需要使用 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

钩子仍会在每次会话中首次编辑时发出警告。确认后，同一会话中的后续编辑将被允许（会话状态缓存）。

为什么模式基于子字符串而非 AST

权衡如下：基于 AST 的检测会更精确（不会对包含 "eval(" 的字符串字面量产生误报）。而基于子字符串的检测具有以下优点：

• 更快：在毫秒级完成，无需解析文件
• 跨语言：同一钩子适用于 JS/TS/Python/YAML 等
• 保守：误报容易忽略（只需按一次键）；漏报则很危险

对于 90% 以上的情况，子字符串检测已经足够。如果需要更严格的检测，可以在 CI 步骤中引入成熟的 SAST 工具（如 semgrep、CodeQL）。

状态文件

钩子将"已显示警告"的状态缓存在 ~/.claude/security_warnings_state_<session_id>.json 中。这些文件：

• 会在 30 天后自动清理（每次钩子调用有 10% 的概率触发）
• 以会话为单位存储（每个 Claude 会话各有一份）
• 包含一个 JSON 列表，列表项为 <file_path>-<rule_name> 形式的键

你可以随时安全地删除 ~/.claude/security_warnings_state_*.json 文件，钩子会在下次运行时重新生成它们。

调试日志

该钩子会将日志写入 ~/.claude/security-warnings-log.txt，用于调试钩子误触发问题：

tail -f ~/.claude/security-warnings-log.txt
# Shows JSON decode errors, state-file save failures, etc.

（上游版本写入 /tmp/security-warnings-log.txt，我们将其改到 ~/.claude/ 下，以便在重启后保留。）

来源与署名

本插件移植自 David Dworken 基于 MIT 许可证发布的实现，来源为 alirezarezvani/aeo-box。

原文保留： 原有的 9 条模式（GitHub Actions、child_process.exec、new Function、eval、dangerouslySetInnerHTML、document.write、innerHTML、pickle、os.system）均按原样保留，包括其确切的警告文本。

修改内容：

• 新增 3 条模式：subprocess shell=True、通过 f-string 或 .format 实现的 SQL 注入、yaml.unsafe_load
• 调试日志从 /tmp/security-warnings-log.txt 迁移至 ~/.claude/security-warnings-log.txt
• 重构为 claude-skills 插件，并将 attribution 块放在 .claude-plugin/authoring-notes.json 中（原位于 plugin.json；在 issue #954 显示 Claude Code 会拒绝包含扩展键的清单后，已迁移位置）

反模式

默认禁用钩子

这会违背设置钩子的初衷。如果将 ENABLE_SECURITY_REMINDER=0 设为默认值，你就会逐渐习惯忽略这道安全防线。仅应在针对已验证安全的特定操作中使用。

未经安全审查即修改模式列表

任何人都可以添加模式。删除模式则需要经过安全审查，因为每条模式都对应真实存在的 CVE 类别。

将会话状态视为不可变的安全策略

缓存可以避免重复提醒刷屏，但它仅在当前会话内有效。不要把"我之前已忽略过这条"当作长期策略，应改用按文件记录的方式（用注释说明使用理由）。

相关 Skills

• engineering-team/skills/red-team — 对抗性渗透测试
• engineering-team/skills/threat-detection — 威胁建模与检测设计
• engineering-team/skills/ai-security — AI 专项安全（提示词注入等）
• engineering/ship-gate — 上线前审计（8 个类别，约 89 项检查）
• engineering/skill-security-auditor — Skill 包安全扫描

触发短语

• "add security hook"
• "block unsafe code before write"
• "detect command injection"
• "prevent SQL injection patterns"
• "warn on eval / pickle / os.system"
• "GitHub Actions security hook"

---

版本： 2.7.3 来源： 移植自 alirezarezvani/aeo-box .claude/plugins/security-guidance/（原作者为 Anthropic 的 David Dworken，MIT 许可证） 许可证： MIT