leakferrethq/leakferret-ruby
GitHub: leakferrethq/leakferret-ruby
Ruby gem 形式的密钥扫描器，帮助开发者在代码中检测、验证并自动重写硬编码的密钥与 API key。
Stars: 0 | Forks: 0
# leakferret (Ruby gem)
[](https://rubygems.org/gems/leakferret)
[](https://github.com/leakferrethq/leakferret/blob/master/LICENSE.txt)
[](https://lobehub.com/mcp/leakferrethq-leakferret-ruby)
原生 [`leakferret`](https://github.com/leakferrethq/leakferret) 二进制文件的 Ruby gem 封装。这个 gem 本身不包含任何扫描逻辑：它安装了一个轻量级的 Ruby shim 以及预构建的静态链接引擎（使用 Rust 编写）。所有的工作——扫描、分类、验证、重写——都在那个单一的二进制文件中完成。
你将得到一个**预编译的平台 gem**，其中包含了内置的二进制文件，就像 `nokogiri` 和 `sorbet-static` 发布其原生代码的方式一样，适用于 x86_64 Linux (glibc)、macOS (x86_64 和 arm64) 以及 x86_64 Windows。二进制文件随着 gem 一起通过 RubyGems 分发——**无需下载，无需网络访问，无需 Rust 工具链**——你可以使用 `gem unpack leakferret` 准确审查将要运行的内容。该 gem **完全不包含任何获取并运行的代码**。在任何其他平台上，源码 gem 会进行安装并提示你进行一键修复（从源码构建，或设置 `LEAKFERRET_BIN`）；它绝不会下载二进制文件。
## leakferret 的作用
leakferret 会在你的代码中查找硬编码的密钥和 API key，并分五个阶段帮助你移除它们：
1. **Scan** — 对文件进行 regex 预过滤；遵循 `.gitignore` 并且还会读取如 `.env` 的 dotfiles。
2. **Catalog** — 一个已知的公开示例凭证签名数据库（Stripe test key、`AKIAIOSFODNN7EXAMPLE`、jwt.io 样本），以便将文档示例标记为 `FIXTURE` 而不是产生误报。
3. **Classify** — 通过离线启发式算法或通过询问宿主编辑器/agent 语言模型（无需额外的 API key，无成本）得出 `REAL` / `FIXTURE` / `UNKNOWN` 判定结果。
4. **Verify** — 向 provider（AWS SigV4、GitHub、GitLab、Stripe、OpenAI、Anthropic、Slack、Twilio、SendGrid、Mailgun、Datadog、Heroku、npm、PyPI、DigitalOcean）发起真实但无害的 API 调用，以确认 key 是否有效，并带有 trufflehog 回退机制。
5. **Rewrite** — 将硬编码的字面量替换为环境变量查找（Ruby 中的 `ENV.fetch`，JS 中的 `process.env`，Python 中的 `os.environ`），添加一行 `.env.example`，并打印密钥管理器的种子命令。
**隐私不变性：** 完整的密钥值永远不会离开你的机器。只有经过脱敏处理的“前 4 位加后 4 位”预览（例如 `AKIA...4XYZ`）会被写入报告、日志、网络消息或模型 prompt 中。验证调用直接从你的机器发送到 provider——leakferret 没有服务器。
## 安装
```
gem install leakferret
```
RubyGems 和 Bundler 会自动为你的平台选择正确的预编译 gem，因此二进制文件在 `gem install` 后就已经存在了——无需首次运行下载。在信任它之前，请先进行检查：
```
gem unpack leakferret # the bundled binary is at lib/leakferret/bin/
```
已发布的 gem 带有 GitHub 构建来源（SLSA），因此你可以验证每个 gem 是否是由 CI 中标记的源码构建的。在没有预构建二进制文件的平台（例如 aarch64-linux 或 Alpine/musl）上，源码 gem 仍然可以安装——因此 `bundle install` 可以解析——并提示你从源码构建（`cargo install leakferret-cli`）或设置 `LEAKFERRET_BIN`。它绝不进行下载。
将其添加到 `Gemfile` 以供项目本地使用：
```
gem 'leakferret'
```
需要 Ruby >= 3.1。
## CLI
该 gem 安装了一个 `leakferret` 可执行文件，它只需对该二进制文件执行 `exec`，因此每个子命令和 flag 的工作方式与上游完全一致：
```
leakferret scan .
leakferret verify . --only-verified
leakferret rewrite . --apply --backend doppler
leakferret baseline init
leakferret catalog info
leakferret mcp # MCP server on stdio
```
`leakferret scan --git` 会遍历提交历史记录。输出格式包括 `pretty`（彩色终端）、`json` 和 `sarif`（用于 GitHub Code Scanning）。
## Ruby API
```
require 'leakferret'
# 仅 Regex 预过滤。
findings = Leakferret.scan('.')
# + provider 已验证（通过实时 HTTP 连接到 GitHub / Stripe / AWS / ...）。
findings = Leakferret.verify('.', mode: 'only-verified')
# + 为 REAL findings 建议重写。
findings = Leakferret.rewrite('.', backend: 'doppler')
# 原地应用重写。
Leakferret.rewrite('.', apply: true)
```
每个 `Finding` 都是一个 hash，包含 `path`、`line`、`column`、`pattern`、`severity`（`critical`/`high`/`medium`/`low`）、`verdict`（`real`/`fixture`/`unknown`）、`match_redacted`、`confidence`、`verification` 和 `fingerprint`。
## 重写泄漏
`rewrite` 将硬编码的密钥转换为环境变量查找，并帮助你将其移动到密钥管理器中：
```
leakferret rewrite . --dry-run-diff # preview the change, touch nothing
leakferret rewrite . --apply # write `ENV.fetch("KEY")` in place + add to .env.example
leakferret rewrite . --apply --backend doppler # also print seed commands for your manager
```
`--backend` 接受 `env`（默认）、`vault`、`doppler`、`aws-secrets-manager`、`infisical`。默认情况下，它只会重写被确认为 **REAL/live** 的发现结果；添加 `--include-unknown` 也可以修复未确认的候选项。
## 在 CI 中使用
leakferret 是一个具有明确退出代码（`0` = 干净，`1` = 有发现结果）的二进制文件，因此它可以轻松融入任何 CI。推荐的模式：**建立一次 baseline**，然后在每次构建时执行 `verify`，这样你就只会在出现*新*密钥时失败。
```
# 在可能已经有 findings 的 repo 上一次性执行：
leakferret baseline init # fingerprints current findings (HMAC, never the raw secret)
git add .leakferret-baseline.json # commit it — the per-repo salt is auto-gitignored
```
此后，`verify` 将忽略 baseline 中的任何内容，并且仅在出现新的泄漏时失败。
**GitHub Actions** — 使用专用 action（将 SARIF 上传到 Code Scanning）：
```
- uses: leakferrethq/leakferret-action@v1
with: { path: ., fail-on: any }
```
**CircleCI：**
```
jobs:
secrets:
docker: [{ image: cimg/ruby:3.3 }]
steps:
- checkout
- run: gem install leakferret
- run: leakferret verify . --format sarif > leakferret.sarif
- store_artifacts: { path: leakferret.sarif }
```
**GitLab CI / Argo Workflows / Jenkins / 其他任何工具** — 相同的配方：
```
gem install leakferret
leakferret verify . # exits 1 on any REAL finding -> fails the job
```
有用的 flag：`--only-verified`（仅在 provider 确认的 live key 时失败）、`--verify-mode ever-verified`（带有 baseline，在*曾经*验证为 live 的任何内容上失败）、`--format sarif|json`。
## 与 AI agent (MCP) 配合使用
leakferret 也是一个 MCP server，因此代码编写 agent（Cursor、Claude、Continue）可以在*提交之前*进行扫描、验证和重写。将其添加到你的编辑器的 MCP config 中：
```
{
"mcpServers": {
"leakferret": { "command": "leakferret", "args": ["mcp"] }
}
}
```
在 **Cursor** 中：Settings → MCP → Add。在 **Claude Desktop** 中：`claude_desktop_config.json` 的 `mcpServers` 块。暴露的工具：`scan_repository`、`classify_candidates`、`verify_finding`、`propose_rewrite`、`baseline_diff`。
## 使用本地二进制文件
每个 leakferret wrapper 都遵循 `LEAKFERRET_BIN` 环境变量。将其指向磁盘上的二进制文件，wrapper 就会运行该文件，而不是下载的副本：
```
export LEAKFERRET_BIN=/opt/leakferret/leakferret
leakferret scan .
```
对于气隙隔离或离线安装，设置 `LEAKFERRET_SKIP_DOWNLOAD=1` 可跳过 release 下载，并自行放置二进制文件。
## 在本地拦截提交（pre-commit hook）
在密钥被提交之前将其捕获。在你的 repo 根目录下执行：
```
cat > .git/hooks/pre-commit <<'HOOK'
#!/bin/sh
# 离线 secret 扫描（无网络）。在任何 finding 上阻止 commit。
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` 会在任何非 fixture 发现结果上以非零状态退出（像 `AKIAIOSFODNN7EXAMPLE` 这样的文档示例仍然会被忽略）。与 `leakferret baseline init` 配合使用可仅针对*新*密钥进行拦截，或者将该 hook 提交到 `.githooks/` 并运行 `git config core.hooksPath .githooks` 以便与团队共享。
## 许可证
本 gem 和内置二进制文件的 MIT 许可证。Fixture 目录**数据**采用 CC-BY-SA-4.0 许可证——参见 [`leakferret-catalog`](https://github.com/leakferrethq/leakferret-catalog)。
[leakferret](https://github.com/leakferrethq/leakferret) 的一部分 ·
[leakferret.com](https://leakferret.com) ·
由 Maria Khan <missusk@protonmail.com> 维护。
标签：LNA, Ruby, Rust, StruQ, 可视化界面, 知识库, 网络流量审计