Skip to content

secondsky/claude-skills / plugins/claude-hook-writer/skills/claude-hook-writer

claude-hook-writer

Verified

Expert guidance for writing secure, reliable, and performant Claude Code hooks - validates design decisions, enforces best practices, and prevents common pitfalls. Use when creating, reviewing, or debugging Claude Code hooks.

references/security-requirements.md

View on GitHub
# Security Requirements

Hooks execute automatically with user permissions and can read, modify, or delete any file the user can access. Security is non-negotiable.

---

## MUST-HAVE Security Checks

Every hook must implement these security measures:

### 1. Input Validation

Always validate JSON input before using it:

```bash
#!/bin/bash
set -euo pipefail  # Exit on errors, undefined vars

INPUT=$(cat)

# Validate JSON parse
if ! FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty' 2>&1); then
  echo "JSON parse failed: $FILE" >&2
  exit 1
fi

# Validate field exists
if [[ -z "$FILE" ]]; then
  echo "No file path in input" >&2
  exit 1
fi
```

**Why this matters**: Malformed JSON or missing fields will crash hooks. Always validate before using.

---

### 2. Path Sanitization

Validate files are in the project directory:

```bash
# Validate file is in project
if [[ "$FILE" != "$CLAUDE_PROJECT_DIR"* ]]; then
  echo "File outside project: $FILE" >&2
  exit 2  # Block operation
fi

# Validate no directory traversal
if [[ "$FILE" == *".."* ]]; then
  echo "Path traversal detected: $FILE" >&2
  exit 2
fi
```

**Common attacks prevented**:
- `../../../etc/passwd` (directory traversal)
- `/etc/shadow` (absolute path outside project)
- `~/.ssh/id_rsa` (home directory access)

---

### 3. Sensitive File Protection

Block operations on sensitive files:

```bash
# Block list (extend as needed)
BLOCKED_PATTERNS=(
  ".env"
  ".env.*"
  "*.pem"
  "*.key"
  "*credentials*"
  "*secret*"
  ".git/*"
  ".ssh/*"
)

for pattern in "${BLOCKED_PATTERNS[@]}"; do
  if [[ "$FILE" == $pattern ]]; then
    echo "Blocked: $FILE matches sensitive pattern $pattern" >&2
    exit 2
  fi
done
```

**Files to always block**:
- `.env`, `.env.local`, `.env.production` (environment secrets)
- `*.pem`, `*.key` (private keys)
- `*credentials*`, `*secret*` (anything with credentials/secrets in name)
- `.git/*` (Git internals)
- `.ssh/*` (SSH keys)

---

### 4. Quote All Variables

Spaces and special characters in paths break unquoted variables:

```bash
# ❌ WRONG - breaks on spaces
cat $FILE              # Fails on "my file.txt"
prettier --write $FILE # Fails with spaces
rm $FILE              # DANGEROUS - could delete wrong files

# ✅ RIGHT - handles spaces and special chars
cat "$FILE"              # Handles spaces
prettier --write "$FILE" # Safe
rm "$FILE"              # Scoped to exact file
```

**Test with these filenames**:
- `"my file.txt"` (spaces)
- `"文件.txt"` (Unicode)
- `"file (1).txt"` (special chars)

---

### 5. Use Absolute Paths for Scripts

Relative paths might not resolve correctly:

```bash
# ❌ WRONG - relative path might not work
./my-script.sh

# ✅ RIGHT - explicit absolute path
"${CLAUDE_PLUGIN_ROOT}/scripts/my-script.sh"

# ✅ ALSO RIGHT - use environment variable
"$HOME/.claude/scripts/my-script.sh"
```

**Why**: Hook execution directory might not be where you expect. Always use absolute paths.

---

## Security Checklist

Before deploying a hook, verify:

- [ ] All JSON input is validated before use
- [ ] All file paths are validated to be in `$CLAUDE_PROJECT_DIR`
- [ ] Path traversal attempts (`..`) are blocked
- [ ] Sensitive files (`.env`, `*.key`, etc.) are blocked
- [ ] All variables containing paths are quoted
- [ ] All script paths are absolute
- [ ] No shell injection vulnerabilities (careful with `eval`, `bash -c`)
- [ ] No command injection via unsanitized input

---

## Common Security Vulnerabilities

### Vulnerability #1: Command Injection

```bash
# ❌ DANGEROUS - command injection
COMMAND=$(echo "$INPUT" | jq -r '.input.command')
eval "$COMMAND"  # Attacker can run arbitrary code

# ✅ SAFE - validate and sanitize
COMMAND=$(echo "$INPUT" | jq -r '.input.command // empty')
# Only allow specific commands
case "$COMMAND" in
  "npm test"|"npm build")
    $COMMAND
    ;;
  *)
    echo "Command not allowed: $COMMAND" >&2
    exit 2
    ;;
esac
```

### Vulnerability #2: Path Traversal

```bash
# ❌ VULNERABLE - no path validation
FILE=$(echo "$INPUT" | jq -r '.input.file_path')
rm "$FILE"  # Could delete ../../../etc/passwd

# ✅ SAFE - validate path first
FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty')
[[ "$FILE" == "$CLAUDE_PROJECT_DIR"* ]] || exit 2
[[ "$FILE" != *".."* ]] || exit 2
rm "$FILE"
```

### Vulnerability #3: Trusting User Input

```bash
# ❌ DANGEROUS - trust user input
MESSAGE=$(echo "$INPUT" | jq -r '.input.message')
echo "$MESSAGE" | mail -s "Alert" admin@example.com

# ✅ SAFE - sanitize and validate
MESSAGE=$(echo "$INPUT" | jq -r '.input.message // empty')
# Remove special chars
MESSAGE=$(echo "$MESSAGE" | tr -cd '[:alnum:][:space:].')
# Limit length
MESSAGE="${MESSAGE:0:200}"
echo "$MESSAGE" | mail -s "Alert" admin@example.com
```

---

## Security Best Practices

### Principle of Least Privilege

Only access what you need:

```bash
# Don't read entire files if you only need metadata
# ❌ Unnecessary file read
content=$(cat "$FILE")

# ✅ Better - just check if exists
[[ -f "$FILE" ]] && echo "File exists"
```

### Fail Closed on Security Checks

When in doubt, block:

```bash
# If validation fails, block rather than allow
if ! validate_path "$FILE"; then
  echo "Path validation failed, blocking" >&2
  exit 2  # Block
fi

# Don't continue on validation errors
```

### Log Security Events

Log blocked operations for audit:

```bash
LOG_FILE=~/.claude-hooks/security.log

if [[ "$FILE" == ".env" ]]; then
  echo "[$(date)] BLOCKED: Attempt to modify .env" >> "$LOG_FILE"
  echo "  File: $FILE" >> "$LOG_FILE"
  echo "  Session: $SESSION_ID" >> "$LOG_FILE"
  exit 2
fi
```

---

## Testing Security

### Test Malicious Input

```bash
# Test path traversal
echo '{"input":{"file_path":"../../../etc/passwd"}}' | ./my-hook.sh
# Expected: Exit 2 (blocked)

# Test sensitive file
echo '{"input":{"file_path":".env"}}' | ./my-hook.sh
# Expected: Exit 2 (blocked)

# Test absolute path outside project
echo '{"input":{"file_path":"/etc/shadow"}}' | ./my-hook.sh
# Expected: Exit 2 (blocked)

# Test malformed JSON
echo 'not json' | ./my-hook.sh
# Expected: Exit 1 (error logged)
```

### Test Edge Cases

```bash
# File with spaces
echo '{"input":{"file_path":"my file.txt"}}' | ./my-hook.sh

# Unicode filename
echo '{"input":{"file_path":"文件.txt"}}' | ./my-hook.sh

# Special characters
echo '{"input":{"file_path":"file (1).txt"}}' | ./my-hook.sh
```

---

## Security Resources

- [OWASP Command Injection](https://owasp.org/www-community/attacks/Command_Injection)
- [Path Traversal Attacks](https://owasp.org/www-community/attacks/Path_Traversal)
- [Bash Security Pitfalls](https://mywiki.wooledge.org/BashPitfalls)
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall