security-guidance

---
name: security-guidance
description: Use as a PreToolUse hook that blocks command injection, XSS, SQL injection, unsafe deserialization, GitHub Actions, and code injection before write operations.
category: Engineering
version: 1.0.0
tools: []
---

# Security Guidance Hook

PreToolUse hook that blocks 12 common security anti-patterns before Claude Code writes them.

## Patterns Caught

The hook scans file paths and content for dangerous patterns:

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

## How It Works

1. Before Edit/Write/MultiEdit operation executes
2. Hook extracts file path and content
3. Checks against pattern table
4. If pattern matches and warning not shown in this session:
   - Print warning to output
   - Block the tool call
   - Cache the warning (file+rule) to session state
5. If pattern matched but warning already shown:
   - Allow the operation (user already saw warning)
6. If no pattern matches:
   - Allow the operation

## Installation

This plugin ships as a Claude Code plugin with hooks.json wiring. Once installed, the hook runs automatically before every file write operation.

## Configuration

Disable per-session via environment variable:
```
ENABLE_SECURITY_REMINDER=0
```

Use sparingly—the hook provides maximum value exactly when you're tempted to disable it due to deadline pressure.

## Per-File Override

If a file legitimately needs eval() or pickle (e.g., sandboxed REPL, deliberate fuzzer), document in the file with a comment:

```python
# SAFETY: pickle is required for this internal tool.
# This file does NOT accept untrusted input. See SECURITY.md for boundary analysis.
import pickle
```

Hook will still warn on first edit per session. Subsequent edits in same session are allowed (session-state caching).

## Why Substring-Based Detection

Trade-off compared to AST-based detection:
- Faster (milliseconds, no parsing)
- Cross-language (works for JS/TS/Python/YAML/etc.)
- Conservative (false positives are easy to dismiss; false negatives are dangerous)

For stricter detection, layer in proper SAST tools (semgrep, CodeQL) as CI step.

## State Files

Session-state cache stored at: `~/.claude/security_warnings_state_<session_id>.json`

Contains JSON list of `<file_path>-<rule_name>` keys showing which warnings have been displayed. Files:
- Auto-clean after 30 days (10% chance per invocation)
- Are session-scoped
- Can be safely deleted anytime

## Debug Logging

Hook writes debug info to `~/.claude/security-warnings-log.txt` for troubleshooting hook misfires.

## Attribution & Source

Ported from David Dworken's MIT-licensed implementation in alirezarezvani/aeo-box.
- Original 9 patterns preserved with exact warning text
- Added 3 patterns: subprocess shell=True, SQL injection, yaml.unsafe_load
- Debug log moved from /tmp to ~/.claude/ for persistence
- Restructured as claude-skills plugin

## Related

- threat-detection: Threat modeling and detection design
- ai-security: AI-specific security (prompt injection, etc.)
- ship-gate: Pre-production audit with 89 checks