Pre-Write Secret Scanner - Claude Code Hook

Features

• Scans the exact text a Write, Edit, or MultiEdit call would persist — before it reaches disk — and blocks it on a match (exit code 2).
• Detects high-confidence secret formats whose patterns mirror the canonical gitleaks rule set, so detections map to real provider key shapes rather than ad-hoc guesses.
• Reports the detected secret type and target file without ever echoing the secret value.
• Fails open: if jq is unavailable or the tool input carries no new text, the write proceeds untouched.
• Pure local bash + jq, no network access, no persisted logs.

How it works

Claude Code passes the pending tool call to the hook as JSON on stdin. The hook extracts only the new text the call would write (tool_input.content for Write, new_string for Edit, and each edits[].new_string for MultiEdit), then tests it against a list of named secret patterns. If any match, it prints a redacted message to stderr and exits 2, which instructs Claude Code to block the call so the secret is never saved.

Detected secret types

• AWS access key IDs (AKIA…)
• GitHub personal access and OAuth tokens (ghp_, gho_, ghu_, ghs_, ghr_) and fine-grained tokens (github_pat_…)
• OpenAI API keys (sk-…, sk-proj-…)
• Slack tokens (xox[baprs]-…)
• Google API keys (AIza…)
• Stripe secret keys (sk_live_…)
• PEM private key blocks (-----BEGIN … PRIVATE KEY-----)

Use cases

• Stop Claude from hardcoding a leaked credential into source, config, or test fixtures during an agentic session.
• Add a defense-in-depth layer ahead of (not instead of) commit-time scanners like gitleaks in CI.
• Keep .env-style values out of files that are about to be written to a tracked directory.

Installation

1. Create a trusted user hooks directory: mkdir -p "$HOME/.claude/hooks"
2. Create the hook file: touch "$HOME/.claude/hooks/pre-write-secret-scanner.sh"
3. Paste the script body into that file and make it executable: chmod +x "$HOME/.claude/hooks/pre-write-secret-scanner.sh"
4. Add the configuration below to ~/.claude/settings.json (user) or .claude/settings.json (project). Keep user-level hooks pointed at this trusted $HOME script; do not use $CLAUDE_PROJECT_DIR in global settings because untrusted projects can control that path.

Requirements

• Claude Code CLI with hooks enabled
• bash shell
• jq (for parsing the tool input)

Hook configuration

This configuration references the trusted script installed under your home directory, so it is safe to use from user-level settings across projects. If you instead keep a project-local copy under .claude/hooks, only reference that project-local path from that same project's .claude/settings.json, never from ~/.claude/settings.json.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.claude/hooks/pre-write-secret-scanner.sh"
          }
        ]
      }
    ]
  }
}

Limitations

• Regex detection cannot catch every secret format and may flag a non-secret that happens to match a shape; tune the PATTERNS list for your stack.
• It inspects only the content of the pending write, not files already on disk — pair it with a repository-wide scanner for full coverage.

Source and references

• Secret pattern shapes mirror the canonical rules in gitleaks.
• Claude Code hook contract and exit-code semantics: Claude Code hooks documentation.

• Source repositorygithub.com 2026-07-18T19:14:44+00:00
• Documentationcode.claude.com
• Submitted by jony3762026-06-04