leakferret 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77f46588fbab40b45095c4654047ef78ab41203036e77e3df34e6c0af9396777
+  data.tar.gz: '079c0db268161032b79eac1e49fee61f785aa334a242680f95d7c8a7d260d8f7'
+SHA512:
+  metadata.gz: 89f676f8d255335e83d820a5c962a723cc6434039b56180e2e0bdddcb017bc2d03d765139a00fe5827e6c1b82125a351617bd0cec8a225d9332e76f18231c339
+  data.tar.gz: 151b37249dbf4a8d743bc142d8dfb0815a16e5a7833be451dfa0640316026d21fa36e5215785552e683693594f4ed1bc614145401235edccb29fcc8a4aa62736

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,123 @@
+<p align="center">
+  <img src="assets/logo.png" alt="leakferret" width="380">
+</p>
+
+# leakferret (Ruby gem)
+
+> MCP-native secret scanner — verified findings, agent-applied rewrites.
+
+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 a small executable, and downloads the prebuilt, statically-linked
+binary (written in Rust) from GitHub Releases once per platform at install
+time. All the work — scan, classify, verify, rewrite — happens in that single
+binary.
+
+This is the same packaging pattern used by `ruff`, `biome`, and `esbuild`:
+distributing the toolchain to build a Rust engine on every machine is
+unfriendly, so we ship the compiled engine instead.
+
+## 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
+```
+
+This downloads `leakferret-{version}-{platform}.tar.gz` from GitHub Releases and
+unpacks the binary into `lib/leakferret/bin/`.
+
+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`,
+`verdict`, `match_redacted`, `confidence`, `verification`, and `fingerprint`.
+
+## 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.
+
+## 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/ext/leakferret/extconf.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Best-effort install-time pre-fetch of the native binary into the
+# user-writable cache (see lib/leakferret/binary.rb). This is purely an
+# optimisation so the first invocation is instant — the binary is also
+# downloaded lazily on first use, so a failure here is harmless. Set
+# LEAKFERRET_SKIP_DOWNLOAD to skip the pre-fetch.
+#
+# We deliberately do NOT compile the Rust source: that would force every
+# user to have a Rust toolchain and wait for a long build. The
+# download-binary model matches ruff (Python), biome/esbuild (npm).
+
+require_relative '../../lib/leakferret/version'
+require_relative '../../lib/leakferret/platform'
+require_relative '../../lib/leakferret/error'
+require_relative '../../lib/leakferret/binary'
+
+# Emit an empty Makefile so rubygems considers the "extension" built.
+File.write('Makefile', "all:\n\t@true\ninstall:\n\t@true\nclean:\n\t@true\n")
+
+def log(msg)
+  warn "[leakferret/extconf] #{msg}"
+end
+
+if ENV['LEAKFERRET_SKIP_DOWNLOAD']
+  log 'LEAKFERRET_SKIP_DOWNLOAD set; binary will be downloaded on first use.'
+  exit 0
+end
+
+begin
+  path = Leakferret::Binary.ensure!
+  log "binary ready at #{path}"
+rescue StandardError => e
+  log "pre-fetch failed (#{e.class}: #{e.message}); it will download on first use."
+end
+
+# Always succeed: a failed pre-fetch must not fail the gem install.
+exit 0

data/lib/leakferret/binary.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+require_relative 'version'
+require_relative 'platform'
+require_relative 'error'
+
+module Leakferret
+  # Resolves (and, if needed, downloads) the native `leakferret` binary.
+  #
+  # The binary is fetched into an absolute, user-writable cache directory
+  # rather than into the gem's own tree. RubyGems builds extensions in a
+  # throwaway temp dir, so anything written relative to the gem during
+  # `gem install` is discarded — the cache path sidesteps that entirely and
+  # also lets a plain `gem install` (no extension) work.
+  module Binary
+    # A binary vendored inside the gem, if one was shipped (normally empty).
+    BUNDLED_DIR = Pathname.new(__dir__).join('bin').freeze
+
+    module_function
+
+    # Absolute path to the native binary, downloading it on first use if
+    # necessary. Resolution order:
+    #   1. LEAKFERRET_BIN          — explicit override
+    #   2. lib/leakferret/bin/     — a binary vendored in the gem
+    #   3. the per-version cache   — fetched on a prior run or at install
+    #   4. download into the cache now
+    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)
+      return bundled.to_s if bundled.file?
+
+      return cache_path.to_s if cache_path.file?
+
+      ensure!
+      raise BinaryNotFoundError, install_instructions(cache_path) unless cache_path.file?
+
+      cache_path.to_s
+    end
+
+    # User-writable cache directory, namespaced by the binary version so a
+    # gem upgrade fetches a fresh binary instead of reusing a stale one.
+    def cache_dir
+      base =
+        if Platform.windows?
+          ENV['LOCALAPPDATA'] || File.join(Dir.home, 'AppData', 'Local')
+        else
+          ENV['XDG_CACHE_HOME'] || File.join(Dir.home, '.cache')
+        end
+      Pathname.new(base).join('leakferret', BINARY_VERSION)
+    end
+
+    def cache_path
+      cache_dir.join(Platform.binary_name)
+    end
+
+    def download_url
+      'https://github.com/leakferrethq/leakferret/releases/download/' \
+        "v#{BINARY_VERSION}/leakferret-#{BINARY_VERSION}-#{Platform.triple}.tar.gz"
+    end
+
+    # Download and unpack the binary into the cache. Idempotent: a no-op when
+    # the binary is already cached. Returns the path; raises on failure.
+    def ensure!
+      dest = cache_path
+      return dest.to_s if dest.file?
+
+      require 'fileutils'
+      require 'open-uri'
+      require 'zlib'
+      require 'rubygems/package'
+
+      FileUtils.mkdir_p(dest.dirname)
+      # Stream download -> gunzip -> untar in pure Ruby (no external `tar`,
+      # which on Windows mis-reads `C:\` as a remote host). The archive nests
+      # everything under leakferret-<version>-<triple>/, so match by basename.
+      found = false
+      URI.open(download_url) do |io| # rubocop:disable Security/Open
+        Zlib::GzipReader.wrap(io) do |gz|
+          Gem::Package::TarReader.new(gz) do |tar|
+            tar.each do |entry|
+              next unless entry.file?
+              next unless File.basename(entry.full_name) == Platform.binary_name
+
+              File.binwrite(dest, entry.read)
+              found = true
+            end
+          end
+        end
+      end
+      raise BinaryNotFoundError, "binary not found inside #{download_url}" unless found
+
+      FileUtils.chmod(0o755, dest) unless Platform.windows?
+      dest.to_s
+    end
+
+    def install_instructions(candidate)
+      <<~MSG
+        leakferret native binary not found, and the automatic download failed.
+
+        Expected it at:
+          #{candidate}
+
+        Download the binary for your platform from:
+          https://github.com/leakferrethq/leakferret/releases
+
+        then either place it at the path above or point LEAKFERRET_BIN at it.
+      MSG
+    end
+  end
+end

data/lib/leakferret/client.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+module Leakferret
+  # Thin shell-out wrapper. Each public method invokes the binary with
+  # `--format json` and parses the resulting array.
+  class Client
+    def scan(path, exclude: [], only: nil, show_fixtures: false)
+      run(['scan', path, '--format', 'json'] + format_flags(exclude:, only:, show_fixtures:))
+    end
+
+    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
+
+    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
+
+    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
+
+    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,15 @@
+# frozen_string_literal: true
+
+module Leakferret
+  class Error < StandardError; end
+  class BinaryNotFoundError < Error; end
+  class BinaryInvocationError < Error
+    attr_reader :exit_status, :stderr
+
+    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,40 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+
+require_relative 'error'
+
+module Leakferret
+  module Platform
+    module_function
+
+    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
+
+    def binary_name
+      windows? ? 'leakferret.exe' : 'leakferret'
+    end
+
+    def windows?
+      RbConfig::CONFIG['host_os'] =~ /mswin|mingw|cygwin/
+    end
+  end
+end

data/lib/leakferret/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Leakferret
+  # The gem's own version.
+  VERSION = '0.1.3'
+
+  # The native binary release this gem downloads. Tracks the leakferret
+  # core release, which may move independently of the gem's own version
+  # (e.g. a gem-only bugfix).
+  BINARY_VERSION = '0.1.1'
+end

data/lib/leakferret.rb

@@ -0,0 +1,48 @@
+# 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` binary.
+#
+# The binary is downloaded once per platform at gem install time
+# (`ext/leakferret/extconf.rb`) into `lib/leakferret/bin/`. Subsequent
+# calls shell out to it and parse the JSON output.
+module Leakferret
+  class << self
+    # Scan a directory; returns an array of finding hashes.
+    def scan(path = '.', **opts)
+      Client.new.scan(path, **opts)
+    end
+
+    # Scan + verify + classify; returns findings with verification +
+    # verdict filled in.
+    def verify(path = '.', **opts)
+      Client.new.verify(path, **opts)
+    end
+
+    # Scan + classify + propose rewrites for REAL findings. Use
+    # apply: true to write the rewrites in place.
+    def rewrite(path = '.', apply: false, **opts)
+      Client.new.rewrite(path, apply: apply, **opts)
+    end
+
+    # Path to the bundled binary. Useful for tooling integration.
+    def binary_path
+      Binary.path
+    end
+
+    # Version reported by the bundled binary (Rust) — may differ from
+    # the gem version during pre-release.
+    def binary_version
+      out, _err, _status = Open3.capture3(binary_path, '--version')
+      out.strip
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: leakferret
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: ruby
+authors:
+- Maria Khan
+bindir: exe
+cert_chain: []
+date: 1980-01-02 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. The platform binary is
+  downloaded automatically on first use, so no Rust toolchain is required.
+
+  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:
+- ext/leakferret/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/leakferret
+- ext/leakferret/extconf.rb
+- lib/leakferret.rb
+- 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
+  rubygems_mfa_required: 'true'
+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.6.9
+specification_version: 4
+summary: Context-aware secret detection (Ruby wrapper for the leakferret binary).
+test_files: []