File Protection Verifier

Prevents modification of critical system files, production configurations, and vendor directories by blocking Edit, MultiEdit, and Write operations on protected paths.

When to Use This Hook

Attach this hook when you need to:

• Protect production config files, system directories, and vendor code from accidental edits
• Enforce read-only zones within your project where certain files must never be modified directly
• Prevent Claude from editing files that should only be changed through specific processes (migrations, deploys)

Consider alternatives when:

• Your file system permissions already enforce the access controls you need
• You need fine-grained per-user access control rather than blanket path protection

Quick Start

Configuration

Copy
name: file-protection-verifier
type: hook
trigger: PreToolUse
category: security

Example Trigger

Copy
# Hook triggers before Claude edits a protected file
claude> Edit /etc/nginx/nginx.conf
# Verifier blocks the edit

Example Output

File Protection Verifier: Checking path...
  File: /etc/nginx/nginx.conf
  Matched pattern: */etc/*
  Status: BLOCKED
  Error: File /etc/nginx/nginx.conf is protected from modification
  Reason: System configuration files cannot be edited directly

Core Concepts

Protection Rules Overview

Aspect	Details
System Directories	/etc/*, /usr/bin/*, /usr/sbin/*
Production Files	*.production.*, *prod*config*
Vendor Code	*/node_modules/*, */vendor/*
Matchers	Edit, MultiEdit, Write
Enforcement	Hard block with exit code 1

Protection Workflow

File Modification Requested
          |
   Get File Path
          |
   Check Against Patterns
          |
   ┌──────┼──────┐
   |      |      |
System  Prod   Vendor
Paths   Files  Code
   |      |      |
   └──────┼──────┘
          |
   Any Match?
    /        \
  Yes         No
   |           |
  BLOCK     ALLOW
  (exit 1)  (proceed)

Configuration

Parameter	Type	Default	Description
protected_patterns	string[]	["*/etc/*","*/usr/bin/*","*.production.*"]	Glob patterns for protected file paths
vendor_patterns	string[]	["*/node_modules/*","*/vendor/*"]	Third-party code directories to protect
custom_patterns	string[]	[]	Project-specific paths to add to protection
allow_overrides	boolean	false	Allow file-level override comments
exit_code	number	1	Exit code when blocking a modification

Best Practices

1. Start with Sensible Defaults - The built-in patterns protect system files and vendor code. Add project-specific patterns incrementally based on actual incidents rather than trying to predict every scenario.

2. Protect Lock Files - Add package-lock.json, yarn.lock, and Gemfile.lock to protected patterns. These files should only change through package manager operations, not direct edits.

3. Document Why Files Are Protected - When blocking an edit, include the reason in the error message. "Protected: migration files must be generated via CLI" is more helpful than just "BLOCKED."

4. Use Pattern Specificity - Broad patterns like *config* catch too many files. Use specific patterns like *prod*config* or *.production.* to protect only what needs protecting.

5. Review Protection Lists Quarterly - As projects evolve, some protected files may need editing and new critical files may appear. Review your protection patterns periodically to keep them current.

Common Issues

1. Over-Broad Pattern Matching - A pattern like *config* blocks editing legitimate config files that should be modifiable. Use more specific patterns or add an allowlist for exceptions.

2. Case Sensitivity on macOS - macOS file systems are case-insensitive by default, but glob matching may be case-sensitive. Ensure patterns match regardless of casing to avoid bypasses.

3. Symlink Bypass - If a protected file is accessed through a symlink with a different path, the pattern may not match. Resolve symlinks before pattern matching for thorough protection.