Back to Details

security-guidance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Security Guidance Hook

安全指导钩子

A PreToolUse hook that blocks 12 common security anti-patterns before Claude Code writes them.
This skill is a hook, not a slash command. Once installed, it runs automatically before every 
Edit
, 
Write
, or 
MultiEdit
operation and warns + blocks if it detects a known dangerous pattern.
一款PreToolUse钩子，可在Claude Code写入代码前阻止12种常见安全反模式。
该技能是一个钩子，而非斜杠命令。安装完成后，它会在每次
Edit
、
Write
或
MultiEdit
操作前自动运行，若检测到已知危险模式则发出警告并阻止操作。

What It Catches

检测范围

The hook scans both:
  • The file path being edited — flags GitHub Actions workflow files with risky 
    ${{ }}
    patterns
  • The content being written — substring matches against 11 anti-patterns
PatternCategoryRisk
GitHub Actions workflow expressionsPath-basedWorkflow command injection via untrusted inputs
child_process.exec
, 
exec(
, 
execSync(
SubstringNode.js command injection
new Function
SubstringJS code injection
eval(
SubstringJS code injection
dangerouslySetInnerHTML
SubstringReact XSS
document.write
SubstringDOM XSS
.innerHTML =
SubstringDOM XSS
pickle
SubstringPython deserialization RCE
os.system
, 
from os import system
SubstringPython command injection
shell=True
(subprocess)		SubstringPython command injection
f-string SQL or 
.format
SQL		SubstringSQL injection
yaml.load(
, 
yaml.unsafe_load
SubstringYAML deserialization RCE
钩子会扫描以下两部分内容：
  • 待编辑的文件路径——标记带有危险
    ${{ }}
    模式的GitHub Actions工作流文件
  • 待写入的内容——匹配11种反模式的子字符串
模式类别风险
GitHub Actions workflow expressions基于路径通过不可信输入进行工作流命令注入
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）

How It Works

工作原理

  1. Claude Code is about to run 
    Edit
    , 
    Write
    , or 
    MultiEdit
  2. PreToolUse hook fires → invokes 
    security_reminder_hook.py
    with the tool input as JSON on stdin
  3. The hook extracts file_path + content + checks against the pattern table
  4. If a pattern matches AND this warning hasn't been shown for this file+rule in this session:
    • Print the warning to stderr (Claude sees it)
    • Exit code 2 → blocks the tool call
    • Save the warning key to 
      ~/.claude/security_warnings_state_<session>.json
  5. If a pattern matches BUT the warning was already shown this session:
    • Allow the tool call (exit code 0) — Claude already saw the warning once
  6. If no pattern matches:
    • Allow the tool call (exit code 0)
  1. Claude Code即将执行
    Edit
    、
    Write
    或
    MultiEdit
    操作
  2. PreToolUse钩子触发→通过标准输入以JSON形式传入工具输入，调用
    security_reminder_hook.py
  3. 钩子提取file_path + 内容，并与模式表进行匹配检查
  4. 若模式匹配，且本次会话中尚未针对该文件+规则发出过警告：
    • 将警告打印至标准错误输出（Claude可看到）
    • 退出码为2→阻止工具调用
    • 将警告键保存至
      ~/.claude/security_warnings_state_<session>.json
  5. 若模式匹配，但本次会话中已发出过该警告：
    • 允许工具调用（退出码为0）——Claude已看过一次警告
  6. 若未匹配到任何模式：
    • 允许工具调用（退出码为0）

Installation

安装

This plugin ships as a Claude Code plugin with 
hooks.json
wiring:
bash
undefined
该插件作为Claude Code插件发布，带有
hooks.json
配置：
bash
undefined

In Claude Code:

在Claude Code中执行：

/plugin marketplace add alirezarezvani/claude-skills /plugin install security-guidance@claude-code-skills

Once installed, no further configuration needed — the hook runs automatically.
/plugin marketplace add alirezarezvani/claude-skills /plugin install security-guidance@claude-code-skills

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

Configuration

配置

Disable per-session via environment variable:
bash
ENABLE_SECURITY_REMINDER=0 claude
可通过环境变量在会话中禁用钩子：
bash
ENABLE_SECURITY_REMINDER=0 claude

Hook is bypassed for this session

本次会话中钩子将被绕过


Use sparingly — the hook is most useful exactly when you're tempted to disable it (because you're under deadline pressure to ship something you know is sketchy).

请谨慎使用——当你因截止日期压力想要交付明知存在风险的代码时，正是该钩子发挥最大作用的时候。

Per-File Override Pattern

单文件覆盖模式

If a specific file legitimately needs 
eval()
or 
pickle
(e.g., a sandboxed REPL, a deliberately unsafe parser for a fuzzer), document it in the file with a comment:
python
undefined
若特定文件确实需要使用
eval()
或
pickle
（例如沙箱化REPL、用于模糊测试的故意不安全解析器），请在文件中添加注释进行说明：
python
undefined

SAFETY: pickle is the required serialization format for this internal tool.

安全说明：pickle是此内部工具所需的序列化格式。

This file does NOT accept untrusted input. See SECURITY.md for boundary analysis.

本文件不接受不可信输入。边界分析请参考SECURITY.md。

import pickle

The hook will still warn on first edit per session. After acknowledging, subsequent edits in the same session are allowed (session-state caching).
import pickle

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

Why The Patterns Are Substring-Based (Not AST-Based)

为何采用基于子字符串的模式检测（而非基于AST）

Trade-off: AST-based detection would be more precise (no false positives on string literals containing "eval("). Substring-based is:
  • Faster — runs in ms, doesn't parse the file
  • Cross-language — same hook works for JS/TS/Python/YAML/etc.
  • Conservative — false positives are easy to dismiss (one keystroke); false negatives are dangerous
For 90%+ of cases, substring detection is sufficient. If you need stricter detection, layer in a proper SAST tool (semgrep, CodeQL) as a CI step.
权衡取舍：基于AST的检测更精确（不会对包含"eval("的字符串字面量产生误报），而基于子字符串的检测：
  • 速度更快——毫秒级运行，无需解析文件
  • 跨语言——同一钩子适用于JS/TS/Python/YAML等多种语言
  • 保守性——误报易于忽略（只需一次确认）；漏报则十分危险
对于90%以上的场景，子字符串检测已足够。若需要更严格的检测，可在CI步骤中集成专业的SAST工具（如semgrep、CodeQL）。

State Files

状态文件

The hook caches "warning shown" state in 
~/.claude/security_warnings_state_<session_id>.json
. These files:
  • Are auto-cleaned after 30 days (10% chance per hook invocation)
  • Are session-scoped (each Claude session gets its own)
  • Contain a JSON list of 
    <file_path>-<rule_name>
    keys
You can safely delete 
~/.claude/security_warnings_state_*.json
files at any time — the hook regenerates them on next run.
钩子会将“已发出警告”的状态缓存至
~/.claude/security_warnings_state_<session_id>.json
文件中。这些文件：
  • 30天后自动清理（每次钩子调用时有10%的清理概率）
  • 会话作用域（每个Claude会话拥有独立的状态文件）
  • 包含
    <file_path>-<rule_name>
    键的JSON列表
你可随时安全删除
~/.claude/security_warnings_state_*.json
文件——钩子会在下次运行时重新生成。

Debug Log

调试日志

The hook writes to 
~/.claude/security-warnings-log.txt
for debugging hook misfires:
bash
tail -f ~/.claude/security-warnings-log.txt
钩子会将调试信息写入
~/.claude/security-warnings-log.txt
，用于排查钩子误触发问题：
bash
tail -f ~/.claude/security-warnings-log.txt

Shows JSON decode errors, state-file save failures, etc.

显示JSON解码错误、状态文件保存失败等信息


(Upstream version wrote to `/tmp/security-warnings-log.txt` — we moved it to `~/.claude/` for persistence across reboots.)

（上游版本写入`/tmp/security-warnings-log.txt`——我们将其移至`~/.claude/`以实现跨重启持久化。）

Source + Attribution

源码与归属

This plugin is ported from David Dworken's MIT-licensed implementation in 
alirezarezvani/aeo-box
.
Verbatim: the original 9 patterns (GitHub Actions, child_process.exec, new Function, eval, dangerouslySetInnerHTML, document.write, innerHTML, pickle, os.system) are preserved with their exact warning text.
Modifications:
  • Added 3 patterns: 
    subprocess shell=True
    , SQL injection via f-string or 
    .format
    , 
    yaml.unsafe_load
  • Debug log moved from 
    /tmp/security-warnings-log.txt
    → 
    ~/.claude/security-warnings-log.txt
  • Restructured as a claude-skills plugin with 
    attribution
    block in 
    plugin.json
本插件移植自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插件，在
    plugin.json
    中添加
    attribution
    块

Anti-Patterns

反模式

Disabling the hook by default

默认禁用钩子

Defeats the purpose. If 
ENABLE_SECURITY_REMINDER=0
becomes your default, you've trained yourself to ignore the safety net. Use it only for specific verified-safe operations.
这违背了钩子的设计初衷。若
ENABLE_SECURITY_REMINDER=0
成为你的默认设置，你会逐渐习惯忽略安全保障。仅在执行特定经验证的安全操作时使用该设置。

Modifying the pattern list without security review

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

Anyone can add a pattern. Removing one requires a security review — patterns exist because they map to real CVE classes.
任何人都可添加模式，但移除模式需经过安全审查——这些模式的存在是因为它们对应真实的CVE类别。

Treating session-state as immutable security policy

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

The cache prevents nag-spam but is per-session. Don't rely on "I dismissed this once" as long-term policy — use the per-file documentation pattern instead (comment justifying the use).
缓存用于避免重复警告，但仅针对当前会话。不要将“我已忽略过一次”作为长期策略——请使用单文件文档模式（添加注释说明使用理由）。

Related Skills

相关技能

  • engineering-team/skills/red-team
    — adversarial pen-testing
  • engineering-team/skills/threat-detection
    — threat modeling + detection design
  • engineering-team/skills/ai-security
    — AI-specific security (prompt injection, etc.)
  • engineering/ship-gate
    — pre-production audit (8-category, ~89 checks)
  • engineering/skill-security-auditor
    — security scan for skill packages
  • 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
    ——技能包安全扫描

Trigger Phrases

触发短语

  • "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"
Version: 2.7.3 Source: Ported from 
alirezarezvani/aeo-box
 
.claude/plugins/security-guidance/
(originally by David Dworken at Anthropic, MIT) License: MIT
  • "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