leakferret 0.2.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bd9375c03897c6ce0d46a768d62356484dc54365310952d6a1e2afccd31ccb26
+  data.tar.gz: 9dafdf0b3de2cdf0184d2c4a8d0373084435347e87cb078d9145217e32b5e24e
+SHA512:
+  metadata.gz: b5294f97cb9d81711cd756224a3bf7b3b4e2c8f9eac1406b7c40374c174cbde2c061cee23f9b67e0da52053626510d60bdc6912a4cc9f439a4158e56a2bbfc49
+  data.tar.gz: 3c4ca608c5d66f8319d3827bd224cd724150cd745f18916e565d8f3e7edc06d251a4be88e81bc07f86fafb2ee35f7279b75edb1c51343670e96d03e0c9bb683f

data/.yardopts

@@ -0,0 +1,8 @@
+--markup markdown
+--readme README.md
+--title "leakferret (Ruby)"
+--no-private
+--charset utf-8
+lib/**/*.rb
+-
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to the `leakferret` gem are documented here. The gem version
+can move independently of the native binary version it targets.
+
+## [0.2.0] - 2026-06-04
+
+Minor bump (not patch): this removes the binary-download fallback, so a
+previously-supported install path is gone on platforms without a prebuilt gem
+(notably arm64-Windows). Breaking change under the 0.x convention.
+
+### Changed
+- Ship **precompiled platform gems** (x86_64-linux, x86_64-darwin, arm64-darwin,
+  x64-mingw-ucrt) with the native binary bundled inside the gem. A normal
+  `gem install` gets the binary through RubyGems itself: no download, no
+  network, no Rust toolchain. Audit it with `gem unpack leakferret`. Mirrors how
+  `nokogiri` and `sorbet-static` ship.
+- **Removed the binary-download flow entirely.** Dropped the install-time
+  `extconf.rb` pre-fetch and the runtime download + SHA256 logic. The gem now
+  has no fetch-and-run code to audit at all.
+- On a platform without a prebuilt binary (e.g. aarch64-linux, Alpine/musl), the
+  source gem still installs (so `bundle install` resolves) and raises a clear
+  message pointing to `cargo install leakferret-cli` or `LEAKFERRET_BIN`. It
+  never downloads.
+- Released gems now carry GitHub build provenance (SLSA attestation).
+
+### Removed
+- `ext/leakferret/extconf.rb` and the runtime binary downloader.
+
+Targets the leakferret `0.1.9` binary (unchanged).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maria Khan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,250 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/leakferrethq/leakferret/master/brand/logo.png" alt="leakferret" width="380">
+</p>
+
+# leakferret (Ruby gem)
+
+> MCP-native secret scanner — verified findings, agent-applied rewrites.
+
+[![Gem Version](https://img.shields.io/gem/v/leakferret?logo=rubygems&logoColor=white)](https://rubygems.org/gems/leakferret)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/leakferrethq/leakferret/blob/master/LICENSE.txt)
+[![MCP Badge](https://lobehub.com/badge/mcp/leakferrethq-leakferret-ruby)](https://lobehub.com/mcp/leakferrethq-leakferret-ruby)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/leakferrethq/leakferret/master/brand/demo.gif" alt="leakferret finds, verifies, and rewrites a leaked secret" width="760">
+</p>
+
+Ruby gem wrapper around the native [`leakferret`](https://github.com/leakferrethq/leakferret)
+binary. This gem ships no scanning logic of its own: it installs a tiny Ruby
+shim plus the prebuilt, statically-linked engine (written in Rust). All the
+work — scan, classify, verify, rewrite — happens in that single binary.
+
+You get a **precompiled platform gem** with the binary bundled inside it, the
+same way `nokogiri` and `sorbet-static` ship their native code, for x86_64
+Linux (glibc), macOS (x86_64 and arm64), and x86_64 Windows. The binary travels
+through RubyGems with the gem — **no download, no network access, no Rust
+toolchain** — and you can audit exactly what you will run with
+`gem unpack leakferret`. The gem has **no fetch-and-run code at all**. On any
+other platform the source gem installs and points you at a one-line fix (build
+from source, or set `LEAKFERRET_BIN`); it never downloads a binary.
+
+## What leakferret does
+
+leakferret finds hardcoded secrets and API keys in your code and helps you
+remove them, in five stations:
+
+1. **Scan** — regex pre-filter over files; respects `.gitignore` and also reads
+   dotfiles like `.env`.
+2. **Catalog** — a signed database of known-public example credentials (Stripe
+   test keys, `AKIAIOSFODNN7EXAMPLE`, jwt.io samples) so documented examples are
+   marked `FIXTURE` instead of false-alarming.
+3. **Classify** — a `REAL` / `FIXTURE` / `UNKNOWN` verdict, from offline
+   heuristics or by asking the host editor/agent language model (no extra API
+   key, no cost).
+4. **Verify** — a real but harmless API call to the provider (AWS SigV4,
+   GitHub, GitLab, Stripe, OpenAI, Anthropic, Slack, Twilio, SendGrid, Mailgun,
+   Datadog, Heroku, npm, PyPI, DigitalOcean) to confirm a key is live, plus a
+   trufflehog fallback.
+5. **Rewrite** — swap a hardcoded literal for an environment-variable lookup
+   (`ENV.fetch` in Ruby, `process.env` in JS, `os.environ` in Python), add a
+   `.env.example` line, and print secret-manager seed commands.
+
+**Privacy invariant:** the full secret value never leaves your machine. Only a
+redacted first-4-plus-last-4 preview (e.g. `AKIA...4XYZ`) is ever written to a
+report, log, network message, or model prompt. Verification calls go straight
+from your machine to the provider — leakferret has no servers.
+
+## Install
+
+```bash
+gem install leakferret
+```
+
+RubyGems and Bundler select the right precompiled gem for your platform
+automatically, so the binary is already there after `gem install` — no
+first-run download. Inspect it before you trust it:
+
+```bash
+gem unpack leakferret        # the bundled binary is at lib/leakferret/bin/
+```
+
+Released gems carry GitHub build provenance (SLSA), so you can verify each gem
+was built from the tagged source in CI. On a platform without a prebuilt binary
+(e.g. aarch64-linux or Alpine/musl), the source gem still installs — so
+`bundle install` resolves — and tells you to build from source
+(`cargo install leakferret-cli`) or set `LEAKFERRET_BIN`. It never downloads.
+
+Add it to a `Gemfile` for project-local use:
+
+```ruby
+gem 'leakferret'
+```
+
+Requires Ruby >= 3.1.
+
+## CLI
+
+The gem installs a `leakferret` executable that simply `exec`s the binary, so
+every subcommand and flag works exactly as upstream:
+
+```bash
+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` walks commit history. Output formats are `pretty`
+(colored terminal), `json`, and `sarif` (for GitHub Code Scanning).
+
+## Ruby API
+
+```ruby
+require 'leakferret'
+
+# Regex pre-filter only.
+findings = Leakferret.scan('.')
+
+# + provider-verified (live HTTP to GitHub / Stripe / AWS / ...).
+findings = Leakferret.verify('.', mode: 'only-verified')
+
+# + propose rewrites for REAL findings.
+findings = Leakferret.rewrite('.', backend: 'doppler')
+
+# Apply rewrites in place.
+Leakferret.rewrite('.', apply: true)
+```
+
+Each `Finding` is a hash with `path`, `line`, `column`, `pattern`, `severity`
+(`critical`/`high`/`medium`/`low`), `verdict` (`real`/`fixture`/`unknown`),
+`match_redacted`, `confidence`, `verification`, and `fingerprint`.
+
+## Rewrite a leak
+
+`rewrite` turns a hardcoded secret into an env-var lookup and helps you move it
+into a secret manager:
+
+```bash
+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` accepts `env` (default), `vault`, `doppler`, `aws-secrets-manager`,
+`infisical`. By default it only rewrites findings confirmed **REAL/live**; add
+`--include-unknown` to also fix unconfirmed candidates.
+
+## Use it in CI
+
+leakferret is one binary with clear exit codes (`0` = clean, `1` = findings), so
+it drops into any CI. The recommended pattern: **baseline once**, then `verify`
+on every build so you only fail on *new* secrets.
+
+```bash
+# One-time, on a repo that may already have findings:
+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
+```
+
+After that, `verify` ignores anything in the baseline and fails only on new leaks.
+
+**GitHub Actions** — use the dedicated action (uploads SARIF to Code Scanning):
+
+```yaml
+- uses: leakferrethq/leakferret-action@v1
+  with: { path: ., fail-on: any }
+```
+
+**CircleCI:**
+
+```yaml
+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 / anything else** — identical recipe:
+
+```bash
+gem install leakferret
+leakferret verify .                 # exits 1 on any REAL finding -> fails the job
+```
+
+Useful flags: `--only-verified` (fail only on provider-confirmed live keys),
+`--verify-mode ever-verified` (with a baseline, fail on anything that *ever*
+verified live), `--format sarif|json`.
+
+## Use it with AI agents (MCP)
+
+leakferret is also an MCP server, so a coding agent (Cursor, Claude, Continue)
+can scan, verify, and rewrite *before it commits*. Add it to your editor's MCP
+config:
+
+```json
+{
+  "mcpServers": {
+    "leakferret": { "command": "leakferret", "args": ["mcp"] }
+  }
+}
+```
+
+In **Cursor**: Settings → MCP → Add. In **Claude Desktop**: the `mcpServers`
+block of `claude_desktop_config.json`. Tools exposed: `scan_repository`,
+`classify_candidates`, `verify_finding`, `propose_rewrite`, `baseline_diff`.
+
+> Running `leakferret mcp` directly in a terminal looks like it hangs — that's
+> correct. It's a stdio JSON-RPC server waiting for your editor to connect, not
+> a command you run by hand.
+
+## Using a local binary
+
+Every leakferret wrapper honors the `LEAKFERRET_BIN` environment variable. Point
+it at a binary on disk and the wrapper runs that instead of the downloaded copy:
+
+```bash
+export LEAKFERRET_BIN=/opt/leakferret/leakferret
+leakferret scan .
+```
+
+For air-gapped or offline installs, set `LEAKFERRET_SKIP_DOWNLOAD=1` to skip the
+release download and position the binary yourself.
+
+## Block commits locally (pre-commit hook)
+
+Catch a secret before it is ever committed. From your repo root:
+
+```bash
+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` keeps it offline; `--fail-on any` exits non-zero on any
+non-fixture finding (documented examples like `AKIAIOSFODNN7EXAMPLE` are still
+ignored). Pair with `leakferret baseline init` to block only on *new* secrets,
+or commit the hook to `.githooks/` and run `git config core.hooksPath .githooks`
+to share it with a team.
+
+## License
+
+MIT for this gem and the bundled binary. The fixture catalog **data** is
+CC-BY-SA-4.0 — see [`leakferret-catalog`](https://github.com/leakferrethq/leakferret-catalog).
+
+---
+
+Part of [leakferret](https://github.com/leakferrethq/leakferret) ·
+[leakferret.com](https://leakferret.com) ·
+maintained by Maria Khan &lt;missusk@protonmail.com&gt;.

data/exe/leakferret

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Pass-through to the bundled native binary. Same CLI as the Rust crate.
+require 'leakferret'
+
+bin = Leakferret::Binary.path
+exec(bin, *ARGV)

data/lib/leakferret/binary.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+require_relative 'version'
+require_relative 'platform'
+require_relative 'error'
+
+module Leakferret
+  # Resolves the native `leakferret` binary that ships inside the gem.
+  #
+  # Precompiled platform gems bundle the binary at lib/leakferret/bin/. There is
+  # deliberately no download path: the gem either carries the binary for your
+  # platform or it tells you how to provide one. Nothing here touches the
+  # network, so what you `gem unpack` is exactly what runs - the whole gem is
+  # auditable, with no fetch-and-execute code to vet.
+  #
+  # @api private
+  module Binary
+    # Where a precompiled platform gem stages the native binary.
+    BUNDLED_DIR = Pathname.new(__dir__).join('bin').freeze
+
+    module_function
+
+    # Absolute path to the native binary. Resolution order:
+    #   1. LEAKFERRET_BIN             - explicit override
+    #   2. lib/leakferret/bin/<name>  - bundled by the precompiled platform gem
+    #
+    # @return [String] absolute path to the executable
+    # @raise [BinaryNotFoundError] if the override is missing, or no binary is
+    #   bundled for this platform
+    def path
+      override = ENV['LEAKFERRET_BIN']
+      unless override.nil? || override.empty?
+        unless File.file?(override)
+          raise BinaryNotFoundError, "LEAKFERRET_BIN points to a missing file: #{override}"
+        end
+
+        return override
+      end
+
+      bundled = BUNDLED_DIR.join(Platform.binary_name)
+      if bundled.file?
+        # Make sure it is executable in case the mode did not survive packaging
+        # or install; the gem dir is usually writable, a read-only one is
+        # harmless to skip.
+        unless Platform.windows? || bundled.executable?
+          begin
+            bundled.chmod(0o755)
+          rescue StandardError
+            # best effort
+          end
+        end
+        return bundled.to_s
+      end
+
+      raise BinaryNotFoundError, no_binary_message
+    end
+
+    # Message shown when the source/fallback gem is installed on a platform with
+    # no precompiled binary. No automatic download is attempted - the user
+    # provides the binary, or builds it.
+    #
+    # @return [String] multi-line build-from-source instructions
+    def no_binary_message
+      plat =
+        begin
+          Gem::Platform.local.to_s
+        rescue StandardError
+          RUBY_PLATFORM
+        end
+
+      <<~MSG
+        No prebuilt leakferret binary ships for this platform (#{plat}).
+
+        leakferret publishes precompiled gems for x86_64 and arm64 macOS,
+        x86_64 Linux (glibc), and x86_64 Windows. On any other platform, provide
+        the binary yourself - either of these works:
+
+          1. Build from source and point LEAKFERRET_BIN at it:
+               cargo install leakferret-cli
+               export LEAKFERRET_BIN="$(command -v leakferret)"
+
+          2. Download a release binary for your platform from
+               https://github.com/leakferrethq/leakferret/releases
+             and set LEAKFERRET_BIN to its absolute path.
+      MSG
+    end
+  end
+end

data/lib/leakferret/client.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+module Leakferret
+  # Thin shell-out wrapper around the native binary. Each public method invokes
+  # `leakferret <verb> --format json` and parses the resulting array. You
+  # normally call the module-level {Leakferret.scan}, {Leakferret.verify}, and
+  # {Leakferret.rewrite} helpers instead of constructing this directly.
+  class Client
+    # Run a scan-only pass (regex pre-filter, offline).
+    #
+    # @param path [String] file or directory to scan
+    # @param exclude [Array<String>] glob(s) to skip
+    # @param only [Array<String>, String, nil] restrict the scan to these path(s)
+    # @param show_fixtures [Boolean] include catalog fixtures in the result
+    # @return [Array<Hash>] candidate finding hashes
+    # @raise [BinaryInvocationError] on an unexpected exit status
+    def scan(path, exclude: [], only: nil, show_fixtures: false)
+      run(['scan', path, '--format', 'json'] + format_flags(exclude:, only:, show_fixtures:))
+    end
+
+    # Run scan + classify + provider verification.
+    #
+    # @param path [String] file or directory to scan
+    # @param mode [String] verify mode passed to `--verify-mode`
+    # @param timeout [Integer] per-verifier timeout in seconds
+    # @option opts [Array<String>] :exclude glob(s) to skip
+    # @option opts [Array<String>, String] :only restrict the scan to these path(s)
+    # @option opts [Boolean] :show_fixtures include catalog fixtures
+    # @return [Array<Hash>] findings with verification and verdict filled in
+    # @raise [BinaryInvocationError] on an unexpected exit status
+    def verify(path, mode: 'best-effort', timeout: 10, **opts)
+      run(['verify', path, '--format', 'json', '--verify-mode', mode,
+           '--verifier-timeout-secs', timeout.to_s] + format_flags(**opts))
+    end
+
+    # Run scan + classify + rewrite proposal.
+    #
+    # @param path [String] file or directory to scan
+    # @param apply [Boolean] write the rewrites in place when true
+    # @param backend [String] rewrite backend (e.g. `env`, `doppler`)
+    # @option opts [Array<String>] :exclude glob(s) to skip
+    # @option opts [Array<String>, String] :only restrict the scan to these path(s)
+    # @return [Array<Hash>] findings, each with a proposed replacement
+    # @raise [BinaryInvocationError] on an unexpected exit status
+    def rewrite(path, apply: false, backend: 'env', **opts)
+      args = ['rewrite', path, '--format', 'json', '--backend', backend]
+      args << '--apply' if apply
+      run(args + format_flags(**opts))
+    end
+
+    private
+
+    # Build the shared `--exclude` / `--only` / `--show-fixtures` flag list.
+    #
+    # @return [Array<String>] CLI flags
+    # @api private
+    def format_flags(exclude: [], only: nil, show_fixtures: false)
+      flags = []
+      Array(exclude).each { |g| flags.push('--exclude', g) }
+      Array(only).each   { |p| flags.push('--only',    p) }
+      flags << '--show-fixtures' if show_fixtures
+      flags
+    end
+
+    # Invoke the binary and parse its JSON output. Exit codes 0 (clean) and 1
+    # (findings present) are both treated as success; any other status raises.
+    #
+    # @param args [Array<String>] argv passed to the binary
+    # @return [Array<Hash>] the parsed findings (empty array when output is blank)
+    # @raise [BinaryInvocationError] if the binary exits with a status other than 0 or 1
+    # @api private
+    def run(args)
+      out, err, status = Open3.capture3(Binary.path, *args)
+      unless [0, 1].include?(status.exitstatus)
+        raise BinaryInvocationError.new(
+          "leakferret exited with #{status.exitstatus}",
+          exit_status: status.exitstatus,
+          stderr: err,
+        )
+      end
+      JSON.parse(out.strip.empty? ? '[]' : out)
+    end
+  end
+end

data/lib/leakferret/error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Leakferret
+  # Base class for every error this gem raises. Rescue this to catch them all.
+  class Error < StandardError; end
+
+  # Raised when the native binary cannot be located or downloaded (no pinned
+  # checksum for the platform, a failed download, or a bad `LEAKFERRET_BIN`).
+  class BinaryNotFoundError < Error; end
+
+  # Raised when the binary runs but exits with an unexpected status (anything
+  # other than 0 for a clean run or 1 for findings present).
+  class BinaryInvocationError < Error
+    # @return [Integer] the binary's process exit status
+    attr_reader :exit_status
+
+    # @return [String] captured standard error from the failed invocation
+    attr_reader :stderr
+
+    # @param message [String] human-readable error message
+    # @param exit_status [Integer] the binary's exit status
+    # @param stderr [String] captured standard error
+    def initialize(message, exit_status:, stderr:)
+      super(message)
+      @exit_status = exit_status
+      @stderr = stderr
+    end
+  end
+end

data/lib/leakferret/platform.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+
+require_relative 'error'
+
+module Leakferret
+  # Host detection for picking the right release asset. Maps the running
+  # Ruby's `RbConfig` host to a Rust target triple and binary name.
+  #
+  # @api private
+  module Platform
+    module_function
+
+    # The Rust target triple for the current host (e.g.
+    # `x86_64-unknown-linux-gnu`).
+    #
+    # @return [String] the target triple
+    # @raise [Error] on an unsupported CPU or OS, or aarch64-linux (no asset yet)
+    def triple
+      cpu = case RbConfig::CONFIG['host_cpu']
+            when /x86_64|amd64|x64/ then 'x86_64'
+            when /aarch64|arm64/ then 'aarch64'
+            else
+              raise Error, "unsupported CPU: #{RbConfig::CONFIG['host_cpu']}"
+            end
+
+      case RbConfig::CONFIG['host_os']
+      when /mswin|mingw|cygwin/ then "#{cpu}-pc-windows-msvc"
+      when /darwin/             then "#{cpu}-apple-darwin"
+      when /linux/
+        # No aarch64-linux release asset yet (v0.1.0 ships x86_64 only).
+        raise Error, 'aarch64-linux has no prebuilt binary yet; build from source' if cpu == 'aarch64'
+
+        "#{cpu}-unknown-linux-gnu"
+      else
+        raise Error, "unsupported OS: #{RbConfig::CONFIG['host_os']}"
+      end
+    end
+
+    # Executable name for the current OS.
+    # @return [String] `"leakferret.exe"` on Windows, otherwise `"leakferret"`
+    def binary_name
+      windows? ? 'leakferret.exe' : 'leakferret'
+    end
+
+    # @return [Integer, nil] truthy when the host OS is Windows
+    def windows?
+      RbConfig::CONFIG['host_os'] =~ /mswin|mingw|cygwin/
+    end
+  end
+end

data/lib/leakferret/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Leakferret
+  # The gem's own version (what `gem install leakferret` resolves).
+  # @return [String]
+  VERSION = '0.2.0'
+
+  # The native binary release this gem bundles and runs. The release workflow
+  # stages this version's binary into each precompiled platform gem. Tracks the
+  # leakferret core release and can move independently of {VERSION} (e.g. a
+  # gem-only bugfix keeps the same binary).
+  # @return [String]
+  BINARY_VERSION = '0.1.9'
+end

data/lib/leakferret.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+require 'leakferret/version'
+require 'leakferret/error'
+require 'leakferret/platform'
+require 'leakferret/binary'
+require 'leakferret/client'
+
+# Ruby wrapper around the native `leakferret` secret scanner.
+#
+# leakferret finds hardcoded secrets, confirms which ones are actually live by
+# calling the provider, and rewrites them to read from environment variables.
+# This gem is a thin wrapper: the native binary (written in Rust) is downloaded
+# once per platform on first use and cached, then each call shells out to it
+# and parses the JSON it prints. The full secret value never leaves your
+# machine; every finding carries only a redacted `first4...last4` preview.
+#
+# The three top-level methods mirror the CLI verbs and each return an array of
+# finding hashes.
+#
+# @example Scan the working tree
+#   Leakferret.scan(".").each do |f|
+#     puts "#{f['path']}:#{f['line']} #{f['pattern']} [#{f['verdict']}]"
+#   end
+#
+# @example Fail a script on any live secret
+#   exit(1) unless Leakferret.verify(".", mode: "only-verified").empty?
+#
+# @see https://leakferret.com
+# @see https://github.com/leakferrethq/leakferret
+module Leakferret
+  class << self
+    # Scan a path for candidate secrets. This is the regex pre-filter only (no
+    # classification, no verification): the fastest, fully offline pass.
+    #
+    # @param path [String] file or directory to scan, relative or absolute
+    # @option opts [Array<String>] :exclude glob(s) to skip
+    # @option opts [Array<String>, String] :only restrict the scan to these path(s)
+    # @option opts [Boolean] :show_fixtures (false) include catalog fixtures in the result
+    # @return [Array<Hash>] candidate findings, each with `path`, `line`,
+    #   `pattern`, `verdict`, and `match_redacted` keys
+    # @raise [BinaryInvocationError] if the binary exits with an unexpected status
+    # @example
+    #   Leakferret.scan("app/", exclude: ["**/*_test.rb"])
+    def scan(path = '.', **opts)
+      Client.new.scan(path, **opts)
+    end
+
+    # Scan, classify, and verify. Real findings are confirmed live with a
+    # harmless API call to the provider (AWS, GitHub, Stripe, and others), so
+    # this method makes outbound network requests.
+    #
+    # @param path [String] file or directory to scan
+    # @option opts [String] :mode ("best-effort") verify mode: `none`,
+    #   `best-effort`, `only-verified`, or `ever-verified`
+    # @option opts [Integer] :timeout (10) per-verifier timeout in seconds
+    # @option opts [Array<String>] :exclude glob(s) to skip
+    # @option opts [Array<String>, String] :only restrict the scan to these path(s)
+    # @return [Array<Hash>] findings with `verdict` and `verification` filled in
+    # @raise [BinaryInvocationError] if the binary exits with an unexpected status
+    # @example Only return secrets confirmed live
+    #   Leakferret.verify(".", mode: "only-verified")
+    def verify(path = '.', **opts)
+      Client.new.verify(path, **opts)
+    end
+
+    # Scan, classify, and propose environment-variable rewrites for real
+    # findings. Pass `apply: true` to write the rewrites to disk in place.
+    #
+    # @param path [String] file or directory to scan
+    # @param apply [Boolean] when true, edit files in place; otherwise only
+    #   propose the replacements
+    # @option opts [String] :backend ("env") rewrite backend, e.g. `env`, `doppler`
+    # @return [Array<Hash>] findings, each with a `replacement` proposal attached
+    # @raise [BinaryInvocationError] if the binary exits with an unexpected status
+    # @example Apply rewrites and seed Doppler
+    #   Leakferret.rewrite(".", apply: true, backend: "doppler")
+    def rewrite(path = '.', apply: false, **opts)
+      Client.new.rewrite(path, apply: apply, **opts)
+    end
+
+    # Absolute path to the native binary, downloading it on first use.
+    #
+    # @return [String] absolute filesystem path to the `leakferret` executable
+    # @raise [BinaryNotFoundError] if the binary is missing and cannot be fetched
+    def binary_path
+      Binary.path
+    end
+
+    # Version string reported by the bundled native binary. May differ from
+    # {VERSION} (the gem's own version) during pre-release; see {BINARY_VERSION}.
+    #
+    # @return [String] the binary's `--version` output, stripped
+    def binary_version
+      out, _err, _status = Open3.capture3(binary_path, '--version')
+      out.strip
+    end
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: leakferret
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: x86_64-linux
+authors:
+- Maria Khan
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-04 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Context-aware secret scanning for Ruby projects. A thin wrapper around the
+  native leakferret binary (written in Rust): it finds hardcoded secrets,
+  confirms which ones are actually live by calling the provider, and rewrites
+  them to read from environment variables instead.
+
+  Precompiled platform gems bundle the native binary inside the gem, so a
+  normal `gem install` ships the binary through RubyGems itself: no download,
+  no network access, and no Rust toolchain. You can audit exactly what you are
+  about to run with `gem unpack leakferret`. The gem never fetches and runs a
+  binary off the internet - there is no download code to vet. On a platform
+  without a prebuilt gem, the source gem tells you to build from source
+  (`cargo install leakferret-cli`) or point LEAKFERRET_BIN at a binary.
+
+  The API exposes Leakferret.scan, Leakferret.verify, and Leakferret.rewrite
+  (each returning Finding objects), plus a `leakferret` command-line tool.
+email:
+- missusk@protonmail.com
+executables:
+- leakferret
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/leakferret
+- lib/leakferret.rb
+- lib/leakferret/bin/leakferret
+- lib/leakferret/binary.rb
+- lib/leakferret/client.rb
+- lib/leakferret/error.rb
+- lib/leakferret/platform.rb
+- lib/leakferret/version.rb
+homepage: https://github.com/leakferrethq/leakferret-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/leakferrethq/leakferret-ruby
+  source_code_uri: https://github.com/leakferrethq/leakferret-ruby
+  changelog_uri: https://github.com/leakferrethq/leakferret-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/leakferret
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Context-aware secret detection (Ruby wrapper for the leakferret binary).
+test_files: []