security-hooks

Security Hooks

A Claude Code plugin that detects and blocks potential secrets before git commits.

Quick Start

# Add the marketplace
/plugin marketplace add /path/to/claude-plugins

# Install the plugin
/plugin install security-hooks@plugins-by-james

That's it. Pre-built binaries are included for all platforms. The hook automatically scans all git commit operations for secrets.

For development: Clone the repo and run make build to compile locally.

Table of Contents

• What Are Security Hooks?
• How It Works
• Secret Patterns Detected
• Smart Filtering
• Output Format
• Hook Configuration
• Exit Codes
• Usage Examples
• Running Tests
• Environment Variables
• Remediation Guidance
• Best Practices
• Limitations
• Debugging
• License

What Are Security Hooks?

Security hooks are PreToolUse hooks that run before git operations to scan staged files for secrets, API keys, credentials, and sensitive data. They act as a final security gate before code is committed.

Key Features:

• Fail-closed design (errors block commits for safety)
• TOCTOU-safe (reads from git staging area, not disk)
• Zero external dependencies (Go stdlib only)
• 26 pre-compiled regex patterns for fast detection
• Hardcoded .env value detection with word boundaries
• Compiled binary for instant startup

How It Works

Detection Methods

1. Pattern-Based Detection

Scans for 26 common secret patterns using pre-compiled regex.

2. Hardcoded .env Value Detection

• Parses .env file for environment variable values
• Searches staged files for exact matches using word boundaries
• Catches secrets that are copy-pasted from .env into source code

Processing Pipeline

1. Receive Bash tool call with "git commit" command
2. Get CLAUDE_PROJECT_DIR (or cwd)
3. Parse .env file (if exists)
4. Get staged files: git diff --cached --name-only
5. For each staged file:
   - Skip binary files (30+ extensions)
   - Skip .env files
   - Skip files >10MB or <10 bytes
   - Read content from git staging area
   - Check against 26 secret patterns
   - Check against hardcoded .env values
6. If secrets found: block commit with detailed report (exit 2)
7. On errors: block commit (exit 2, fail-closed)

Secret Patterns Detected

Cloud Provider Credentials

Pattern	Example Format
AWS Access Key ID	AKIA[0-9A-Z]{16}
AWS Secret Access Key	aws_secret_access_key = ...
Google API Key	AIza[0-9A-Za-z-_]{35}

AI Service API Keys

Pattern	Example Format
OpenAI API Key	sk-[a-zA-Z0-9]{20,}
OpenAI Project Key	sk-proj-[a-zA-Z0-9]{20,}
Anthropic API Key	sk-ant-[a-zA-Z0-9-]{20,}

Version Control & CI/CD

Pattern	Example Format
GitHub PAT	ghp_[a-zA-Z0-9]{36}
GitHub OAuth Token	gho_[a-zA-Z0-9]{36}
GitHub User Token	ghu_[a-zA-Z0-9]{36}
GitHub Server Token	ghs_[a-zA-Z0-9]{36}
GitHub Refresh Token	ghr_[a-zA-Z0-9]{36}
npm Access Token	npm_[a-zA-Z0-9]{36}
PyPI API Token	pypi-[a-zA-Z0-9]{43,}

Communication Services

Pattern	Example Format
Slack Token	xox[baprs]-[a-zA-Z0-9-]{10,}
Discord Bot Token	[MN][A-Za-z\d]{23,}.[A-Za-z\d_-]{6}.[A-Za-z\d_-]{27}
Twilio API Key	SK[a-fA-F0-9]{32}
SendGrid API Key	SG.[a-zA-Z0-9_-]{20,}.[a-zA-Z0-9_-]{20,}
Mailgun API Key	key-[a-zA-Z0-9]{32}

Payment Services

Pattern	Example Format
Stripe Secret Key	sk_live_[a-zA-Z0-9]{24,}
Stripe Restricted Key	rk_live_[a-zA-Z0-9]{24,}

Database Connection Strings

Pattern	Example Format
PostgreSQL	postgres(ql)?://user:pass@host
MySQL	`[REDACTED:DB Connection String]
MongoDB	mongodb(+srv)?://user:pass@host

Generic Patterns

Pattern	Description
Private Keys	-----BEGIN (RSA|DSA|EC|OPENSSH) PRIVATE KEY-----
Bearer Tokens	bearer [a-zA-Z0-9_-.]{20,}
Generic Secrets	(secret|token)\s*[:=]\s*[value]{20,}

Smart Filtering

Binary Files Skipped (32 extensions)

Images: .png, .jpg, .jpeg, .gif, .ico, .svg

Archives: .zip, .tar, .gz, .7z

Executables: .exe, .dll, .so, .bin

Compiled: .wasm, .pyc, .class

Fonts: .woff, .woff2, .ttf, .eot

Media: .mp3, .mp4, .mov