secret-scanner

@guardbee/mcp-secret-scanner

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

ソースファイル、ディレクトリ、環境設定ファイルをスキャンし、公開状態の API キー、パスワード、トークンなどのシークレットを検出する MCP サーバーです。プロジェクトからシークレットが漏洩していないか、Claude に直接確認できます。

テレメトリーはデフォルトでオフです。GUARDBEE_TELEMETRY=1 を設定すると、サーバー、ツール、成功状態、所要時間、ファイルパスなどの短いパラメーター値が送信されます。長い文字列や content、token、password などのフィールドはプレースホルダーに置き換えられます。詳細は @guardbee/mcp-telemetry をご覧ください。

---

機能

• 76 種類のシークレットパターン — AWS、Azure、GCP、GitHub、GitLab、Stripe、OpenAI、Anthropic、OpenRouter、Groq、Hugging Face、Slack、Twilio、SendGrid、DigitalOcean、Cloudflare、Supabase、Vault、PyPI、Shopify、Linear、Notion、Atlassian などに対応しています。さらに、キーにプレフィックスがないため変数名で照合する、トルコのプロバイダー iyzico、PayTR、Netgsm、İleti Merkezi にも対応しています。ルールは @guardbee/guard-core にあり、@guardbee/mcp-security-proxy は実行時にツールの結果内にある同じ形式をマスクします
• ファイルとディレクトリのスキャン — 単一ファイルまたはプロジェクトツリー全体をスキャンします
• Git 履歴とステージ済みファイルのスキャン — --history は、コミットで追加されたすべての行をスキャンします。そのため、ファイルから削除されていてもリポジトリに残っているキーを検出し、追加したコミットの場所で（作成者と日付を含めて）1 回だけ報告します。--staged は、これからコミットする内容だけをスキャンします
• ベースライン — --write-baseline は、今日の検出結果をハッシュとして記録します（シークレット自体は記録しないため、安全にコミットできます）。その後、--baseline は新しい検出結果だけを報告するため、既存のリポジトリでも、最初にすべてを修正することなく CI でスキャナーを導入できます。SARIF の結果には、安定した partialFingerprints 値が含まれます
• 高エントロピー値 — シークレットらしい名前に割り当てられた、ランダムに見える値（.env 内の WEBHOOK_SIGNING_SECRET=…、YAML 内の client_secret:、JSON 内の "internalApiKey" など）は、プロバイダーのルールで形式が認識されなくても報告されます。ランダム性はシャノンエントロピーで測定されます（16 進数値は 32 文字以上が必要です。数字を含まない値は、より多くのビット数が必要なため、キャメルケースのパスフレーズは該当しません）。public／publishable、*_hash、*_id、*_url という名前、プレースホルダー、${VAR} 参照は対象外です。また、プロバイダーのルールですでに報告された値は重複して報告されません。重大度は中程度で、テストファイルでは低くなります。--no-entropy（または MCP ツールの entropy: false）で無効にできます
• エージェントのトランスクリプト — scan --agent-history（MCP：scan_agent_history）は、コーディングエージェントがマシン上に保存するデータをスキャンします。対象は Claude Code（~/.claude/projects、~/.claude.json）、Codex（~/.codex）、Gemini CLI（~/.gemini/tmp）、Continue（~/.continue/sessions）です。チャットに貼り付けたキーや、エージェントが実行したコマンドによって出力されたキーはそこに残ります。また、すでにモデルプロバイダーに送信されているため、ローテーションしてください。各シークレットはエージェントごとに 1 回だけ報告され、出現回数も示されます。トランスクリプトにはエージェントが読み取ったコードが大量に含まれるため、--entropy を指定しない限り、ここではエントロピーチェックは無効です
• 長い行を含むファイル — 1 MB を超える .jsonl、.ndjson、.ipynb、.log ファイル（トランスクリプト、出力を含むノートブック、ログ）は、スキップせずに 1 行ずつ読み取ります
• ライブ検証（CLI のみ） — --verify は、読み取り専用の ID エンドポイント（GitHub の /user、OpenAI の /models、Slack の auth.test など）を通じて、検出したキーがまだ有効かどうかを各プロバイダーに問い合わせます。対象は GitHub、GitLab、OpenAI、Anthropic、Slack、Stripe、Hugging Face、npm、SendGrid、Groq、OpenRouter、DigitalOcean です。各キーは対応するプロバイダーにのみ 1 回送信され、出力には表示されません。検出結果には live／invalid／unknown のいずれかが付き、有効なものが最初に表示されます。--fail-on=live を指定すると、まだ有効なキーがある場合にのみ CI が失敗します。MCP ツールでは検証を行わないため、エージェントが独自にシークレットを外部へ送信することはありません
• スマートスキップ — node_modules、.git、dist、build、.next などのディレクトリは自動的にスキップされます
• 安全なマスキング — 一致した値は、先頭 4 文字と末尾 4 文字を残して、間をアスタリスクで表示します
• 許可リストのサポート — 既知のテスト用／偽の値を許可リストに登録できます
• 71 件のユニットテスト — テストスイートは 100% 合格しています

---

クイックスタート

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

claude_desktop_config.json に追加します：

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

---

MCP ツール

ツール	説明
scan_text	指定されたテキストをスキャンしてシークレットを検出します
scan_file	単一のファイルをスキャンします
scan_directory	ディレクトリとそのサブディレクトリを再帰的にスキャンします
scan_git	git リポジトリのステージ済み変更、または各コミットで追加された行（履歴）をスキャンします
scan_agent_history	このマシン上のコーディングエージェントのトランスクリプト（Claude Code、Codex、Gemini CLI、Continue）をスキャンします
list_patterns	有効なシークレットパターンをすべて一覧表示します

使用例

Claude に次のように依頼できます。

「プロジェクト /Users/me/my-app からシークレットをスキャンしてください」

「この .env ファイルにシークレットはありますか？」

「このテキストは安全ですか：export API_KEY=sk-abc123...」

---

検出されるシークレットの種類

カテゴリ	例
クラウド	AWS アクセスキー、AWS シークレット、GCP API キー
ソース管理	GitHub PAT、GitLab トークン
決済	Stripe シークレットキー／公開可能キー
AI	OpenAI API キー、Anthropic API キー、HuggingFace トークン
コミュニケーション	Slack ボットトークン、Twilio 認証トークン、SendGrid キー
データベース	PostgreSQL URL、MySQL URL、MongoDB URI、Redis URL
暗号	RSA 秘密鍵、EC 秘密鍵、OpenSSH キー、PGP キー
Web	JWT トークン、ベアラートークン
パッケージ／プラットフォーム	npm トークン、Docker Hub トークン、Vercel トークン
汎用	SECRET=、PASSWORD=、API_KEY= のパターン

---

セキュリティに関する注意

このツールは、スキャン結果に含まれる一致した値を部分的にマスキングします（例：sk_live_abc1...xyz9）。完全な値が記録またはエクスポートされることはありません。

---

CLI — CI/CD 統合

MCP サーバーモードに加えて、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
# Secrets pasted into Claude Code / Codex / Gemini CLI / Continue sessions on this machine
npx @guardbee/mcp-secret-scanner scan --agent-history
# Which of the found keys still work? (sends each key to its own provider)
npx @guardbee/mcp-secret-scanner scan . --history --verify --fail-on=live
# 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

終了コード： 0 = シークレットなし · 1 = シークレットを検出 · 2 = エラー

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 フック

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

---

開発

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

---

ライセンス

MIT — GuardBee

フィードバック

質問、アイデア、または誤検知がありましたら、GitHub Discussions でスレッドを開始するか、issue を作成してください。GuardBee が役に立った場合は、リポジトリに ⭐ を付けていただくと、ほかの人にも見つけてもらいやすくなります。