leakferret

原生支持 MCP 的机密扫描器——验证发现项，由 Agent 应用重写。

leakferret 是一个快速的 Rust 二进制程序，同时也是引擎、命令行工具和 MCP 服务。它能在代码中发现硬编码的机密，调用提供商确认哪些机密确实有效，并就地重写泄漏内容，改为从环境变量读取。它可在终端、CI 中运行，也可作为编码 Agent 在提交前调用的工具——原始机密绝不会离开你的机器。

---

效果示例

假设你不小心提交了一个真实密钥，以及一些常见的干扰项：

# .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 会将发现的问题依次送入五个环节的流水线。每个环节只会看到自己所需的信息，原始密钥不会离开磁盘。

1. 扫描 — 使用快速正则预筛选器扫描文件，覆盖 60+ 种密钥类型。遵循 .gitignore，读取 .env 等点文件，并可使用 --git 遍历历史记录。
2. 编目 — 使用经过签名的数据库检查每个候选项，其中收录了已知公开的示例凭证：Stripe 测试密钥、AKIAIOSFODNN7EXAMPLE、jwt.io 示例、RFC 示例。匹配项会标记为 FIXTURE，因此文档中的示例不会引发误报。目录随二进制文件一起打包，并且可以刷新和验证签名。
3. 分类 — 为每个剩余候选项给出判定：REAL、FIXTURE 或 UNKNOWN。默认离线运行（使用路径规则和虚假标记启发式规则），也可以调用宿主编辑器或 Agent 自带的大模型，无需额外的 API 密钥，也不会增加成本。
4. 验证 — 向服务提供商发起一次无害的 API 调用，以确认密钥是否为 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 中追加一行，并输出用于密钥管理器的初始化命令（env、Vault、Doppler、AWS Secrets Manager 或 Infisical）。

基线会存储已知发现项的单向 HMAC 指纹，而不会存储原始密钥，这样 CI 就只会因新增泄漏而失败。

---

与 AI Agent 配合使用（MCP）

MCP（Model Context Protocol）是一项用于为编码 Agent 提供工具的开放标准。Agent 也会硬编码密钥，而且没人会逐行审查它们的差异——leakferret 可让 Agent 在提交之前自行检查。

通过 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 提示词，让 Agent 可以使用现有模型直接对候选项进行分类。两个只读资源会将引擎目录作为上下文提供：leakferret://secret-types（所有可检测的模式）和 leakferret://verifiers（实时验证支持的服务提供商）。

---

对比

	gitleaks	trufflehog	detect-secrets	GitGuardian	leakferret
实时验证服务提供商	—	✓	—	✓	✓
就地重写环境变量	—	—	—	—	✓
面向 AI Agent 的 MCP 服务	—	—	—	—	✓
基线（仅对新问题失败）	—	—	✓	✓	✓
SARIF / 代码扫描	✓	✓	—	✓	✓
免费、本地运行、无需账户	✓	✓	✓	—	✓

gitleaks 是速度最快的提交前正则拦截工具。trufflehog 树立了实时验证的标杆。detect-secrets 擅长处理旧代码库的基线工作流。GitGuardian 是一款付费平台，拥有最广泛的检测器和仪表板。leakferret 会先进行正则预筛选，再验证密钥是否有效，将泄露内容重写为环境变量，并以 MCP 服务的形式运行，让编码 Agent 检查自己的差异。完整对比： 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 hook）

在密钥被提交之前将其拦截。在仓库根目录运行：

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 会在发现任何非示例问题时以非零状态码退出（AKIAIOSFODNN7EXAMPLE 等文档中的示例仍会被忽略）。将其与 leakferret baseline init 配合使用，让钩子只拦截新的密钥。若要与团队共享钩子，请将其提交到 .githooks/，并运行一次 git config core.hooksPath .githooks。

该钩子适用于任何 git 客户端——终端、GitHub Desktop、VS Code 源代码管理面板、JetBrains 等——因为它们都会运行 git 的 pre-commit hook。提交被拦截时，该客户端的“提交失败”对话框中会显示 leakferret 的输出。

pre-commit hook 是本地便利措施，不是防护墙。任何人——或任何 AI Agent——都可以通过 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 的一项操作注意事项。 验证会针对每个候选密钥发送真实的身份验证请求，因此会出现在密钥所有者自己的审计日志中——AWS STS 的 GetCallerIdentity 会显示在 CloudTrail 中，GitHub 令牌检查会显示为令牌使用记录，其他服务也一样。请仅对你有权测试其密钥的仓库运行 verify；对他人的代码运行此命令，意味着使用其账户进行身份验证并留下记录。如需完全不发起网络请求地扫描，请使用 leakferret scan，而不是 verify，或传入 --verify-mode none。

---

对比

• gitleaks 是一款快速的正则扫描器。leakferret 匹配其预筛选能力，并增加了服务提供商验证，让你可以处理有效密钥，而不必筛查正则表达式产生的大量噪声。
• trufflehog 会针对服务提供商验证密钥。leakferret 也具备这一能力，还增加了 MCP/Agent 层和由 Agent 应用的重写功能，而这两项是竞品所不具备的。经过签名的样例目录还会避免将已知公开的示例密钥报告为有效密钥。

---

平台

v0.1.6 的预构建二进制文件：

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

---

验证二进制文件

每个发布压缩包均使用 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

每个压缩包还附带一个 .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 是一款可选的、由用户自行安装的 AGPL-3.0 工具，leakferret 会将其作为独立进程调用，用于回退验证。该工具不会随软件打包、修改或再分发。请参阅 NOTICE。