claude-hooks/docs/how-to/customize-patterns.md

# How to Add Custom Command Validation Patterns

**When to use this guide**: You want to block specific commands or add warnings for commands that are problematic in your environment.

## Add a Dangerous Command Pattern

If you have commands that should never be run in your environment:

1. **Edit the command validator**:
   ```bash
   nano hooks/command_validator.py
   ```

2. **Find the dangerous_patterns list** (around line 23):
   ```python
   self.dangerous_patterns = [
       r'rm\s+-rf\s+/',           # Delete root
       r'mkfs\.',                 # Format filesystem  
       # Add your pattern here
   ]
   ```

3. **Add your pattern**:
   ```python
   self.dangerous_patterns = [
       r'rm\s+-rf\s+/',           # Delete root
       r'mkfs\.',                 # Format filesystem
       r'docker\s+system\s+prune\s+--all',  # Delete all Docker data
       r'kubectl\s+delete\s+namespace\s+production',  # Delete prod namespace
   ]
   ```

4. **Test your pattern**:
   ```bash
   echo '{"tool": "Bash", "parameters": {"command": "docker system prune --all"}}' | python3 hooks/command_validator.py
   ```

   Should return: `{"allow": false, "message": "⛔ Command blocked: Dangerous command pattern detected"}`

## Add Warning Patterns

For commands that are risky but sometimes legitimate:

1. **Find the suspicious_patterns list**:
   ```python
   self.suspicious_patterns = [
       r'sudo\s+rm',              # Sudo with rm
       r'chmod\s+777',            # Overly permissive
       # Add your pattern here
   ]
   ```

2. **Add patterns that should warn but not block**:
   ```python
   self.suspicious_patterns = [
       r'sudo\s+rm',              # Sudo with rm
       r'chmod\s+777',            # Overly permissive
       r'npm\s+install\s+.*--global',  # Global npm installs
       r'pip\s+install.*--user',       # User pip installs
   ]
   ```

## Customize for Your Tech Stack

### For Docker Environments

Add Docker-specific protections:
```python
# In dangerous_patterns:
r'docker\s+rm\s+.*-f.*',      # Force remove containers
r'docker\s+rmi\s+.*-f.*',     # Force remove images

# In suspicious_patterns:  
r'docker\s+run.*--privileged',  # Privileged containers
r'docker.*-v\s+/:/.*',         # Mount root filesystem
```

### For Kubernetes

Protect production namespaces:
```python
# In dangerous_patterns:
r'kubectl\s+delete\s+.*production.*',
r'kubectl\s+delete\s+.*prod.*',
r'helm\s+delete\s+.*production.*',

# In suspicious_patterns:
r'kubectl\s+apply.*production.*',
r'kubectl.*--all-namespaces.*delete',
```

### For Database Operations

Prevent destructive database commands:
```python
# In dangerous_patterns:
r'DROP\s+DATABASE.*',
r'TRUNCATE\s+TABLE.*',
r'DELETE\s+FROM.*WHERE\s+1=1',

# In suspicious_patterns:
r'UPDATE.*SET.*WHERE\s+1=1',
r'ALTER\s+TABLE.*DROP.*',
```

## Environment-Specific Patterns

### For Production Servers

```python
# In dangerous_patterns:
r'systemctl\s+stop\s+(nginx|apache|mysql)',
r'service\s+(nginx|apache|mysql)\s+stop',
r'killall\s+-9.*',

# In suspicious_patterns:
r'sudo\s+systemctl\s+restart.*',
r'sudo\s+service.*restart.*',
```

### For Development Machines

```python
# In suspicious_patterns:
r'rm\s+-rf\s+node_modules',    # Can break local dev
r'git\s+reset\s+--hard\s+HEAD~[0-9]+',  # Lose multiple commits
r'git\s+push\s+.*--force.*',   # Force push
```

## Test Your Custom Patterns

Create a test script to verify your patterns work:

```bash
cat > test_patterns.sh << 'EOF'
#!/bin/bash

# Test dangerous pattern (should block)
echo "Testing dangerous pattern..."
echo '{"tool": "Bash", "parameters": {"command": "docker system prune --all"}}' | python3 hooks/command_validator.py

# Test suspicious pattern (should warn)  
echo "Testing suspicious pattern..."
echo '{"tool": "Bash", "parameters": {"command": "npm install -g dangerous-package"}}' | python3 hooks/command_validator.py

# Test normal command (should pass)
echo "Testing normal command..."
echo '{"tool": "Bash", "parameters": {"command": "ls -la"}}' | python3 hooks/command_validator.py
EOF

chmod +x test_patterns.sh
./test_patterns.sh
```

## Advanced: Context-Aware Patterns

For patterns that depend on file context:

1. **Edit the validation function** to check current directory or files:
   ```python
   def validate_command_safety(self, command: str) -> ValidationResult:
       # Your existing patterns...
       
       # Context-aware validation
       if "git push" in command.lower():
           # Check if we're in a production branch
           try:
               current_branch = subprocess.check_output(['git', 'branch', '--show-current'], 
                                                       text=True).strip()
               if current_branch in ['main', 'master', 'production']:
                   return ValidationResult(
                       allowed=True,
                       reason="⚠️ Pushing to protected branch",
                       severity="warning"
                   )
           except:
               pass
   ```

## Pattern Syntax Reference

Use Python regex patterns:

- `\s+` - One or more whitespace characters
- `.*` - Any characters (greedy)
- `.*?` - Any characters (non-greedy)  
- `[0-9]+` - One or more digits
- `(option1|option2)` - Either option1 or option2
- `^` - Start of string
- `$` - End of string

**Examples**:
- `r'rm\s+-rf\s+/'` - Matches "rm -rf /"
- `r'git\s+push.*--force'` - Matches "git push" followed by "--force" anywhere
- `r'^sudo\s+'` - Matches commands starting with "sudo"

## Reload Changes

After modifying patterns:

1. **Test the changes**:
   ```bash
   ./test_patterns.sh
   ```

2. **No restart needed** - changes take effect immediately since hooks are called fresh each time

3. **Verify in Claude** by trying a command that should trigger your new pattern