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

Pattern	Category	Risk
GitHub Actions workflow expressions	Path-based	Workflow command injection via untrusted inputs
`child_process.exec` , `exec(` , `execSync(`	Substring	Node.js command injection
`new Function`	Substring	JS code injection
`eval(`	Substring	JS code injection
`dangerouslySetInnerHTML`	Substring	React XSS
`document.write`	Substring	DOM XSS
`.innerHTML =`	Substring	DOM XSS
`pickle`	Substring	Python deserialization RCE
`os.system` , `from os import system`	Substring	Python command injection
`shell=True` (subprocess)	Substring	Python command injection
f-string SQL or `.format` SQL	Substring	SQL injection
`yaml.load(` , `yaml.unsafe_load`	Substring	YAML 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

工作原理

Claude Code is about to run
```
Edit
```
,
```
Write
```
, or
```
MultiEdit
```
PreToolUse hook fires → invokes
```
security_reminder_hook.py
```
with the tool input as JSON on stdin
The hook extracts file_path + content + checks against the pattern table
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
```
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
If no pattern matches:
- Allow the tool call (exit code 0)

Claude Code即将执行
```
Edit
```
、
```
Write
```
或
```
MultiEdit
```
操作
PreToolUse钩子触发→通过标准输入以JSON形式传入工具输入，调用
```
security_reminder_hook.py
```
钩子提取file_path + 内容，并与模式表进行匹配检查
若模式匹配，且本次会话中尚未针对该文件+规则发出过警告：
- 将警告打印至标准错误输出（Claude可看到）
- 退出码为2→阻止工具调用
- 将警告键保存至
```
~/.claude/security_warnings_state_<session>.json
```
若模式匹配，但本次会话中已发出过该警告：
- 允许工具调用（退出码为0）——Claude已看过一次警告
若未匹配到任何模式：
- 允许工具调用（退出码为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()

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

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

security-guidance

Original

Translation

Security Guidance Hook

安全指导钩子

What It Catches

检测范围

How It Works

工作原理

Installation

安装

In Claude Code:

在Claude Code中执行：

Configuration

配置

Hook is bypassed for this session

本次会话中钩子将被绕过

Per-File Override Pattern

单文件覆盖模式

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。

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

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

State Files

状态文件

Debug Log

调试日志

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

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

Source + Attribution

源码与归属

Anti-Patterns

反模式

Disabling the hook by default

默认禁用钩子

Modifying the pattern list without security review

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

Treating session-state as immutable security policy

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

Related Skills

相关技能

Trigger Phrases

触发短语