Hook: MCP Security Scanner

Script: mcp-security-scan.sh

Purpose: This hook acts as a security gateway, scanning all requests to MCP servers to prevent the accidental exposure of secrets, API keys, and other sensitive data.

Trigger: It runs on the PreToolUse event for any tool matching mcp__.*, meaning it protects all calls to external MCP servers.

Features

  • Pattern-Based Detection: It uses a configurable list of patterns to detect credentials, API keys (including formats for common services like OpenAI, AWS, and Google), and private keys.
  • Comprehensive Scanning: It scans the code_context, problem_description, and the content of any attached_files in the MCP request.
  • Configurable: The detection logic is controlled by a JSON file, allowing you to customize it for your project's needs.
  • Whitelisting: It supports a whitelist to prevent false positives for placeholder values like YOUR_API_KEY.
  • Blocking Behavior: If a secret is detected, the hook exits with a special code that blocks the MCP request from being sent and provides a clear error message to the user.
  • Logging: All scan events (started, completed, blocked) are logged to .claude/logs/security-scan.log for auditing.

Configuration

The scanner's behavior is controlled by .claude/hooks/config/sensitive-patterns.json. You can edit this file to:

  • Add new regex patterns for custom secret formats.
  • Add new filename patterns to the sensitive_files list.
  • Add new placeholder values to the whitelist to avoid flagging them.

Here is a snippet of the default configuration:

{
  "patterns": {
    "credentials": [
      "password\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?",
      "secret\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?",
      "api[_-]?key\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?"
    ],
    "sensitive_files": [
      ".env",
      "credentials.json",
      "private.key"
    ],
    "regex_patterns": [
      "sk-[a-zA-Z0-9]{32,}",
      "AIza[0-9A-Za-z\\-_]{35}",
      "-----BEGIN.*PRIVATE KEY-----"
    ]
  },
  "whitelist": {
    "allowed_mentions": [
      "API_KEY=<your_api_key>",
      "password=your_password_here"
    ]
  }
}