leakferret

MCP ネイティブのシークレットスキャナー — 検証済みの検出結果と、エージェントによる書き換え。

leakferret は、高速な Rust バイナリひとつで、エンジン、CLI、MCP サーバーとして動作します。コード内のハードコードされたシークレットを見つけ、プロバイダーに問い合わせて実際に有効なものを確認し、漏えいした値を環境変数から読み込むよう、その場で書き換えます。ターミナルや CI で実行できるほか、コーディングエージェントがコミット前に呼び出すツールとしても使えます。生のシークレットがマシンの外に出ることはありません。

---

実際の動作

本物のキーを誤ってコミットしてしまった場合に、よくあるノイズも一緒に含まれているとします。

# .env  — every key below is fabricated for this example
STRIPE_SECRET_KEY=sk_live_FAKE_example_not_a_real_key   # fabricated
GITHUB_TOKEN=ghp_FAKE_example_not_a_real_token          # fabricated
SENDGRID_API_KEY=${SENDGRID_API_KEY}                    # a reference — not a leak
ADMIN_PASSWORD=changeme                                 # a placeholder — not a leak
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE                  # AWS's public docs example

leakferret verify は各プロバイダーに問い合わせて、実際に有効なキーを報告し、それ以外については何も表示しません。

$ leakferret verify .
.env
  L2  UNKNOWN    CRITICAL  stripe_secret   sk_l..._key
  L3  VERIFIED   CRITICAL  github_token    ghp_...oken   ← live, rotate it now

2 findings · 1 verified · 1 unknown

_{上記のキーはすべて架空のものです。そのため、VERIFIED の行は実際に有効なキーがどのように報告されるかを示す例です。ここにある例では、どちらも UNKNOWN になります。}

${SENDGRID_API_KEY} の参照、changeme というプレースホルダー、よく知られた AKIAIOSFODNN7EXAMPLE の例は認識され、対象から除外されます。この精度こそが重要です。その後、leakferret rewrite --apply を実行すると、コード内のハードコードされたキーを書き換えます（.env ファイルはそのままです。シークレットの書き換え先として、そこに適切なものはないためです）。

  # app/billing.rb  (fabricated example)
- Stripe.api_key = "sk_live_FAKE_example_not_a_real_key"   # fabricated
+ Stripe.api_key = ENV.fetch("STRIPE_API_KEY")

…さらに、シークレットマネージャー用のシードコマンドとともに、.env.example に STRIPE_API_KEY= を追記します。検出 → 有効性の確認 → 修正を、ほとんど誤検出なく実現します。

シークレットの完全な値がマシンの外に出ることはありません。レポート、ログ、ネットワークメッセージに記録されるのは、マスキングされた AKIA...4XYZ のプレビューだけです。

---

クイックスタート

お好みの方法でインストールしてください。どのパッケージにも、同じビルド済みバイナリが含まれています。

# Ruby gem
gem install leakferret

# npm (CLI)
npm i -g @leakferret/cli

# Go
go install github.com/leakferrethq/leakferret-go/cmd/leakferret@latest

# Native binary — download from GitHub Releases, unpack, and put it on $PATH:
#   https://github.com/leakferrethq/leakferret/releases

# Rust, from source
cargo install leakferret-cli

次に、現在のディレクトリをスキャンします。

leakferret scan .

scan は .gitignore を尊重し、.env などのドットファイルも読み込みます。作業ツリーではなくコミット履歴を確認するには、--git を追加してください。

すべてのラッパーは、オフライン利用や開発用途向けに、ローカルのバイナリを指定する LEAKFERRET_BIN 環境変数に対応しています。

---

仕組み

leakferret は、検出結果を5段階のパイプラインで処理します。各段階では必要な情報だけを扱い、生のシークレットがディスクを越えて先に進むことはありません。

1. スキャン — ファイルに対して高速な正規表現による事前フィルターを実行し、60 種類以上のシークレットを検出します。.gitignore を尊重し、.env などのドットファイルを読み込み、--git を指定すると履歴も調べます。
2. カタログ照合 — 候補を、署名付きの既知の公開サンプル認証情報データベースと照合します。Stripe のテストキー、AKIAIOSFODNN7EXAMPLE、jwt.io のサンプル、RFC の例などが含まれます。一致したものには FIXTURE のマークを付け、ドキュメントに記載された例で誤検出が起きないようにします。カタログはバイナリに同梱されており、更新と署名検証が可能です。
3. 分類 — 残った各候補を REAL、FIXTURE、UNKNOWN のいずれかに判定します。既定ではオフラインで実行され（パスのルールとダミーマーカーのヒューリスティックを使用）、またはホストエディターやエージェント自身の言語モデルに判定を求めます。追加の API キーは不要で、追加料金もかかりません。
4. 検証 — プロバイダーに無害な API 呼び出しを1回行い、キーが LIVE かどうかを確認します。約 25 のプロバイダーにネイティブ対応しています（AWS SigV4、GitHub、GitLab、Stripe、OpenAI、Anthropic、Slack、Twilio、SendGrid、Mailgun、Datadog、Heroku、npm、PyPI、DigitalOcean、Hugging Face、Groq、Replicate、Notion、Postman、Figma、Linear、Square、Shopify、Databricks）。それ以外は trufflehog バイナリにフォールバックします。呼び出しはお使いのマシンからプロバイダーに直接送信され、leakferret のサーバーを経由することはありません。
5. 書き換え — ハードコードされたリテラルを環境変数の参照（ENV.fetch / os.environ / process.env）に置き換え、.env.example に1行を追加し、シークレットマネージャー（env、Vault、Doppler、AWS Secrets Manager、Infisical）向けのシードコマンドを表示します。

ベースラインには、既知の検出結果の一方向 HMAC フィンガープリントが保存されます。生のシークレットは保存されないため、CI で新たな漏えいがあった場合にのみ失敗させることができます。

---

AI エージェントで使用する（MCP）

MCP（Model Context Protocol）は、コーディングエージェントにツールを提供するためのオープン標準です。エージェントもシークレットをハードコードすることがあり、変更差分を1行ずつレビューする人はいません。leakferret を使うと、エージェントはコミット前に自らチェックできます。

stdio 上で JSON-RPC を使用してサーバーを起動します。

npx @leakferret/mcp

mcpServers 設定に追加します（Claude Desktop、Cursor、Continue、Claude Code）。

{
  "mcpServers": {
    "leakferret": {
      "command": "npx",
      "args": ["@leakferret/mcp"]
    }
  }
}

Claude Code の場合、このブロックをプロジェクトルートの .mcp.json として保存するか、次のコマンドで追加します。

claude mcp add leakferret -- npx -y @leakferret/mcp

ネイティブバイナリをインストールした場合は、代わりにそのパスを直接指定できます。

{
  "mcpServers": {
    "leakferret": {
      "command": "leakferret",
      "args": ["mcp"]
    }
  }
}

leakferret は MCP Registry にも io.github.leakferrethq/leakferret として登録されているため、レジストリに対応したクライアントから検出できます。

公開されるツールは scan_repository、classify_candidates、verify_finding、propose_rewrite、baseline_diff です。また、エージェントが既存のモデルを使って候補をその場で分類できるよう、classify プロンプトも用意されています。読み取り専用リソースを2つ公開しており、エンジンのカタログをコンテキストとして利用できます。leakferret://secret-types（検出可能なすべてのパターン）と leakferret://verifiers（ライブ検証に対応するプロバイダー）です。

---

比較

	gitleaks	trufflehog	detect-secrets	GitGuardian	leakferret
プロバイダーのリアルタイム検証	—	✓	—	✓	✓
環境変数へのインプレース書き換え	—	—	—	—	✓
AI エージェント向け MCP サーバー	—	—	—	—	✓
ベースライン（新しい検出結果のみ失敗）	—	—	✓	✓	✓
SARIF／コードスキャン	✓	✓	—	✓	✓
無料、ローカルで利用可能、アカウント不要	✓	✓	✓	—	✓

gitleaks は、コミット前に正規表現でブロックする最速のツールです。trufflehog はリアルタイム検証の基準を打ち立てました。detect-secrets は、レガシーリポジトリでベースラインを設定するワークフローに特化しています。GitGuardian は、最も幅広い検出機能とダッシュボードを備えた有料プラットフォームです。leakferret は、正規表現による事前フィルタリングを行い、キーが有効かどうかを検証して、漏洩した値を環境変数に書き換えます。また、コーディングエージェントが自身の差分をチェックできるよう、MCP サーバーとして動作します。詳細： leakferret.com/compare。

---

CLI リファレンス

leakferret scan      Regex pre-filter only (no classifier, no verifier)
leakferret verify    Scan + classify + provider verification
leakferret rewrite   Scan + classify + propose/apply ENV-fetch rewrites
leakferret org       Scan every public repo owned by a GitHub user/org
leakferret baseline  Manage the per-repo fingerprint baseline
leakferret catalog   Load and inspect the fixture catalog
leakferret mcp       Start the MCP server on stdio

GitHub のアカウントまたは組織全体を一度にスキャンします（誰かに見つけられる前に、公開リポジトリ全体の漏洩を見つけるのに便利です）。

leakferret org leakferrethq            # all public repos for that owner
leakferret org myco --token "$GITHUB_TOKEN" --format sarif > leaks.sarif

よく使うフラグ：

# scan
leakferret scan .                              # working tree
leakferret scan . --git                        # scan HEAD's commit history
leakferret scan . --git --all                  # scan every branch / tag
leakferret scan . --git --since HEAD~50        # bounded history window

# verify
leakferret verify .                            # best-effort verification
leakferret verify . --verify-mode none --fail-on any  # offline gate: exit 1 on any finding
leakferret verify . --only-verified            # emit only confirmed-live keys
leakferret verify . --verify-mode ever-verified  # fail on historical leaks
leakferret verify . --verifier-timeout-secs 10

# rewrite
leakferret rewrite . --apply                   # write ENV.fetch in place
leakferret rewrite . --dry-run-diff            # show the diff, touch nothing
leakferret rewrite . --check                   # CI mode: exit 1 if rewrites pending
leakferret rewrite . --apply --include-unknown # also fix UNKNOWN (unconfirmed) candidates
leakferret rewrite . --backend doppler         # seed cmds for your manager

# baseline  (scan/verify are read-only — they never write to your repo)
leakferret baseline init                       # create .leakferret-baseline.json (gitignores the salt)
leakferret verify . --update-baseline          # record current findings into the baseline
leakferret baseline show
leakferret baseline ignore --fingerprint <fp>  # acknowledge a finding

# catalog
leakferret catalog info
leakferret catalog test "sk_test_4eC39..."     # deterministic FIXTURE verdict
leakferret catalog refresh                      # fetch + signature-verify update

scan／verify／rewrite で共通のフラグ：--format、--show-fixtures、 --exclude <glob>、--only <path>、--only-verified、 --fail-on <none|any|real|verified>。 --backend には、env、vault、doppler、aws-secrets-manager、 infisical を指定できます。

---

ローカルでコミットをブロックする（pre-commit フック）

シークレットがコミットされる前に検出します。リポジトリのルートから実行します。

cat > .git/hooks/pre-commit <<'HOOK'
#!/bin/sh
# Offline secret scan (no network). Blocks the commit on any finding.
leakferret verify . --verify-mode none --fail-on any || {
  echo "leakferret blocked this commit. Bypass: git commit --no-verify"
  exit 1
}
HOOK
chmod +x .git/hooks/pre-commit

--verify-mode none を指定すると、完全にオフラインで動作します。--fail-on any は、フィクスチャ以外の検出結果があれば、終了コード 0 以外で終了します（AKIAIOSFODNN7EXAMPLE のような、ドキュメントに記載されている例は引き続き無視されます）。leakferret baseline init と組み合わせると、このフックは新しいシークレットのみをブロックします。チームでフックを共有するには、.githooks/ にコミットし、git config core.hooksPath .githooks を一度実行します。

このフックは、ターミナル、GitHub Desktop、VS Code のソース管理パネル、JetBrains など、どの Git クライアントでも実行されます。いずれも Git の pre-commit フックを実行するためです。コミットがブロックされると、そのクライアントの「コミットに失敗しました」ダイアログに leakferret の出力が表示されます。

pre-commit フックはローカルでの利便性を高めるものであり、完全な防壁ではありません。 誰でも、または AI エージェントでも、git commit --no-verify でフックをスキップでき、Git にはローカルでそれを禁止する方法がありません。そのため、フックは迅速なフィードバック手段として扱い、GitHub Action（または CI の同じ leakferret verify ステップ）を強制ゲートとして使用してください。これはプッシュとプルリクエストのたびにサーバー側で実行されるため、--no-verify では回避できません。

---

出力形式

--format で選択します。

• pretty — 色付きのターミナル出力（デフォルト）。
• json — スクリプトやパイプラインで使える、構造化された検出結果。
• sarif — GitHub コードスキャン向け。GitHub Action ラッパー （leakferrethq/leakferret-action@v1）がアップロードします。

---

プライバシーの保証

これは信頼性に関する取り組みであり、専用のテストで徹底しています。

シークレットの完全な値は、ディスク上にのみ保存されます。レポート、 ログ、ネットワークメッセージ、モデルプロンプトに書き込まれることは 決してありません。プロセス外に送信されるのは、先頭4文字と末尾4文字 のみを表示するプレビュー（例：AKIA...4XYZ）です。

検証では、キーをお使いのマシンからプロバイダーへ直接送信します。 leakferret にサーバーはなく、データも収集しません。ベースラインには一方向の HMAC フィンガープリントのみが保存され、生のシークレットは保存されません。

verify の運用上の注意点が1つあります。 検証では候補ごとに実際の認証済みリクエストを送信するため、キーの所有者自身の監査ログに記録されます。AWS STS の GetCallerIdentity は CloudTrail に記録され、GitHub トークンのチェックはトークンの使用として記録されます。verify は、テスト対象のシークレットがご自身のものであるリポジトリにのみ使用してください。他者のコードに対して実行すると、その人のアカウントに認証を行い、痕跡を残すことになります。ネットワーク呼び出しを一切行わずにスキャンするには、verify の代わりに leakferret scan を使用するか、--verify-mode none を渡してください。

---

比較

• gitleaks は高速な正規表現スキャナーです。leakferret はこの事前フィルターに対応し、プロバイダー検証を追加するため、正規表現によるノイズのトリアージではなく、有効なキーに対処できます。
• trufflehog はシークレットをプロバイダーに対して検証します。leakferret も同様の機能を備え、さらに、競合製品にはない MCP／エージェント層と、エージェントが適用する書き換え機能を追加しています。また、署名済みのフィクスチャカタログにより、公開済みのサンプルキーが有効なものとして報告されるのを防ぎます。

---

プラットフォーム

v0.1.6 向けのビルド済みバイナリ：

• x86_64-unknown-linux-gnu
• x86_64-apple-darwin
• aarch64-apple-darwin
• x86_64-pc-windows-msvc
• aarch64-pc-windows-msvc

---

バイナリの検証

すべてのリリース用 tarball は、Sigstore／cosign で署名されています。GitHub OIDC を使用したキーレス署名で、対応する *.cosign.bundle が同梱されています。ダウンロードしたファイルがこのリポジトリのリリースワークフローでビルドされ、改ざんされていないことを証明できます。

cosign verify-blob \
  --bundle leakferret-0.1.6-x86_64-unknown-linux-gnu.tar.gz.cosign.bundle \
  --certificate-identity-regexp 'https://github.com/leakferrethq/leakferret/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  leakferret-0.1.6-x86_64-unknown-linux-gnu.tar.gz

各 tarball には、基本的な整合性チェック用の .sha256 も同梱されています。

---

リンク

• ウェブサイト：https://leakferret.com
• ソース：https://github.com/leakferrethq/leakferret
• カタログデータ：https://github.com/leakferrethq/leakferret-catalog
• ラッパー：ruby · go · npm · action · vscode
• メンテナー：Maria Khan <[email protected]>

ライセンス

エンジン、CLI、MCP サーバー、およびすべての言語ラッパーには MIT ライセンスが適用されます。 フィクスチャカタログデータには CC-BY-SA-4.0 が適用されます。

trufflehog は、leakferret がフォールバック検証のために別プロセスとして呼び出す、ユーザーが任意でインストールする AGPL-3.0 ツールです。同梱、変更、再配布はされません。NOTICE を参照してください。