secretguard-mcp

secretguard-mcp

コード文字列をスキャンしてハードコードされたシークレットを検出する MCP（Model Context Protocol）サーバーです。対象には、AWS キー、Stripe キー、GitHub トークン、Google API キーと OAuth クライアントシークレット、Slack トークンと受信 Webhook URL、Shopify アクセストークン、Telegram ボットトークン、DigitalOcean トークン、Hugging Face トークン、Notion API トークン、Mailchimp API キー、Postman API トークン、Linear API キー、Readme API キー、Clojars API トークン、Pulumi API トークン、OpenAI キー、Anthropic キー、npm アクセストークン、SendGrid キー、Twilio API キー、Azure Storage アカウントキー、パスワードが埋め込まれたデータベース接続文字列、秘密鍵ブロック、JWT、汎用的な高エントロピー認証情報が含まれます。AI コーディングエージェント（Claude Code、Cursor、Windsurf など）が、ファイルを書き込んだりコミットしたりする前にシークレットを検出できるため、CI や PR レビューの段階で初めて発見する事態を防ぎます。公開するツールは scan_for_secrets の1つだけです。stdio 経由で完全にローカル実行され、API キーは不要で、生のシークレット値は決して返しません。検出結果はすべて秘匿化されます。

このプロジェクトの目的

secret-scan-action は、すでに CI で各 PR のシークレットを検出しています。これは必要ですが、検出のタイミングが遅すぎます。実行される頃には、シークレットはすでに書き込まれ、コミットされ、プッシュされています。このプロジェクトでは、同じ検出エンジン（同じルール、同じエントロピーチェック、同じ秘匿化）を再利用し、それをツール呼び出しとしてエージェントの前段に配置します。これにより、生成時にチェックを行い、シークレットがディスクや履歴に残る前に検出できます。

機能

scan_for_secrets を呼び出すと、次の処理を行います。

1. 入力された code 文字列を行ごとに分割します。
2. secret-scan-action と同じ2段階のルールセットを実行します。
   • パターンルール（高信頼度） — 一致した場合、ほぼ確実にシークレットと見なせる特徴的な形式です。AWS アクセスキー ID（AKIA...）とコンテキストに応じたシークレットキー、Stripe のライブキー（sk_live_、rk_live_）、GitHub トークン（ghp_、gho_、github_pat_ など）、Google API キー（AIza...）、Google OAuth クライアントシークレット（GOCSPX-...）、Slack トークン（xox[baprs]-...）、Slack の受信 Webhook URL（hooks.slack.com/services/...）、Shopify アクセストークン（shpat_...、shpca_...、shpss_...、shppa_...、shpua_...）、Telegram ボットトークン（<bot_id>:A...、35文字のシークレット）、DigitalOcean トークン（dop_v1_...、doo_v1_...、dor_v1_...、64文字の16進数）、Hugging Face トークン（hf_...、api_org_...、34文字の英字）、Notion API トークン（ntn_...、11桁の数字＋35文字の英数字）、OpenAI キー（sk-...、sk-proj-...、sk-svcacct-...）、Anthropic キー（sk-ant-...）、npm アクセストークン（npm_...）、SendGrid キー（SG....）、Twilio API キー（SK...）、Azure Storage アカウントキー（コンテキストに応じた AccountKey=...）、秘密鍵ブロック（-----BEGIN ... PRIVATE KEY-----）、JWT が対象です。パターンルールのうち、パスワードが埋め込まれたデータベース接続文字列（postgres://、mysql://、mongodb(+srv)://、redis(s)://、amqp(s)://）は、既知のプレースホルダーパスワード（user、password、changeit など）や ${...} 形式の環境変数参照を除外した後でも、意図的に「ほぼ確実」とは判定しません。実際の値であっても、有効な認証情報ではなく、リスクの低いチュートリアルの例である可能性があるためです。このルールは、以下のエントロピールールと同じ一般信頼度で返されます。もう1つのパターンルールである Mailchimp API キー（32文字の16進数値の後に -usNN データセンター接尾辞が続く形式）も、一般信頼度です。値の直前に mailchimp で始まる変数名またはキー名がある場合のみ検出しますが、このキーワードによる制限だけでは、たまたま同じ接尾辞の形式に一致した無関係な16進数値を除外できないためです。Postman API トークン（PMAK-...、24文字の16進数＋-＋34文字の16進数）、Linear API キー（lin_api_...、40文字の英数字）、Readme API キー（rdme_...、70文字の小文字英数字）、Clojars API トークン（CLOJARS_...、大文字小文字を区別しない60文字の英数字）、Pulumi API トークン（pul-...、40文字の小文字の16進数）は、固定のプレフィックスと正確な長さを持つため、他のプロバイダートークンルールと同様に高信頼度です。
   • 一般エントロピールール — secret、token、password／credential などの名前が付いた変数、または実際のシークレットによく使われる apiKey、sessionKey、signingKey、clientKey、webhookKey などの複合 *key 名の変数に代入された値が、高いシャノンエントロピーを持つ（ランダムに見え、プレースホルダーや環境変数参照のようには見えない）場合に検出します。単独の *Key には意図的に一致させません。一致させると、通常のコードで一般的な partitionKey、cacheKey、queryKey など、シークレットではない識別子も検出してしまうためです。
3. 検出結果ごとに、filename、line、ruleId、description、confidence（"high" | "generic"）、および秘匿化された行を返します。生のシークレット値がプロセス外に出ることはありません。何も見つからなかった場合は、プレーンな "No secrets detected." という結果を返します。

出力例

scan_for_secrets を次の内容で呼び出すと、

{
  "code": "const key = \"AKIAIOSFODNN7EXAMPLE\";\nconst greeting = \"hello\";",
  "filename": "src/config.ts"
}

次の結果が返されます。

{
  "findings": [
    {
      "filename": "src/config.ts",
      "line": 1,
      "ruleId": "aws-access-key-id",
      "description": "AWS Access Key ID",
      "confidence": "high",
      "redactedLine": "const key = \"AKIA************MPLE\";"
    }
  ],
  "summary": "Found 1 potential secret (1 high-confidence, 0 needs-review).\n\n- [high] src/config.ts:1 — AWS Access Key ID (aws-access-key-id)\n  const key = \"AKIA************MPLE\";"
}

（上記の AWS キーは AWS 自身の公開ドキュメントにあるプレースホルダーであり、有効な認証情報ではありません。）問題のないスキャンでは、たとえば { "code": "const greeting = \"hello world\";" } に対して { "findings": [], "summary": "No secrets detected." } が返されます。

セットアップ

npm レジストリにはまだ公開されていないため、npx を使って GitHub から直接インストールしてください。Git ソースから npm install を実行すると、このパッケージの prepare スクリプトが自動的に実行され、その場で dist/ がビルドされるため、別途ビルドする必要はありません。

Claude Code

プロジェクトの .mcp.json に追加するか、claude mcp add を実行してください。

{
  "mcpServers": {
    "secretguard": {
      "command": "npx",
      "args": ["-y", "github:vladimirbakalov/secretguard-mcp"]
    }
  }
}

Claude Desktop

claude_desktop_config.json に追加してください。

{
  "mcpServers": {
    "secretguard": {
      "command": "npx",
      "args": ["-y", "github:vladimirbakalov/secretguard-mcp"]
    }
  }
}

API キーもアカウントも設定オプションも不要です。Claude Code／Claude Desktop を再起動すると、scan_for_secrets が利用可能になります。ツールの説明では、認証情報を含む可能性のあるコードを書く前と、コミットまたは PR の前に、エージェントがこのツールを呼び出すよう指示しています。ほとんどの場合、明示的に呼び出すよう頼む必要はありません。

Cursor／Windsurf

どちらも、それぞれの MCP 設定 UI または設定ファイルから同じ command／args の形式を読み込みます。同じように npx -y github:vladimirbakalov/secretguard-mcp を指定してください。

このパッケージが npm に公開されたら、上記の args は ["-y", "secretguard-mcp"] に変更できます。これは今後の対応事項であり、現時点での利用を妨げるものではありません。

ワンクリックインストール（.mcpb）

ビルド済みの MCP Bundle が v0.1.4-mcpb リリースに添付されています。secretguard-mcp-0.1.4.mcpb をダウンロードして Claude Desktop（またはほかの MCPB 対応クライアント）で開くと、クライアント側で npx／Node をセットアップする必要なく、ワンクリックでローカルにインストールできます。npm run package:mcpb を実行して自分で再ビルドすることもできます（scripts/build-mcpb.sh を参照）。

この .mcpb リリースアセットは、リポジトリのルートにある server.json が公式 MCP Registry用に参照しているものでもあります。secretguard-mcp は io.github.vladimirbakalov/secretguard-mcpとして公開・掲載されているため、公式レジストリを参照する MCP クライアントは、上記の npx／.mcpb に加えて、直接見つけてインストールできます。公開は、v*-mcpb タグのプッシュごとに mcp-publisher login github-oidc を使い、CI（.github/workflows/publish-mcp.yml）で無人実行されます。対話的なログイン手順は不要です。

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

• ルールによって一致した生のシークレット値は、1 回の scan_for_secrets 呼び出し中のみメモリ上に保持され、ツールの結果を構築する前に伏字化されます（redactLine／redactSecret）。返される content、structuredContent、ログ行のいずれにも表示されることはありません。
• サーバーは、いかなる種類のネットワーク呼び出しも行いません。標準入力を読み取り、標準出力（MCP stdio トランスポート）に書き込み、それ以外は何もしません。
• 汎用ティアの検出結果は、性質上あいまいです（設定のプレースホルダー、ハッシュ、UUID がエントロピー検査に引っかかることがあります）。これは想定された動作です。confidence: "generic" は「確認が必要」と捉え、「確認済み」とは捉えないでください。

開発

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest run
npm run build       # tsc -p tsconfig.build.json -> dist/

dist/ はコミットされません。prepare スクリプトを使って src/ からビルドされます。このスクリプトは、Git ベースの npx／npm install の実行時と、今後 npm publish を行う前の両方で実行されます。

対象範囲（v1）

ツールは 1 つ、役割も 1 つです。コード文字列をスキャンし、伏字化した検出結果を返します。許可リストファイル、AI によるトリアージ手順、設定オプション、永続状態はありません。将来そのいずれかが必要になった場合は、実際の使用状況から必要性が確認されてから追加します。先回りして追加することはありません。

secret-scan-action との関係

secretguard-mcp と secret-scan-actionは、同じ検出エンジン（rules.ts、redact.ts、および scan.ts の中核部分）を共有していますが、独立して個別に配布されるパッケージです。一方は CI で PR の差分をスキャンする GitHub Action、もう一方はコミット作成前にローカルで任意のコード文字列をスキャンする MCP サーバーです。ルールセットの誤検知または検出漏れを修正するには、両方を更新する必要があります。

ライセンス

MIT。