Dynamic Secret Detection Guard Gate

Dynamically detects and blocks secrets using pattern learning, entropy analysis, and contextual awareness across all file types during edit and commit operations.

When to Use This Hook

Attach this hook when you need to:

• Detect novel secret formats that static pattern lists miss using entropy-based analysis
• Build a project-specific secret detection model that learns from your codebase patterns
• Guard against secrets in configuration files, environment templates, and infrastructure-as-code

Consider alternatives when:

• A simpler static pattern scanner meets your needs without the complexity of dynamic analysis
• You use a centralized secrets vault and your code never contains credentials by design

Quick Start

Configuration

Copy
name: dynamic-secret-detection-guard-gate
type: hook
trigger: PreToolUse
category: security

Example Trigger

Copy
# Hook triggers before any edit or commit that introduces high-entropy strings
claude> Edit src/config/apiClient.ts
# Guard analyzes new content for potential secrets

Example Output

Dynamic Secret Guard: Analyzing edit content...
  Static patterns: 0 matches
  Entropy analysis:
    Line 23: "a8f2k9x1m4p7..." (entropy: 4.7, threshold: 4.5) FLAGGED
    Context: variable assignment to `apiToken`
  Contextual check:
    Variable name contains "token" → HIGH confidence secret
  Decision: BLOCKED
  Suggestion: Use process.env.API_TOKEN instead

Core Concepts

Detection Layers Overview

Aspect	Details
Static Patterns	30+ provider-specific regex patterns (AWS, Stripe, GitHub, etc.)
Entropy Analysis	Shannon entropy calculation flags high-randomness strings
Contextual Clues	Variable names containing "key", "secret", "token", "password"
Learning Model	Builds allowlist of known-safe high-entropy strings (UUIDs, hashes)
Multi-File Scope	Tracks secrets across related files (config + code)

Detection Workflow

Content Change Detected
         |
   Static Pattern Scan
    /            \
  Match        No Match
   |               |
  BLOCK      Entropy Analysis
              /          \
        High Entropy   Normal
              |            |
       Context Check    ALLOW
        /         \
   Suspicious    Benign
      |            |
    BLOCK      Add to
   + Report    Allowlist

Configuration

Parameter	Type	Default	Description
entropy_threshold	number	4.5	Shannon entropy score above which strings are flagged
min_string_length	number	16	Minimum string length to analyze for entropy
context_keywords	string[]	["key","secret","token","password","credential"]	Variable name patterns indicating secrets
allowlist_path	string	.claude/secret-allowlist.json	Path to known-safe high-entropy strings
learning_mode	boolean	false	Auto-add confirmed-safe strings to allowlist

Best Practices

1. Tune Entropy Threshold Carefully - An entropy threshold of 4.5 catches most secrets while allowing common strings. Lower values catch more but create false positives on UUIDs and hash constants.

2. Maintain an Allowlist - Base64-encoded constants, UUID strings, and cryptographic test vectors trigger entropy analysis. Add verified-safe strings to the allowlist to prevent repeated false positives.

3. Combine Static and Dynamic Detection - Static patterns catch known providers with high precision. Entropy analysis catches novel formats. Together they provide comprehensive coverage.

4. Use Context to Boost Confidence - A high-entropy string assigned to a variable named apiKey is almost certainly a secret. Context-aware scoring reduces false positives by requiring both entropy and naming signals.

5. Review Flagged Items Promptly - When the guard flags a potential secret, investigate immediately. Deferred review leads to accumulated flags that get batch-dismissed without proper examination.

Common Issues

1. UUIDs Triggering False Positives - UUIDs have high entropy but are not secrets. Add UUID patterns (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) to the allowlist or detect the format explicitly.

2. Performance on Large Files - Entropy calculation on every string in a large file is computationally expensive. Limit analysis to strings in assignment contexts or known variable patterns.

3. Encoded Secrets Bypassing Detection - Base64-encoded or hex-encoded secrets may fall below the entropy threshold when encoded. Consider decoding common encodings before entropy analysis.