secretsweep 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec15ec1664c3323a4f84c7e234df7f45f4cd318c38b86c39e068da35f9af80ae
+  data.tar.gz: 199353f168d2ec5873496546b788fb5fa34f455a75ce698f4cf1ddfabd89806a
+SHA512:
+  metadata.gz: 614b09cb1147c57a9bab4ff1f3274af32d182470a42d6ee8fdd27daa97171e180d35965f2f03ea56f26ecdb87c816939e8ad0a8a3e1069d4f6d6b3535ac2af01
+  data.tar.gz: c60c7f54f78f32997565fbd8ed8ca6be614610c16287a6aa4587dace73800aa847eebd017e9a730bd516d34eac47ac39a5d8186412d3f5759d9d832f6fa6f4a3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Majd
+
+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,155 @@
+# SecretSweep
+
+**A dependency-free Ruby CLI that scans files and full git history for leaked secrets — API keys, tokens, private keys — using known-format patterns plus entropy analysis for everything else.**
+
+![Ruby](https://img.shields.io/badge/Ruby-3.0%2B-CC342D?logo=ruby&logoColor=white)
+![Dependencies](https://img.shields.io/badge/runtime_deps-zero-brightgreen)
+![Tests](https://img.shields.io/badge/tests-36_passing-brightgreen)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+## Why this exists
+
+Secrets leak into git repos constantly — a hardcoded API key committed
+"just for testing," a `.env` file that wasn't gitignored in time. The
+sneaky part: **removing the secret in the next commit does not remove it
+from git history.** Anyone with `git log -p` can still read it. This tool
+scans both the working tree and full history, and treats them as equally
+important.
+
+## How it works
+
+Two independent detection layers, deliberately kept separate:
+
+1. **Pattern matching** (`PatternRegistry`) — known formats: AWS keys,
+   GitHub/Slack/Stripe tokens, PEM private key headers, JWTs, and a
+   generic `key = "..."` assignment heuristic.
+2. **Entropy analysis** (`Entropy`) — Shannon entropy per character.
+   Catches secrets in formats with no dedicated pattern yet (a new
+   provider, an internal auth token) by flagging strings that are
+   "suspiciously random" rather than matching a specific shape.
+
+Both layers can flag the *same* secret independently — see
+[Known limitations](#known-limitations) below for why that's left as-is
+rather than "fixed."
+
+## Installation
+
+```bash
+git clone https://github.com/yourusername/SecretSweep.git
+cd SecretSweep
+bundle install
+gem build secretsweep.gemspec
+gem install ./secretsweep-0.1.0.gem
+```
+
+## Usage
+
+```bash
+# Scan the current directory's working tree
+secretsweep .
+
+# Also scan full git history (every branch)
+secretsweep . --history
+
+# Machine-readable output, e.g. for CI
+secretsweep . --format json
+
+# Use a specific ignore file
+secretsweep . --ignore-file .secretsweepignore
+```
+
+Exit codes: `0` = clean, `1` = secrets found, `2` = error (e.g. not a git
+repo when `--history` was requested).
+
+### Example output
+
+```
+$ secretsweep . --history
+Found 1 potential secret(s):
+
+  [aws_access_key_id] config.rb @ 010f580376fd
+    AKIA...MPLE  (fingerprint: 039a924b0920)
+
+To allowlist a confirmed false positive, add its fingerprint to .secretsweepignore
+```
+
+That example is real — it's what `secretsweep` reports against a test
+repo where an AWS key was committed and then "removed" in a later
+commit. The removal didn't help; the key is still readable in history.
+
+### Ignoring false positives
+
+Copy `.secretsweepignore.example` to `.secretsweepignore` in the
+directory you're scanning. Two kinds of entries:
+
+```
+# Skip scanning these paths entirely
+test/fixtures/**
+
+# Allowlist ONE specific confirmed false positive by its fingerprint
+# (does NOT silence the whole rule — just that exact file+type+snippet)
+a1b2c3d4e5f6
+```
+
+## Design decisions worth reading
+
+- **Two detection layers, kept intentionally separate.** Pattern
+  matching and entropy analysis never share code — a bug in one can't
+  silently break the other, and each is independently testable.
+- **Fingerprints, not line numbers, are the identity of a finding.**
+  A fingerprint is a hash of `source:type:snippet` — it survives the
+  file being edited above the secret, so an ignore-list entry doesn't
+  silently stop working the next time someone touches that file.
+- **The ignore list has two granularities on purpose.** A path glob
+  silences a whole directory (fixtures, generated files); a fingerprint
+  silences exactly one confirmed false positive. Collapsing these into
+  one mechanism would force a choice between "too broad" and "too
+  narrow" for different real situations.
+- **Git history scanning shells out to the real `git` binary** rather
+  than reimplementing pack-file parsing or depending on a native
+  extension gem — `git log -p --all` is well-tested, always available
+  wherever git itself is, and the output format is stable.
+- **Zero runtime dependencies.** The whole tool is Ruby stdlib
+  (`optparse`, `json`, `open3`, `digest`, `pathname`, `find`). Anyone can
+  `gem install` it with no dependency resolution at all.
+
+## Known limitations
+
+- **The same secret can be reported twice**, once by pattern matching
+  and once by entropy analysis, if it happens to satisfy both (e.g. a
+  GitHub token is both a recognized format *and* high-entropy). This is
+  left as-is rather than deduplicated across types: two independent
+  detectors agreeing is a legitimate confidence signal, and collapsing
+  it would hide which detector(s) actually fired. See
+  `docs/COMMIT_PLAN.md` for a possible future confidence-scoring
+  approach instead of outright deduplication.
+- **Entropy thresholds are heuristic**, not universally tuned — see
+  `docs/COMMIT_PLAN.md` Week 2 for the plan to validate them against a
+  larger real-world sample.
+- **History scanning reads the full diff of every commit on every
+  branch** (`git log -p --all`) — this is thorough but can be slow on
+  very large, long-lived repositories. No pagination/depth limit yet.
+
+## Testing
+
+```bash
+rake test
+```
+
+36 tests, zero dependencies beyond Ruby's bundled Minitest — no network
+access or external services required to run the suite. Includes a real
+integration test (`git_history_scanner_test.rb`) that creates an actual
+throwaway git repo, commits a secret, removes it in a later commit, and
+verifies `--history` still catches it.
+
+## Roadmap
+
+See [`docs/COMMIT_PLAN.md`](docs/COMMIT_PLAN.md) for the week-by-week build-out plan.
+
+## Tech stack
+
+Ruby 3.0+, standard library only. Minitest + Rake for testing.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/bin/secretsweep

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "secretsweep"
+
+exit SecretSweep::CLI.start(ARGV)

data/lib/secretsweep/cli.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module SecretSweep
+  # Thin CLI wrapper. Deliberately kept dumb — argument parsing and exit
+  # codes only, no scanning logic — so Scanner/FileScanner/etc. stay
+  # usable as a plain Ruby library, e.g. `require "secretsweep"` inside
+  # a Rake task, with no CLI involved at all.
+  class CLI
+    EXIT_CLEAN = 0
+    EXIT_SECRETS_FOUND = 1
+    EXIT_ERROR = 2
+
+    def self.start(argv)
+      new.run(argv)
+    end
+
+    def run(argv)
+      options = parse(argv)
+      path = options[:path] || "."
+
+      scanner = Scanner.new(path, ignore_file: options[:ignore_file], include_history: options[:history])
+      findings = scanner.run
+
+      puts Reporter.render(findings, format: options[:format])
+
+      findings.empty? ? EXIT_CLEAN : EXIT_SECRETS_FOUND
+    rescue GitHistoryScanner::NotAGitRepoError => e
+      warn "Error: #{e.message}"
+      EXIT_ERROR
+    rescue Errno::ENOENT => e
+      warn "Error: #{e.message}"
+      EXIT_ERROR
+    end
+
+    private
+
+    def parse(argv)
+      options = { format: :text, history: false }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: secretsweep [path] [options]"
+
+        opts.on("--history", "Also scan full git history, not just the working tree") do
+          options[:history] = true
+        end
+
+        opts.on("--format FORMAT", %w[text json], "Output format: text (default) or json") do |fmt|
+          options[:format] = fmt.to_sym
+        end
+
+        opts.on("--ignore-file PATH", "Path to a .secretsweepignore file (default: <path>/.secretsweepignore)") do |p|
+          options[:ignore_file] = p
+        end
+
+        opts.on("-v", "--version", "Print the version and exit") do
+          puts SecretSweep::VERSION
+          exit(0)
+        end
+
+        opts.on("-h", "--help", "Print this help") do
+          puts opts
+          exit(0)
+        end
+      end
+
+      remaining = parser.parse(argv)
+      options[:path] = remaining.first
+      options
+    end
+  end
+end

data/lib/secretsweep/entropy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SecretSweep
+  # Computes Shannon entropy of a string — a measure of "randomness" per
+  # character, in bits. Real secrets (API keys, tokens) tend to be
+  # high-entropy (close to random); English words, file paths, and normal
+  # code tend to be low-entropy. This catches secrets that don't match any
+  # known regex pattern — a purely regex-based scanner misses those.
+  module Entropy
+    module_function
+
+    def shannon(str)
+      return 0.0 if str.nil? || str.empty?
+
+      frequencies = Hash.new(0)
+      str.each_char { |c| frequencies[c] += 1 }
+
+      length = str.length
+      frequencies.values.reduce(0.0) do |entropy, count|
+        probability = count.to_f / length
+        entropy - (probability * Math.log2(probability))
+      end
+    end
+
+    # A candidate string is "suspiciously random" if its entropy per
+    # character exceeds this threshold. Tuned empirically: base64-like
+    # secrets tend to sit around 4.0-4.5 bits/char; English text sits
+    # around 3.5-4.0 for lowercase-heavy content but real code identifiers
+    # (snake_case, camelCase) tend lower still.
+    DEFAULT_THRESHOLD = 4.3
+
+    def high_entropy?(str, threshold: DEFAULT_THRESHOLD, min_length: 20)
+      return false if str.nil? || str.length < min_length
+
+      shannon(str) >= threshold
+    end
+  end
+end

data/lib/secretsweep/file_scanner.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "find"
+require "pathname"
+
+module SecretSweep
+  # Scans the current state of files on disk (as opposed to GitHistoryScanner,
+  # which scans past commits). Skips binary files and common noise
+  # directories so a full repo scan doesn't choke on node_modules or .git
+  # internals.
+  class FileScanner
+    SKIP_DIRS = %w[.git node_modules vendor tmp log dist build coverage .bundle].freeze
+    MAX_FILE_SIZE = 2 * 1024 * 1024 # 2MB — skip huge files (logs, binaries, lockfiles)
+
+    def initialize(root, ignore_list: IgnoreList.new([], []))
+      @root = root
+      @ignore_list = ignore_list
+    end
+
+    def scan
+      findings = []
+
+      each_scannable_file do |path|
+        relative_path = relative(path)
+        next if @ignore_list.path_ignored?(relative_path)
+
+        findings.concat(scan_file(path, relative_path))
+      end
+
+      findings
+    end
+
+    private
+
+    def each_scannable_file
+      Find.find(@root) do |path|
+        if File.directory?(path)
+          Find.prune if SKIP_DIRS.include?(File.basename(path))
+          next
+        end
+        next unless File.file?(path)
+        next if File.size(path) > MAX_FILE_SIZE
+        next if binary?(path)
+
+        yield path
+      end
+    end
+
+    def scan_file(path, relative_path)
+      findings = []
+
+      File.foreach(path).with_index(1) do |line, line_number|
+        # Guard per-line, not per-file: one malformed line (bad encoding,
+        # unexpected control characters) should never discard matches
+        # already found earlier in the same file.
+        begin
+          PatternRegistry.scan_line(line).each do |match|
+            findings << Finding.new(relative_path, line_number, match[:type], match[:snippet], nil)
+          end
+          check_high_entropy_tokens(line, relative_path, line_number, findings)
+        rescue ArgumentError, Encoding::InvalidByteSequenceError
+          next
+        end
+      end
+
+      findings
+    rescue ArgumentError, Encoding::InvalidByteSequenceError, Errno::ENOENT
+      # File wasn't actually readable/valid text despite passing the
+      # binary? heuristic (e.g. removed between listing and reading).
+      findings
+    end
+
+    # Beyond known patterns, flag bare high-entropy tokens assigned to a
+    # variable — catches secrets in formats we don't have a specific regex
+    # for yet (a new provider's token format, an internal auth token).
+    def check_high_entropy_tokens(line, relative_path, line_number, findings)
+      return unless line.match?(/=|:/)
+
+      line.scan(/['"]([A-Za-z0-9\/+_-]{20,})['"]/) do |match|
+        token = match[0]
+        next unless Entropy.high_entropy?(token)
+
+        findings << Finding.new(relative_path, line_number, "high_entropy_string", token, nil)
+      end
+    end
+
+    def relative(path)
+      Pathname.new(path).relative_path_from(Pathname.new(@root)).to_s
+    end
+
+    def binary?(path)
+      sample = File.open(path, "rb") { |f| f.read(512) }
+      return false if sample.nil?
+
+      sample.include?("\x00")
+    end
+  end
+end

data/lib/secretsweep/finding.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module SecretSweep
+  # A single detected secret. Immutable value object — findings are
+  # produced once and never mutated, only filtered (by IgnoreList) or
+  # rendered (by Reporter).
+  Finding = Struct.new(:source, :line_number, :type, :snippet, :commit) do
+    def fingerprint
+      # Stable identifier for this finding, used by the ignore list to
+      # allowlist a specific known false positive without silencing the
+      # entire rule everywhere else. Based on content, not line number,
+      # so it survives the file being edited above the secret.
+      Digest::SHA256.hexdigest("#{source}:#{type}:#{redacted_snippet}")[0, 12]
+    end
+
+    def redacted_snippet
+      return snippet if snippet.length <= 8
+
+      "#{snippet[0, 4]}...#{snippet[-4, 4]}"
+    end
+
+    def to_h
+      {
+        source: source,
+        line: line_number,
+        type: type,
+        snippet: redacted_snippet,
+        commit: commit,
+        fingerprint: fingerprint
+      }.compact
+    end
+  end
+end

data/lib/secretsweep/git_history_scanner.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module SecretSweep
+  # Scans git history — not just the working tree — because a secret
+  # deleted in the latest commit is still fully readable by anyone who
+  # runs `git log -p` or `git show <old-sha>`. This is the check that
+  # catches "I removed the key in the next commit" as still a real leak.
+  class GitHistoryScanner
+    class NotAGitRepoError < StandardError; end
+
+    def initialize(repo_path, ignore_list: IgnoreList.new([], []))
+      @repo_path = repo_path
+      @ignore_list = ignore_list
+    end
+
+    def scan
+      raise NotAGitRepoError, "#{@repo_path} is not a git repository" unless git_repo?
+
+      findings = []
+      current_file = nil
+      current_commit = nil
+
+      each_diff_line do |line|
+        if line.start_with?("commit ")
+          current_commit = line.split(" ", 2).last[0, 12]
+        elsif line.start_with?("+++ b/")
+          current_file = line.sub("+++ b/", "").strip
+        elsif line.start_with?("+") && !line.start_with?("+++")
+          content = line[1..]
+          next if current_file.nil? || @ignore_list.path_ignored?(current_file)
+
+          PatternRegistry.scan_line(content).each do |match|
+            findings << Finding.new(current_file, nil, match[:type], match[:snippet], current_commit)
+          end
+        end
+      end
+
+      findings
+    end
+
+    private
+
+    def git_repo?
+      _out, status = Open3.capture2("git", "-C", @repo_path, "rev-parse", "--is-inside-work-tree")
+      status.success?
+    end
+
+    def each_diff_line
+      # -p: show patches (actual added/removed lines), --all: every branch,
+      # not just the currently checked-out one — a secret on a stale
+      # feature branch is still a leak.
+      Open3.popen2("git", "-C", @repo_path, "log", "-p", "--all", "--no-color") do |_in, out, _thread|
+        out.each_line { |line| yield line }
+      end
+    end
+  end
+end

data/lib/secretsweep/ignore_list.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module SecretSweep
+  # Parses a .secretsweepignore file with two kinds of entries:
+  #   - a bare glob pattern (e.g. `spec/fixtures/**`) skips scanning those
+  #     paths entirely
+  #   - a 12-char fingerprint (as printed in a Finding's report) allowlists
+  #     that ONE specific known false positive, not the whole rule
+  #
+  # This distinction matters: silencing an entire secret TYPE because one
+  # file has a false positive would blind the scanner everywhere else.
+  class IgnoreList
+    def self.load(path)
+      return new([], []) unless path && File.exist?(path)
+
+      globs = []
+      fingerprints = []
+
+      File.readlines(path).each do |raw_line|
+        line = raw_line.strip
+        next if line.empty? || line.start_with?("#")
+
+        if line.match?(/\A[0-9a-f]{12}\z/)
+          fingerprints << line
+        else
+          globs << line
+        end
+      end
+
+      new(globs, fingerprints)
+    end
+
+    def initialize(path_globs, fingerprints)
+      @path_globs = path_globs
+      @fingerprints = fingerprints
+    end
+
+    def path_ignored?(path)
+      @path_globs.any? { |glob| File.fnmatch(glob, path, File::FNM_PATHNAME | File::FNM_EXTGLOB) }
+    end
+
+    def finding_ignored?(finding)
+      @fingerprints.include?(finding.fingerprint)
+    end
+
+    def reject_ignored(findings)
+      findings.reject { |f| finding_ignored?(f) }
+    end
+  end
+end

data/lib/secretsweep/pattern_registry.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SecretSweep
+  # Known secret formats, keyed by a short type name. Each pattern is
+  # intentionally specific (not a generic "any long string" catch-all —
+  # that's what Entropy.high_entropy? is for) to keep false positives low
+  # for the formats we DO recognize.
+  module PatternRegistry
+    PATTERNS = {
+      "aws_access_key_id" => /\bAKIA[0-9A-Z]{16}\b/,
+      "aws_secret_access_key" => /\baws(.{0,20})?(secret|access)[_-]?key\b.{0,5}['"]([A-Za-z0-9\/+=]{40})['"]/i,
+      "github_token" => /\bgh[pousr]_[A-Za-z0-9]{36,}\b/,
+      "slack_token" => /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/,
+      "stripe_live_key" => /\bsk_live_[A-Za-z0-9]{24,}\b/,
+      "stripe_test_key" => /\bsk_test_[A-Za-z0-9]{24,}\b/,
+      "generic_private_key" => /-----BEGIN (RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/,
+      "google_api_key" => /\bAIza[0-9A-Za-z\-_]{35}\b/,
+      "generic_api_key_assignment" =>
+        /\b(api[_-]?key|secret|token|password|passwd|pwd)\b\s*[:=]\s*['"][A-Za-z0-9\/+=_\-]{16,}['"]/i,
+      "jwt" => /\bey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/
+    }.freeze
+
+    # Lines matching any of these are skipped entirely before pattern
+    # matching runs — cuts down on noise from example/placeholder values
+    # that would otherwise trip the generic_api_key_assignment pattern.
+    #
+    # "your_api_key" and "xxxx+" are deliberately NOT wrapped in a trailing
+    # \b: that phrase commonly appears glued to surrounding text via
+    # underscores (e.g. "your_api_key_goes_here"), and \b never fires
+    # between two word characters — underscore counts as one — so a
+    # trailing boundary there would silently fail to match exactly the
+    # placeholder text it exists to catch.
+    PLACEHOLDER_HINTS = /\b(example|placeholder|changeme|dummy|fake|sample)\b|your[_-]?api[_-]?key|xxxx+/i
+
+    # Returns an array of { type:, snippet: } hashes for every match found
+    # in the line. The snippet is the full matched text — callers (e.g.
+    # Finding) are responsible for redacting it before display/storage.
+    def self.scan_line(line)
+      # Defensively normalize encoding: a file read outside a UTF-8 locale
+      # (e.g. LANG unset) can hand us a string whose declared encoding
+      # doesn't match its bytes, which makes regex matching raise instead
+      # of just returning "no match". `scrub` replaces invalid byte
+      # sequences so scanning degrades gracefully instead of aborting the
+      # whole file's scan.
+      line = line.to_s.scrub
+      return [] if line.match?(PLACEHOLDER_HINTS)
+
+      PATTERNS.each_with_object([]) do |(type, regex), matches|
+        line.scan(regex) { matches << { type: type, snippet: Regexp.last_match(0) } }
+      end
+    end
+  end
+end

data/lib/secretsweep/reporter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SecretSweep
+  # Renders a list of Findings for human or machine consumption. Kept
+  # separate from Scanner so output format never leaks into detection
+  # logic — adding a new format (e.g. SARIF for GitHub code scanning)
+  # means touching only this file.
+  module Reporter
+    module_function
+
+    def render(findings, format: :text)
+      case format
+      when :json then render_json(findings)
+      else render_text(findings)
+      end
+    end
+
+    def render_text(findings)
+      return "No secrets found.\n" if findings.empty?
+
+      lines = ["Found #{findings.size} potential secret(s):", ""]
+      findings.each do |f|
+        location = f.commit ? "#{f.source} @ #{f.commit}" : "#{f.source}:#{f.line_number}"
+        lines << "  [#{f.type}] #{location}"
+        lines << "    #{f.redacted_snippet}  (fingerprint: #{f.fingerprint})"
+      end
+      lines << ""
+      lines << "To allowlist a confirmed false positive, add its fingerprint to .secretsweepignore"
+      "#{lines.join("\n")}\n"
+    end
+
+    def render_json(findings)
+      JSON.pretty_generate(
+        count: findings.size,
+        findings: findings.map(&:to_h)
+      )
+    end
+  end
+end

data/lib/secretsweep/scanner.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module SecretSweep
+  # Public entry point for running a scan. Combines FileScanner and
+  # (optionally) GitHistoryScanner, applies the ignore list once at the
+  # end so both scanners share identical allowlisting behavior instead of
+  # each reimplementing it.
+  class Scanner
+    def initialize(path, ignore_file: nil, include_history: false)
+      @path = File.expand_path(path)
+      @ignore_list = IgnoreList.load(ignore_file || default_ignore_path)
+      @include_history = include_history
+    end
+
+    def run
+      findings = FileScanner.new(@path, ignore_list: @ignore_list).scan
+
+      if @include_history
+        findings.concat(GitHistoryScanner.new(@path, ignore_list: @ignore_list).scan)
+      end
+
+      dedupe(@ignore_list.reject_ignored(findings))
+    end
+
+    private
+
+    def default_ignore_path
+      candidate = File.join(@path, ".secretsweepignore")
+      File.exist?(candidate) ? candidate : nil
+    end
+
+    # The same secret often appears in both the working tree AND history
+    # (e.g. it's still there right now). Collapse to one entry per unique
+    # fingerprint so the report doesn't double-count it, while keeping the
+    # entry with the most specific location.
+    def dedupe(findings)
+      findings.group_by(&:fingerprint).map { |_fp, group| group.first }
+    end
+  end
+end

data/lib/secretsweep/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SecretSweep
+  VERSION = "0.1.0"
+end

data/lib/secretsweep.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "secretsweep/version"
+require_relative "secretsweep/entropy"
+require_relative "secretsweep/pattern_registry"
+require_relative "secretsweep/finding"
+require_relative "secretsweep/ignore_list"
+require_relative "secretsweep/file_scanner"
+require_relative "secretsweep/git_history_scanner"
+require_relative "secretsweep/reporter"
+require_relative "secretsweep/scanner"
+require_relative "secretsweep/cli"
+
+module SecretSweep
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: secretsweep
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Majd
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+description: |
+  SecretSweep scans a codebase (and optionally its full git history) for
+  leaked secrets — API keys, tokens, private keys — using a combination
+  of known-format regex patterns and Shannon entropy analysis for
+  unknown formats. Pure Ruby standard library, zero runtime dependencies.
+executables:
+- secretsweep
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/secretsweep
+- lib/secretsweep.rb
+- lib/secretsweep/cli.rb
+- lib/secretsweep/entropy.rb
+- lib/secretsweep/file_scanner.rb
+- lib/secretsweep/finding.rb
+- lib/secretsweep/git_history_scanner.rb
+- lib/secretsweep/ignore_list.rb
+- lib/secretsweep/pattern_registry.rb
+- lib/secretsweep/reporter.rb
+- lib/secretsweep/scanner.rb
+- lib/secretsweep/version.rb
+homepage: https://github.com/yourusername/SecretSweep
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.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: A dependency-free CLI that scans files and git history for leaked secrets.
+test_files: []