security-guidance

セキュリティガイダンスフック

Claude Code がコードを書き込む前に、よくある 12 のセキュリティ上のアンチパターンをブロックする PreToolUse フックです。

このスキルはスラッシュコマンドではなく、フックです。インストールすると、すべての 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. パターンが一致し、かつこのセッションでこのファイルとルールの組み合わせに対する警告がまだ表示されていない場合：
   • 警告を標準エラー出力に表示します（Claude に表示されます）
   • 終了コード 2 を返し、ツール呼び出しをブロックします
   • 警告キーを ~/.claude/security_warnings_state_<session>.json に保存します
5. パターンが一致しても、このセッションですでに警告が表示されている場合：
   • ツール呼び出しを許可します（終了コード 0）。Claude はすでに警告を一度確認しています
6. パターンが一致しない場合：
   • ツール呼び出しを許可します（終了コード 0）

インストール

このプラグインは、hooks.json でフックを設定した Claude Code プラグインとして提供されます。

# 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 などに対応します
• 保守的 — 誤検出は簡単に無視できます（キーを 1 回押すだけ）。見逃しは危険です

90％以上のケースでは、部分文字列による検出で十分です。より厳密な検出が必要な場合は、CI ステップとして適切な SAST ツール（semgrep、CodeQL）を追加してください。

状態ファイル

フックは「警告を表示済み」の状態を ~/.claude/security_warnings_state_<session_id>.json にキャッシュします。これらのファイルは次のように扱われます。

• 30 日後に自動的にクリーンアップされます（フックの呼び出しごとに 10％ の確率）
• セッションごとに管理されます（Claude の各セッションに専用のファイルが作られます）
• <file_path>-<rule_name> キーの JSON リストが格納されます

~/.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 プラグインとして再構成し、.claude-plugin/authoring-notes.json に attribution ブロックを追加（当初は plugin.json にありましたが、issue #954 で、拡張キーを含むマニフェストを Claude Code が拒否することが判明したため移動しました）

アンチパターン

デフォルトでフックを無効にする

本来の目的が損なわれます。ENABLE_SECURITY_REMINDER=0 をデフォルトにすると、安全策を無視することが習慣になってしまいます。検証済みで安全な特定の操作に限って使用してください。

セキュリティレビューなしでパターンリストを変更する

パターンの追加は誰でもできます。削除する場合はセキュリティレビューが必要です。パターンは実際の CVE クラスに対応しているためです。

session-state を不変のセキュリティポリシーとして扱う

キャッシュは警告のスパムを防ぎますが、セッションごとに適用されます。「一度却下したから」と長期的なポリシーとして頼らないでください。代わりに、ファイルごとのドキュメント化パターン（使用の根拠をコメントで記載する方法）を使用してください。

関連スキル

• 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 — スキルパッケージのセキュリティスキャン

トリガーフレーズ

• 「セキュリティフックを追加」
• 「書き込み前に危険なコードをブロック」
• 「コマンドインジェクションを検出」
• 「SQL インジェクションのパターンを防止」
• 「eval / pickle / os.system に警告」
• 「GitHub Actions セキュリティフック」

---

バージョン： 2.7.3 ソース： alirezarezvani/aeo-box の .claude/plugins/security-guidance/ から移植（元は Anthropic の David Dworken によるもの、MIT） ライセンス： MIT