Security Guidance — Vulnerability Pattern Detection Hook

🛡️ Security🔍 Pattern Detection🐍 Python Hook⚠️ Context-Aware Warnings

Architecture

The hook intercepts file-edit tool calls before they execute. The Python script parses the tool input, matches file paths and content against 9 security pattern rules, checks session state to avoid duplicate warnings, and returns advisory messages when new patterns are detected.

flowchart LR
    subgraph Trigger["PreToolUse Event"]
        A["Claude requests file edit"] --> B["PreToolUse fires"]
    end
    subgraph Hook["security_reminder_hook.py"]
        B --> C["Parse tool input"]
        C --> D["Match against 9 patterns"]
        D --> E{"New pattern\ndetected?"}
        E -->|"Yes"| F["Load session state"]
        F --> G{"Already\nwarned?"}
        G -->|"No"| H["Show warning + update state"]
        G -->|"Yes"| I["Skip — no warning"]
        E -->|"No"| I
    end
    subgraph Output["Result"]
        H --> J[" Security advisory in response"]
        I --> K["Silent pass-through"]
    end

Security Patterns

The hook monitors for 9 distinct vulnerability patterns, each with specific file path matching and substring detection rules:

State Management

Session-Scoped Warning Tracking

To prevent warning fatigue, the hook maintains a state file that tracks which pattern–file combinations have already triggered warnings in the current session. The state file is stored alongside the hook script and is automatically cleaned up after 30 days of inactivity.

{
  "eval:src/utils/parser.js": "2026-03-25T14:30:00Z",
  "innerHTML:src/components/Render.tsx": "2026-03-25T14:32:00Z",
  "pickle:ml/model_loader.py": "2026-03-24T09:15:00Z"
}

Data Flow

sequenceDiagram
    participant Claude as Claude LLM
    participant CC as Claude Code CLI
    participant Hook as security_reminder_hook.py
    participant State as .security-state.json
    participant Dev as Developer

    Claude->>CC: Request: edit file src/api/handler.js
    CC->>Hook: PreToolUse(tool="file_edit", input={path, content})
    Hook->>Hook: Match path *.js against 9 patterns
    Hook->>Hook: Found: child_process.exec in content

    Hook->>State: Load existing warnings
    State-->>Hook: No prior warning for exec:src/api/handler.js

    Hook->>State: Write new entry with timestamp
    Hook-->>CC:  "child_process.exec detected — consider execFile() or spawn() with array args"

    CC-->>Dev: Show security advisory
    CC->>Claude: Proceed with file edit + advisory context

    Note over Claude,Dev: Later in same session...

    Claude->>CC: Request: edit same file again
    CC->>Hook: PreToolUse(tool="file_edit", input={path, content})
    Hook->>State: Load existing warnings
    State-->>Hook: Already warned for exec:src/api/handler.js
    Hook-->>CC: Silent pass-through (no duplicate warning)

Key Components

Hook Implementation

PreToolUse Hook Configuration

#!/usr/bin/env python3
"""PreToolUse hook: scan file edits for 9 security vulnerability patterns."""

import json, sys, os, datetime

PATTERNS = [
    {"id": "gh-actions-injection", "path": ".github/workflows/", "substr": "${{",
     "msg": "GitHub Actions command injection — avoid interpolating untrusted input in run: blocks"},
    {"id": "child-process-exec", "path_ext": [".js", ".ts"], "substr": "child_process.exec",
     "msg": "child_process.exec is vulnerable to shell injection — use execFile() or spawn()"},
    {"id": "new-function", "path_ext": [".js", ".ts"], "substr": "new Function(",
     "msg": "new Function() enables dynamic code execution — equivalent to eval()"},
    {"id": "eval", "path_ext": [".js", ".ts", ".py"], "substr": "eval(",
     "msg": "eval() executes arbitrary code — use JSON.parse(), ast.literal_eval(), or a safe parser"},
    {"id": "dangerouslySetInnerHTML", "path_ext": [".jsx", ".tsx"], "substr": "dangerouslySetInnerHTML",
     "msg": "dangerouslySetInnerHTML enables XSS — sanitize with DOMPurify first"},
    {"id": "document-write", "path_ext": [".js", ".ts", ".html"], "substr": "document.write(",
     "msg": "document.write() enables DOM-based XSS — use textContent or createElement"},
    {"id": "innerHTML", "path_ext": [".js", ".ts"], "substr": ".innerHTML",
     "msg": ".innerHTML enables XSS — use textContent for text or sanitize HTML first"},
    {"id": "pickle", "path_ext": [".py"], "substr": "pickle.load",
     "msg": "pickle deserialization executes arbitrary code — use json or a safe format"},
    {"id": "os-system", "path_ext": [".py"], "substr": "os.system(",
     "msg": "os.system() is vulnerable to shell injection — use subprocess.run() with a list"},
]

STATE_FILE = os.path.join(os.path.dirname(__file__), ".security-state.json")

Interactions

Configuration Reference

Directory Map

security-guidance/
├── .claude-plugin/plugin.json          ← Role: Plugin manifest with PreToolUse hook
├── README.md                           ← Role: Pattern catalog and usage docs
└── hooks-handlers/
    ├── security_reminder_hook.py        ← Role: Pattern detection + state engine
    └── .security-state.json             ← Role: Session warning state (auto-generated)

Warning Examples

Example Security Advisory

When Claude attempts to edit a file containing a detected pattern:

⚠️ Security Advisory — child_process.exec
The file src/api/handler.js uses child_process.exec() which passes arguments through a shell, making it vulnerable to command injection.

Recommended: Use child_process.execFile() or child_process.spawn() with an argument array to avoid shell interpretation of special characters.

GitHub Actions Pattern

# ⚠️ DANGEROUS — PR title is attacker-controlled
- name: Greet
  run: echo "Hello ${{ github.event.pull_request.title }}"

# ✅ SAFE — use an environment variable
- name: Greet
  env:
    PR_TITLE: ${{ github.event.pull_request.title }}
  run: echo "Hello $PR_TITLE"