credential-leak-detector

credential-leak-detector — Catch Leaked Credentials Before They Spread

Every time your agent runs a Bash command, the output flows back into the conversation — and into your API provider's logs, any monitoring tools, and the model's context window. If that output contains an API key, a private key, or a database password, the credential is now exposed in places you never intended.

This hook scans every Bash tool response for 14 credential patterns before the output reaches the agent. Critical matches (API keys, AWS credentials, private keys) get blocked entirely. High-severity matches get redacted with a warning. Suspicious patterns get flagged as advisories. No external dependencies — just Python stdlib.

What Gets Detected

Critical (Blocks the response)

High (Blocks or redacts with warning)

Medium (Advisory warning)

Installation

Step 1: Create the hook script

mkdir -p .claude/hooks

Create .claude/hooks/credential-leak-detector.py with the contents below.

The Script

Save this as .claude/hooks/credential-leak-detector.py:

#!/usr/bin/env python3
"""
credential-leak-detector.py — PostToolUse hook that scans Bash output
for leaked credentials. Blocks critical leaks, redacts high-severity
matches, warns on suspicious patterns.

Exit code 2 = block (critical credential found)
Exit code 0 = allow (clean or advisory-only)
"""
import sys
import json
import re

# --- Masking ---

def mask(value):
    """Mask a credential: first 4 + **** + last 4, or full mask if short."""
    v = value.strip()
    if len(v) < 12:
        return "*" * len(v)
    return v[:4] + "****" + v[-4:]


# --- Pattern Definitions ---
# (name, regex, severity, action)
# severity: critical, high, medium
# action: block, redact, warn

PATTERNS = [
    # Critical — Block
    ("OpenAI API key",
     r'(sk-(?:proj-)?[a-zA-Z0-9]{20,})',
     "critical", "block"),

    ("Anthropic API key",
     r'(sk-ant-api[a-zA-Z0-9_-]{90,})',
     "critical", "block"),

    ("AWS access key",
     r'(AKIA[0-9A-Z]{16})',
     "critical", "block"),

    ("GitHub token (classic)",
     r'(gh[pousr]_[A-Za-z0-9_]{36,})',
     "critical", "block"),

    ("GitHub fine-grained PAT",
     r'(github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59})',
     "critical", "block"),

    ("Stripe secret key",
     r'(sk_(?:live|test)_[a-zA-Z0-9]{24,})',
     "critical", "block"),

    ("PEM private key",
     r'(-----BEGIN (?:RSA |EC |DSA )?PRIVATE KEY-----)',
     "critical", "block"),

    # High — Block
    ("Google API key",
     r'(AIza[0-9A-Za-z_-]{35})',
     "high", "block"),

    ("Slack token",
     r'(xox[bpors]-[0-9a-zA-Z-]{10,})',
     "high", "block"),

    ("SendGrid API key",
     r'(SG\.[a-zA-Z0-9_-]{22}\.[a-zA-Z0-9_-]{43})',
     "high", "block"),

    # High — Redact
    ("Twilio auth key",
     r'(SK[0-9a-fA-F]{32})',
     "high", "redact"),

    ("Bearer auth token",
     r'(?:Authorization|Bearer)\s*[:=]\s*Bearer\s+([^\s]{20,})',
     "high", "redact"),

    # Medium — Warn
    ("Generic secret assignment",
     r'(?:password|secret|token|api_key)\s*[=:]\s*[\'"]?([^\s\'"]{16,})',
     "medium", "warn"),

    ("High-entropy hex string",
     r'\b([a-fA-F0-9]{64})\b',
     "medium", "warn"),
]


# --- Main ---

def scan(text):
    """Scan text for credential patterns. Returns list of findings."""
    findings = []
    for name, pattern, severity, action in PATTERNS:
        matches = re.findall(pattern, text)
        for m in matches:
            findings.append({
                "name": name,
                "severity": severity,
                "action": action,
                "matched": m if isinstance(m, str) else m[0],
            })
    return findings


def main():
    try:
        payload = json.load(sys.stdin)
    except Exception:
        sys.exit(0)

    tool_name = payload.get("tool_name", "")
    tool_response = payload.get("tool_response", "")

    # Only scan Bash output
    if tool_name != "Bash":
        sys.exit(0)

    if not tool_response:
        sys.exit(0)

    # Handle tool_response as string or dict
    if isinstance(tool_response, dict):
        text = tool_response.get("stdout", "") + tool_response.get("stderr", "")
    else:
        text = str(tool_response)

    if not text:
        sys.exit(0)

    findings = scan(text)

    if not findings:
        sys.exit(0)

    # Classify findings
    blockers = [f for f in findings if f["action"] == "block"]
    redacts = [f for f in findings if f["action"] == "redact"]
    warnings = [f for f in findings if f["action"] == "warn"]

    # Critical/high blockers — stop the response
    if blockers:
        details = []
        for f in blockers:
            details.append(
                f"  - {f['name']} [{f['severity']}]: {mask(f['matched'])}"
            )
        reason = (
            "[credential-leak-detector] Credential(s) detected in command output. "
            "Response blocked to prevent exposure.\n\n"
            "Detected:\n" + "\n".join(details) + "\n\n"
            "The command output contained live credentials. Do NOT re-run this "
            "command or attempt to extract these values. If you need to verify "
            "a credential exists, check the env var or file without printing "
            "its value."
        )
        print(json.dumps({"decision": "block", "reason": reason}))
        sys.exit(2)

    # Redact findings — allow but warn with masked values
    messages = []
    if redacts:
        parts = []
        for f in redacts:
            parts.append(f"  - {f['name']}: {mask(f['matched'])}")
        messages.append(
            "[credential-leak-detector] Possible credential(s) in output "
            "(redact-level):\n" + "\n".join(parts) + "\n"
            "Avoid storing, logging, or repeating these values."
        )

    # Warn findings — advisory only
    if warnings:
        parts = []
        for f in warnings:
            parts.append(f"  - {f['name']}: {mask(f['matched'])}")
        messages.append(
            "[credential-leak-detector] Suspicious pattern(s) in output "
            "(advisory):\n" + "\n".join(parts) + "\n"
            "These may be secrets. Avoid including them in commits, logs, "
            "or messages."
        )

    if messages:
        print(json.dumps({"additionalContext": "\n".join(messages)}))

    sys.exit(0)


if __name__ == "__main__":
    main()