{
  "markdown": "<p align=\"center\">\n  <img src=\"brand/logo.png\" alt=\"leakferret\" width=\"440\">\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/leakferrethq/leakferret/actions/workflows/ci.yml\"><img src=\"https://github.com/leakferrethq/leakferret/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"></a>\n  <a href=\"LICENSE.txt\"><img src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License: MIT\"></a>\n  <a href=\"https://marketplace.visualstudio.com/items?itemName=leakferret.leakferret\"><img src=\"https://img.shields.io/badge/VS%20Code-Marketplace-007ACC?logo=visualstudiocode&logoColor=white\" alt=\"VS Code Marketplace\"></a>\n  <a href=\"https://lobehub.com/mcp/leakferrethq-leakferret\"><img src=\"https://lobehub.com/badge/mcp/leakferrethq-leakferret\" alt=\"MCP Badge\"></a>\n</p>\n\n**MCP-native secret scanner — verified findings, agent-applied rewrites.**\n\nleakferret is one fast Rust binary that is engine, CLI, and MCP server. It finds\nhardcoded secrets in your code, **calls the provider to confirm which ones are\nactually live**, and **rewrites the leak in place** to read from an environment\nvariable. It runs in your terminal, in CI, and as a tool your coding agent calls\nbefore it commits — and the raw secret never leaves your machine.\n\n<p align=\"center\">\n  <img src=\"brand/demo.gif\" alt=\"leakferret finds a leaked AWS key, verifies it, and rewrites it to ENV.fetch\" width=\"760\">\n</p>\n\n---\n\n## What it looks like\n\nSay you accidentally commit a real key, plus the usual noise:\n\n```env\n# .env  — every key below is fabricated for this example\nSTRIPE_SECRET_KEY=sk_live_FAKE_example_not_a_real_key   # fabricated\nGITHUB_TOKEN=ghp_FAKE_example_not_a_real_token          # fabricated\nSENDGRID_API_KEY=${SENDGRID_API_KEY}                    # a reference — not a leak\nADMIN_PASSWORD=changeme                                 # a placeholder — not a leak\nAWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE                  # AWS's public docs example\n```\n\n`leakferret verify` calls each provider and tells you what is **real and live** —\nand stays quiet on the rest:\n\n```text\n$ leakferret verify .\n.env\n  L2  UNKNOWN    CRITICAL  stripe_secret   sk_l..._key\n  L3  VERIFIED   CRITICAL  github_token    ghp_...oken   ← live, rotate it now\n\n2 findings · 1 verified · 1 unknown\n```\n\n<sub>The keys above are fabricated, so the `VERIFIED` line illustrates what a\ngenuinely live key reports — on these examples both would be `UNKNOWN`.</sub>\n\nThe `${SENDGRID_API_KEY}` reference, the `changeme` placeholder, and the\nwell-known `AKIAIOSFODNN7EXAMPLE` example are recognized and **left out** — that\nprecision is the point. Then `leakferret rewrite --apply` rewrites the\nhardcoded key **in your code** (it leaves `.env` files alone — there's nothing\nsensible to rewrite a secret *to* there):\n\n```diff\n  # app/billing.rb  (fabricated example)\n- Stripe.api_key = \"sk_live_FAKE_example_not_a_real_key\"   # fabricated\n+ Stripe.api_key = ENV.fetch(\"STRIPE_API_KEY\")\n```\n\n…and appends `STRIPE_API_KEY=` to `.env.example` with a seed command for your\nsecret manager. **Find → confirm live → fix**, with almost no false alarms.\n\n> The full secret value never leaves your machine. Only a redacted\n> `AKIA...4XYZ` preview is ever written to a report, log, or network message.\n\n---\n\n## Quick start\n\nInstall however you like — every package ships the same prebuilt binary.\n\n```bash\n# Ruby gem\ngem install leakferret\n\n# npm (CLI)\nnpm i -g @leakferret/cli\n\n# Go\ngo install github.com/leakferrethq/leakferret-go/cmd/leakferret@latest\n\n# Native binary — download from GitHub Releases, unpack, and put it on $PATH:\n#   https://github.com/leakferrethq/leakferret/releases\n\n# Rust, from source\ncargo install leakferret-cli\n```\n\nThen scan the current directory:\n\n```bash\nleakferret scan .\n```\n\n`scan` respects `.gitignore` and also reads dotfiles such as `.env`. Add\n`--git` to walk commit history instead of the working tree.\n\n> Every wrapper honors a `LEAKFERRET_BIN` environment variable pointing at a\n> local binary, for offline or development use.\n\n---\n\n## How it works\n\nleakferret runs findings through a five-station pipeline. Each station only\nsees what it needs, and the raw secret never advances past disk.\n\n1. **Scan** — a fast regex pre-filter over your files, across **60+ secret\n   types**. Respects `.gitignore`, reads dotfiles like `.env`, and (with\n   `--git`) walks history.\n2. **Catalog** — every candidate is checked against a signed database of\n   *known-public* example credentials: Stripe test keys,\n   `AKIAIOSFODNN7EXAMPLE`, jwt.io samples, RFC examples. Matches are marked\n   **FIXTURE** so documented examples never raise a false alarm. The catalog is\n   bundled with the binary and can be refreshed and signature-verified.\n3. **Classify** — each remaining candidate gets a verdict: **REAL**,\n   **FIXTURE**, or **UNKNOWN**. This runs offline by default (path rules plus\n   dummy-marker heuristics), or asks the host editor or agent's own language\n   model — no extra API key, no added cost.\n4. **Verify** — makes a single harmless API call to the provider to confirm a\n   key is **LIVE**. Around **25 providers** are covered natively (AWS SigV4,\n   GitHub, GitLab, Stripe, OpenAI, Anthropic, Slack, Twilio, SendGrid, Mailgun,\n   Datadog, Heroku, npm, PyPI, DigitalOcean, Hugging Face, Groq, Replicate,\n   Notion, Postman, Figma, Linear, Square, Shopify, Databricks), with a\n   trufflehog binary fallback for the rest. The call goes straight from your machine to the\n   provider — leakferret has no servers.\n5. **Rewrite** — swaps a hardcoded literal for an environment-variable lookup\n   (`ENV.fetch` / `os.environ` / `process.env`), appends a line to\n   `.env.example`, and prints seed commands for your secret manager (env,\n   Vault, Doppler, AWS Secrets Manager, or Infisical).\n\nA **baseline** stores one-way HMAC fingerprints of known findings — never the\nraw secret — so CI can fail only on *new* leaks.\n\n---\n\n## Use it with AI agents (MCP)\n\nMCP (Model Context Protocol) is the open standard for giving coding agents\ntools. Agents hardcode secrets too, and nobody reviews their diffs line by\nline — leakferret lets the agent self-check before it commits.\n\nStart the server over JSON-RPC on stdio:\n\n```bash\nnpx @leakferret/mcp\n```\n\nAdd it to your `mcpServers` config (Claude Desktop, Cursor, Continue,\nClaude Code):\n\n```json\n{\n  \"mcpServers\": {\n    \"leakferret\": {\n      \"command\": \"npx\",\n      \"args\": [\"@leakferret/mcp\"]\n    }\n  }\n}\n```\n\nFor **Claude Code**, save that block as `.mcp.json` in your project root, or add\nit with one command:\n\n```bash\nclaude mcp add leakferret -- npx -y @leakferret/mcp\n```\n\nIf you installed the native binary, you can point at it directly instead:\n\n```json\n{\n  \"mcpServers\": {\n    \"leakferret\": {\n      \"command\": \"leakferret\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nleakferret is also listed in the [MCP Registry](https://registry.modelcontextprotocol.io)\nas `io.github.leakferrethq/leakferret`, so registry-aware clients can discover it.\n\nTools exposed: `scan_repository`, `classify_candidates`, `verify_finding`,\n`propose_rewrite`, and `baseline_diff`. A `classify` prompt is also provided so\nan agent can classify candidates inline using the model it already has. Two\nread-only resources expose the engine's catalog as context: `leakferret://secret-types`\n(every detectable pattern) and `leakferret://verifiers` (the live-verification providers).\n\n---\n\n## How it compares\n\n|                              | gitleaks | trufflehog | detect-secrets | GitGuardian | leakferret |\n| ---------------------------- | :------: | :--------: | :------------: | :---------: | :--------: |\n| Live provider verification   |    —     |     ✓      |       —        |      ✓      |     ✓      |\n| In-place env-var rewrite      |    —     |     —      |       —        |      —      |     ✓      |\n| MCP server for AI agents      |    —     |     —      |       —        |      —      |     ✓      |\n| Baseline (fail only on new)   |    —     |     —      |       ✓        |      ✓      |     ✓      |\n| SARIF / Code Scanning         |    ✓     |     ✓      |       —        |      ✓      |     ✓      |\n| Free, local, no account       |    ✓     |     ✓      |       ✓        |      —      |     ✓      |\n\ngitleaks is the fastest pre-commit regex blocker. trufflehog set the bar for live\nverification. detect-secrets owns the baseline-a-legacy-repo workflow. GitGuardian is\nthe paid platform with the broadest detectors and a dashboard. leakferret does the\nregex pre-filter, verifies which keys are live, rewrites the leak to an env var, and\nruns as an MCP server so coding agents check their own diffs. Full writeup:\n[leakferret.com/compare](https://leakferret.com/compare/).\n\n---\n\n## CLI reference\n\n```text\nleakferret scan      Regex pre-filter only (no classifier, no verifier)\nleakferret verify    Scan + classify + provider verification\nleakferret rewrite   Scan + classify + propose/apply ENV-fetch rewrites\nleakferret org       Scan every public repo owned by a GitHub user/org\nleakferret baseline  Manage the per-repo fingerprint baseline\nleakferret catalog   Load and inspect the fixture catalog\nleakferret mcp       Start the MCP server on stdio\n```\n\nScan a whole GitHub account or org in one go (handy for finding leaks across all\nyour public repos before someone else does):\n\n```bash\nleakferret org leakferrethq            # all public repos for that owner\nleakferret org myco --token \"$GITHUB_TOKEN\" --format sarif > leaks.sarif\n```\n\nCommon flags:\n\n```bash\n# scan\nleakferret scan .                              # working tree\nleakferret scan . --git                        # scan HEAD's commit history\nleakferret scan . --git --all                  # scan every branch / tag\nleakferret scan . --git --since HEAD~50        # bounded history window\n\n# verify\nleakferret verify .                            # best-effort verification\nleakferret verify . --verify-mode none --fail-on any  # offline gate: exit 1 on any finding\nleakferret verify . --only-verified            # emit only confirmed-live keys\nleakferret verify . --verify-mode ever-verified  # fail on historical leaks\nleakferret verify . --verifier-timeout-secs 10\n\n# rewrite\nleakferret rewrite . --apply                   # write ENV.fetch in place\nleakferret rewrite . --dry-run-diff            # show the diff, touch nothing\nleakferret rewrite . --check                   # CI mode: exit 1 if rewrites pending\nleakferret rewrite . --apply --include-unknown # also fix UNKNOWN (unconfirmed) candidates\nleakferret rewrite . --backend doppler         # seed cmds for your manager\n\n# baseline  (scan/verify are read-only — they never write to your repo)\nleakferret baseline init                       # create .leakferret-baseline.json (gitignores the salt)\nleakferret verify . --update-baseline          # record current findings into the baseline\nleakferret baseline show\nleakferret baseline ignore --fingerprint <fp>  # acknowledge a finding\n\n# catalog\nleakferret catalog info\nleakferret catalog test \"sk_test_4eC39...\"     # deterministic FIXTURE verdict\nleakferret catalog refresh                      # fetch + signature-verify update\n```\n\nShared flags on `scan` / `verify` / `rewrite`: `--format`, `--show-fixtures`,\n`--exclude <glob>`, `--only <path>`, `--only-verified`,\n`--fail-on <none|any|real|verified>`.\n`--backend` accepts `env`, `vault`, `doppler`, `aws-secrets-manager`,\n`infisical`.\n\n---\n\n## Block commits locally (pre-commit hook)\n\nCatch a secret before it is ever committed. From your repo root:\n\n```bash\ncat > .git/hooks/pre-commit <<'HOOK'\n#!/bin/sh\n# Offline secret scan (no network). Blocks the commit on any finding.\nleakferret verify . --verify-mode none --fail-on any || {\n  echo \"leakferret blocked this commit. Bypass: git commit --no-verify\"\n  exit 1\n}\nHOOK\nchmod +x .git/hooks/pre-commit\n```\n\n`--verify-mode none` keeps it fully offline; `--fail-on any` exits non-zero on\nany non-fixture finding (documented examples like `AKIAIOSFODNN7EXAMPLE` are\nstill ignored). Pair it with `leakferret baseline init` so the hook only blocks\non *new* secrets. To share the hook with a team, commit it to `.githooks/` and\nrun `git config core.hooksPath .githooks` once.\n\nThe hook runs on **any** git client — the terminal, GitHub Desktop, the\nVS Code Source Control panel, JetBrains, and so on — because they all run git's\npre-commit hook. A blocked commit shows the leakferret output in that client's\n\"commit failed\" dialog.\n\n**A pre-commit hook is a local convenience, not a wall.** Anyone — or any AI\nagent — can skip it with `git commit --no-verify`, and git offers no way to\nforbid that locally. So treat the hook as fast feedback, and make the\n[GitHub Action](https://github.com/leakferrethq/leakferret-action) (or the same\n`leakferret verify` step in your CI) the **enforcing** gate: it runs\nserver-side on every push and pull request, where `--no-verify` can't reach it.\n\n---\n\n## Output formats\n\nChoose with `--format`:\n\n- **pretty** — colored terminal output (default).\n- **json** — structured findings for scripting and pipelines.\n- **sarif** — for GitHub Code Scanning. The GitHub Action wrapper\n  (`leakferrethq/leakferret-action@v1`) uploads it for you.\n\n---\n\n## Privacy guarantee\n\nThis is the trust story, and a dedicated test enforces it:\n\n> The full secret value lives only on disk. It is **never** written into any\n> report, log, network message, or model prompt. Only a redacted first-4 +\n> last-4 preview (for example `AKIA...4XYZ`) ever leaves the process.\n\nVerification sends the key straight from your machine to the provider.\nleakferret has no servers and collects nothing. Baselines store one-way HMAC\nfingerprints, never the raw secret.\n\n**One operational caveat about `verify`.** Verification makes a real,\nauthenticated request per candidate, so it lands in the key owner's own audit\nlog — an AWS STS `GetCallerIdentity` shows up in CloudTrail, a GitHub token\ncheck shows up as token use, and so on. Point `verify` only at repositories\nwhose secrets are yours to test; running it against someone else's code means\nauthenticating into their accounts and leaving traces there. To scan with no\nnetwork calls at all, use `leakferret scan` instead of `verify`, or pass\n`--verify-mode none`.\n\n---\n\n## How it compares\n\n- **gitleaks** is a fast regex scanner. leakferret matches that pre-filter and\n  adds provider verification, so you act on live keys instead of triaging\n  regex noise.\n- **trufflehog** verifies secrets against providers. leakferret matches that\n  too — and adds the MCP/agent layer and the agent-applied rewrite that neither\n  competitor has. The signed fixture catalog also keeps known-public example\n  keys from being reported as live.\n\n---\n\n## Platforms\n\nPrebuilt binaries for v0.1.6:\n\n- `x86_64-unknown-linux-gnu`\n- `x86_64-apple-darwin`\n- `aarch64-apple-darwin`\n- `x86_64-pc-windows-msvc`\n- `aarch64-pc-windows-msvc`\n\n---\n\n## Verifying the binaries\n\nEvery release tarball is signed with [Sigstore](https://www.sigstore.dev/) /\ncosign — keyless, via GitHub OIDC — and ships a matching `*.cosign.bundle`. You\ncan prove a download was built by this repository's release workflow and was\nnever tampered with:\n\n```bash\ncosign verify-blob \\\n  --bundle leakferret-0.1.6-x86_64-unknown-linux-gnu.tar.gz.cosign.bundle \\\n  --certificate-identity-regexp 'https://github.com/leakferrethq/leakferret/.*' \\\n  --certificate-oidc-issuer https://token.actions.githubusercontent.com \\\n  leakferret-0.1.6-x86_64-unknown-linux-gnu.tar.gz\n```\n\nEach tarball also ships a `.sha256` for a basic integrity check.\n\n---\n\n## Links\n\n- Website: <https://leakferret.com>\n- Source: <https://github.com/leakferrethq/leakferret>\n- Catalog data: <https://github.com/leakferrethq/leakferret-catalog>\n- Wrappers: [ruby](https://github.com/leakferrethq/leakferret-ruby) ·\n  [go](https://github.com/leakferrethq/leakferret-go) ·\n  [npm](https://github.com/leakferrethq/leakferret-npm) ·\n  [action](https://github.com/leakferrethq/leakferret-action) ·\n  [vscode](https://github.com/leakferrethq/leakferret-vscode)\n- Maintainer: Maria Khan &lt;missusk@protonmail.com&gt;\n\n## License\n\nMIT for the engine, CLI, MCP server, and all language wrappers.\nCC-BY-SA-4.0 for the fixture catalog data.\n\n[trufflehog](https://github.com/trufflesecurity/trufflehog) is an optional,\nuser-installed AGPL-3.0 tool that leakferret invokes as a separate process for\nfallback verification. It is not bundled, modified, or redistributed. See\n[`NOTICE`](NOTICE).\n",
  "bytes": 16431,
  "sha": "36356b522ab7ceb387a3837c42ad40e07d81e181fab56ce8d8c21a0d95d3da82",
  "repo_slug": "leakferrethq/leakferret",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_leakferrethq_leakferret_ef81a3b8/readme"
}