Prompt-Injection Content Scanner - Claude Code Hook

Overview

Prompt-injection text becomes more dangerous when it lands in files that an AI assistant later treats as instructions: CLAUDE.md, agent definitions, prompt templates, rule files, context snippets, or markdown copied from external sources.

This hook gives Claude Code a local pre-write checkpoint. It scans proposed Write/Edit/MultiEdit content for common prompt-injection pattern categories before the text is saved into an AI-readable surface. When a match is found, it blocks the write by default and tells the user which category needs review without echoing the suspicious text back into logs.

Features

• Watches prompt, agent, rule, context, markdown, text, and instruction-like file paths by default.
• Extracts pending Write/Edit/MultiEdit content from Claude Code hook JSON.
• Detects instruction-override, secret-disclosure, role-confusion, hidden-instruction, and silent-tool-execution pattern categories.
• Reports categories only, reducing the chance that attack text is copied into terminal logs or CI transcripts.
• Supports PROMPT_INJECTION_SCANNER_MODE=advisory for warning-only rollout.
• Supports PROMPT_INJECTION_SCANNER_SCOPE=all when teams want every write payload scanned.

How It Works

Claude Code passes the pending tool call to the hook on stdin. The script reads the target path and new text, then decides whether the file is likely to be an AI-readable context surface. It normalizes whitespace and casing, applies a small set of regex categories, and exits 2 when a category matches.

The hook is intentionally a review trigger, not a proof of safety. OWASP, NIST, Microsoft, and NCSC all describe prompt injection as a persistent risk where filters can help, but cannot fully remove the need for least privilege, trusted data boundaries, and human review of untrusted instructions.

Use Cases

• Catch copied external text before it becomes part of CLAUDE.md, an agent file, or a prompt template.
• Warn when a generated markdown note contains text that asks an assistant to reveal hidden instructions, secrets, or environment variables.
• Keep red-team examples from being saved as active instruction material without review or redaction.
• Add a local checkpoint before stricter CI review of AI-facing documentation.

Installation

1. Create the hooks directory: mkdir -p .claude/hooks
2. Create the hook file: touch .claude/hooks/prompt-injection-content-scanner.sh
3. Paste the script body into that file and make it executable: chmod +x .claude/hooks/prompt-injection-content-scanner.sh
4. Add the configuration below to .claude/settings.json for a project hook or ~/.claude/settings.json for a user hook.

Hook Configuration

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/prompt-injection-content-scanner.sh"
          }
        ]
      }
    ]
  }
}

Script

#!/usr/bin/env bash
# Paste the scriptBody from this entry into:
# .claude/hooks/prompt-injection-content-scanner.sh

Configuration Options

• PROMPT_INJECTION_SCANNER_MODE=advisory prints warnings but exits 0.
• PROMPT_INJECTION_SCANNER_SCOPE=all scans every Write/Edit/MultiEdit payload instead of only context-like file paths.
• PROMPT_INJECTION_SCANNER_ALLOWLIST is an extended grep pattern checked against the target path and proposed content. Use it only for reviewed exceptions.

Expected Behavior

• Allowed: Ordinary markdown, agent, prompt, and context edits that do not match the scanner categories.
• Blocked: Context files containing instruction-override wording.
• Blocked: Prompt files containing requests to reveal hidden instructions, system prompts, secrets, environment variables, or API keys.
• Blocked: Agent/rule files containing concealment or silent tool-execution wording.

Limitations

• Regex matching cannot detect every direct or indirect prompt injection.
• Legitimate security documentation can trigger the hook; use advisory mode or quote/redact examples in files that are not active AI instructions.
• The hook scans new write payloads, not already committed files.
• It does not replace source trust review, least-privilege tool permissions, or runtime isolation for agentic workflows.

Troubleshooting

The hook blocks security documentation

Move examples into a dedicated research note that is not loaded as instructions, quote or redact the attack wording, or temporarily use advisory mode while a human reviews the content.

The hook misses an obvious attack phrase

Add a project-specific pattern by editing the script, then test it against representative prompt files before enabling block mode.

Too many files are being scanned

Keep the default context scope and move general notes outside prompt, instruction, context, and agent directories. Use PROMPT_INJECTION_SCANNER_SCOPE=all only when broad scanning is intentional.

Duplicate Check

Checked content/hooks/ for prompt injection, prompt-injection, instruction override, environment variable leak, secret scanner, MCP config, and unsafe shell command. Existing hooks cover pre-write secret formats, MCP config privacy, package download verification, and other local guards, but no existing hook focuses on prompt-injection text entering AI-readable prompt, agent, rule, markdown, and context files before a write.

Sources

• OWASP LLM01:2025 Prompt Injection
• Claude Code hooks documentation
• Microsoft Prompt Shields documentation
• NCSC prompt-injection guidance
• NIST adversarial machine learning taxonomy