Module: Leakferret

Defined in:
lib/leakferret.rb,
lib/leakferret/error.rb,
lib/leakferret/binary.rb,
lib/leakferret/client.rb,
lib/leakferret/version.rb,
lib/leakferret/platform.rb

Overview

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.

Examples:

Scan the working tree

Leakferret.scan(".").each do |f|
  puts "#{f['path']}:#{f['line']} #{f['pattern']} [#{f['verdict']}]"
end

Fail a script on any live secret

exit(1) unless Leakferret.verify(".", mode: "only-verified").empty?

See Also:

Defined Under Namespace

Modules: Binary, Platform Classes: BinaryInvocationError, BinaryNotFoundError, Client, Error

Constant Summary collapse

VERSION =

The gem's own version (what gem install leakferret resolves).

Returns:

  • (String) 
'0.1.10'
BINARY_VERSION =

The native binary release this gem downloads and runs. Tracks the leakferret core release and can move independently of VERSION (e.g. a gem-only bugfix keeps the same binary).

Returns:

  • (String) 
'0.1.6'

Class Method Summary collapse

Class Method Details

.binary_path ⇒ String

Absolute path to the native binary, downloading it on first use.

Returns:

  • (String) —

    absolute filesystem path to the leakferret executable

Raises:



89
90
91
 
# File 'lib/leakferret.rb', line 89

def binary_path
  Binary.path
end

.binary_version ⇒ String

Version string reported by the bundled native binary. May differ from VERSION (the gem's own version) during pre-release; see BINARY_VERSION.

Returns:

  • (String) —

    the binary's --version output, stripped



97
98
99
100
 
# File 'lib/leakferret.rb', line 97

def binary_version
  out, _err, _status = Open3.capture3(binary_path, '--version')
  out.strip
end

.rewrite(path = '.', apply: false, **opts) ⇒ Array<Hash>

Scan, classify, and propose environment-variable rewrites for real findings. Pass apply: true to write the rewrites to disk in place.

Examples:

Apply rewrites and seed Doppler

Leakferret.rewrite(".", apply: true, backend: "doppler")

Parameters:

  • path (String) (defaults to: '.') —

    file or directory to scan

  • apply (Boolean) (defaults to: false) —

    when true, edit files in place; otherwise only propose the replacements

  • opts (Hash) —

    a customizable set of options

Options Hash (**opts):

  • :backend (String) — default: "env" —

    rewrite backend, e.g. env, doppler

Returns:

  • (Array<Hash>) —

    findings, each with a replacement proposal attached

Raises:



81
82
83
 
# File 'lib/leakferret.rb', line 81

def rewrite(path = '.', apply: false, **opts)
  Client.new.rewrite(path, apply: apply, **opts)
end

.scan(path = '.', **opts) ⇒ Array<Hash>

Scan a path for candidate secrets. This is the regex pre-filter only (no classification, no verification): the fastest, fully offline pass.

Examples:

Leakferret.scan("app/", exclude: ["**/*_test.rb"])

Parameters:

  • path (String) (defaults to: '.') —

    file or directory to scan, relative or absolute

  • opts (Hash) —

    a customizable set of options

Options Hash (**opts):

  • :exclude (Array<String>) —

    glob(s) to skip

  • :only (Array<String>, String) —

    restrict the scan to these path(s)

  • :show_fixtures (Boolean) — default: false —

    include catalog fixtures in the result

Returns:

  • (Array<Hash>) —

    candidate findings, each with path, line, pattern, verdict, and match_redacted keys

Raises:



48
49
50
 
# File 'lib/leakferret.rb', line 48

def scan(path = '.', **opts)
  Client.new.scan(path, **opts)
end

.verify(path = '.', **opts) ⇒ Array<Hash>

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.

Examples:

Only return secrets confirmed live

Leakferret.verify(".", mode: "only-verified")

Parameters:

  • path (String) (defaults to: '.') —

    file or directory to scan

  • opts (Hash) —

    a customizable set of options

Options Hash (**opts):

  • :mode (String) — default: "best-effort" —

    verify mode: none, best-effort, only-verified, or ever-verified

  • :timeout (Integer) — default: 10 —

    per-verifier timeout in seconds

  • :exclude (Array<String>) —

    glob(s) to skip

  • :only (Array<String>, String) —

    restrict the scan to these path(s)

Returns:

  • (Array<Hash>) —

    findings with verdict and verification filled in

Raises:



66
67
68
 
# File 'lib/leakferret.rb', line 66

def verify(path = '.', **opts)
  Client.new.verify(path, **opts)
end