@guardbee/mcp-secret-scanner

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文

An MCP server that scans your source files, directories, and environment configs for exposed API keys, passwords, tokens, and other secrets. Ask Claude directly whether your project is leaking secrets.

This package sends usage telemetry by default (tool name + short parameters like a file path — the scanned file content is never included, see @guardbee/mcp-telemetry). Disable with GUARDBEE_TELEMETRY=0.

Features

• 38 Secret Patterns — AWS, GitHub, GitLab, Stripe, OpenAI, Anthropic, HuggingFace, Slack, Twilio, SendGrid, and more. The rules live in @guardbee/guard-core, so @guardbee/mcp-security-proxy masks the same formats in tool results at runtime
• File & Directory Scanning — a single file or an entire project tree
• Git History & Staged Scanning — --history scans every line any commit added, so a key deleted from the files but still in the repository is found, reported once at the commit that added it (with author and date); --staged scans only what you are about to commit
• Baseline — --write-baseline records today's findings as hashes (never the secrets, safe to commit); --baseline then reports only new ones, so an existing repo can adopt the scanner in CI without fixing everything first. SARIF results carry a stable partialFingerprints value
• Smart Skipping — directories like node_modules, .git, dist, build, .next are skipped automatically
• Safe Redaction — matches are shown as first 4 + stars + last 4 characters
• Allowlist Support — allowlist known test/fake values
• 49 Unit Tests — 100% passing test suite

Quick Start

npm install -g @guardbee/mcp-secret-scanner

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "guardbee-secret-scanner": {
      "command": "npx",
      "args": ["-y", "@guardbee/mcp-secret-scanner"]
    }
  }
}

MCP Tools

Example Usage

You can ask Claude:

"Scan my project for secrets: /Users/me/my-app"

"Are there any secrets in this .env file?"

"Is this text safe: export API_KEY=sk-abc123..."

Detected Secret Types

Security Note

This tool partially redacts matched values in scan results (e.g. sk_live_abc1...xyz9). Full values are never logged or exported.

CLI — CI/CD Integration

In addition to MCP server mode, this can also be used directly as a CLI:

# Scan a project directory
npx @guardbee/mcp-secret-scanner scan ./my-project

# Scan a single file
npx @guardbee/mcp-secret-scanner scan .env

# Fail only on critical/high
npx @guardbee/mcp-secret-scanner scan . --fail-on=high

# JSON output (for CI reporting)
npx @guardbee/mcp-secret-scanner scan . --format=json
# Pre-commit: only the lines you are about to commit
npx @guardbee/mcp-secret-scanner scan --staged

# Every commit on every branch (finds keys deleted from the files)
npx @guardbee/mcp-secret-scanner scan . --history
npx @guardbee/mcp-secret-scanner scan . --history=main..HEAD   # just this branch

# Adopt an existing repo: record known findings once, then fail only on new ones
npx @guardbee/mcp-secret-scanner scan . --history --write-baseline=.guardbee-secrets-baseline.json
npx @guardbee/mcp-secret-scanner scan . --history --baseline=.guardbee-secrets-baseline.json

Exit codes: 0 = no secrets found · 1 = secrets found · 2 = error

GitHub Actions

name: Secret Scan
on: [push, pull_request]

jobs:
  secret-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # full history for --history
      - name: Scan for exposed secrets
        run: npx @guardbee/mcp-secret-scanner scan . --history --baseline=.guardbee-secrets-baseline.json --fail-on=high

GitLab CI

secret-scan:
  image: node:20
  script:
    - npx @guardbee/mcp-secret-scanner scan . --fail-on=high
  only:
    - merge_requests
    - main

Pre-commit Hook

# .git/hooks/pre-commit
npx @guardbee/mcp-secret-scanner scan --staged --fail-on=high || exit 1

Development

npm install
npm test          # 49 unit tests
npm run build     # TypeScript compile

License

MIT — GuardBee