leakless 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bd6f5b211ad396db44eaf4b45609debe5f7ae536ba35578e0c17cee12dcd612d
+  data.tar.gz: 120fd84a65818fcf740ed1d4e94c5b7e7d3b0a458d0390d9c2b901851993c5ce
+SHA512:
+  metadata.gz: dfe5a15dddb34990e7ee5cbbc5cad90bbd8c13c5bf84ab1685c793e375f16259784feb3c8dff35e8b4c16d9d1cd49ec0261b5bbb98e62627b0f9d4daefb41e0f
+  data.tar.gz: 8c593ba6521db2f2f1e48ec81237c371435c3566fe759ad199983281ea6ef356efe8ee36816d6998ef878c86880025a66cd4c8addeb070f04a63129ad10dea94

data/.ruby-version

@@ -0,0 +1 @@
+3.4.10

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+## [Unreleased]
+
+## [0.3.0] - 2026-07-27
+
+- Gem renamed from `sharekit-cli` to `leakless`. Module `Sharekit::Cli` is now
+  `Leakless::Cli`, the executable is now `leakless`, and the repository moved to
+  `github.com/LucasSantana-Dev/leakless`. No behavior changes. `sharekit-cli`
+  0.2.0 remains on RubyGems as the final release under the old name.
+
+## [0.2.0] - 2026-07-26
+
+- `scan --ai-triage` labels each finding `true_positive`, `false_positive` or
+  `uncertain` with a confidence and a one-line rationale, via RubyLLM structured
+  output. Works against any RubyLLM provider; `--provider ollama` needs no setup.
+- `ruby_llm` is an **optional** dependency, not a runtime one: `scan` alone pulls
+  nothing new, and `--ai-triage` without it reports how to install it. Run
+  `gem install ruby_llm` to enable triage.
+- Secret values are never transmitted, and there is no opt-out. Findings are
+  reduced to their shape (length plus Shannon entropy) before the prompt is
+  built. See `docs/adr/2026-07-26-redact-always-ai-triage.md`.
+- Verdicts are advisory: the high-severity gate ignores them.
+
+## [0.1.0] - 2026-07-25
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Lucas Santana
+
+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,145 @@
+# leakless
+
+A small CLI that scaffolds a publishable "AI coding setup" profile and scans a directory for
+leaked secrets — private keys, cloud/API tokens, sensitive env vars — blocking on high-severity
+findings unless you pass `--force`.
+
+It's a Ruby port of the `init` and `scan` commands from
+[sharekit](https://github.com/LucasSantana-Dev/sharekit), a TypeScript CLI I built and publish
+to npm. This port is deliberately not a line-for-line translation — it's rebuilt around Ruby
+idioms that don't have a clean TS equivalent:
+
+- **`Data.define`** for the immutable `Finding` value object, with `Comparable` mixed in for
+  free severity-ranked sorting, and free `Hash` deconstruction for pattern matching.
+- **A rule table, not an if/elsif chain.** Each secret pattern is a `Scanner::Rule` (a `Data`
+  object: pattern + severity + preview metadata), stored in a frozen array. Adding a rule means
+  appending to `RULES` — the scan loop itself never changes.
+- **`Enumerator` dual API.** `Scanner.scan` yields to a block when one is given, or returns an
+  `Enumerator` when it isn't (`return to_enum(:scan, ...) unless block_given?`) — the same
+  pattern as `Array#each`. Callers can stream (`each { }`) or collect (`.to_a`, `.first`, `.lazy`)
+  without the scanner caring which.
+- **`case/in` pattern matching** in `Reporter.format_line`, matching directly on the `Finding`'s
+  deconstructed fields instead of manual attribute access.
+- **`Data#with` for the triage pass.** Verdicts are layered onto findings by returning new
+  `Finding`s, so the scan result is never mutated and an untriaged finding is structurally
+  the same object it always was. The triage fields default to `nil` via a keyword-splat
+  `super`, which is how `Data.define` takes defaults at all.
+- **`autoload` for the AI path.** `require "ruby_llm"` pulls in a provider stack that a plain
+  `scan` never touches, so `Triage` is resolved on first reference. One stdlib line instead of
+  an optional-dependency dance.
+- **Thor** for CLI dispatch instead of hand-parsed `ARGV`/flags.
+- **`git ls-files`, not a hand-rolled ignore-file parser.** `scan` defers to git for
+  `.gitignore`-aware file listing when run inside a repo (via `Open3`, argv-array — no shell
+  interpolation), instead of reimplementing gitignore match semantics.
+
+## Install
+
+```bash
+gem install leakless
+```
+
+Or add to a `Gemfile`:
+
+```ruby
+gem "leakless"
+```
+
+## Usage
+
+```bash
+leakless scan [DIR]          # scan a directory (default: .)
+leakless scan [DIR] --force  # don't block on high-severity findings
+
+leakless init [SKILL...]              # scaffold ./sharekit-profile
+leakless init --dir PATH [SKILL...]   # scaffold at a custom path
+leakless init --force                 # overwrite an existing dir; override secret blocking
+```
+
+```
+$ leakless scan .
+
+  ⚠  Secret patterns detected:
+    .env:1 [AWS Access Key ID] …Y=AKIAEXAMPLEKEY000000
+
+  ⚠  Review and redact secrets before pushing to a public repository.
+
+Secrets export blocked: 1 high-severity finding(s) detected. Review and remove secrets, or re-run with --force to override.
+```
+
+Both commands exit `1` when a high-severity secret is found and `--force` wasn't passed; `0`
+otherwise. `init` copies `~/.claude/CLAUDE.md` and `~/.cursor/.cursorrules` into the new profile
+(or writes placeholders if they don't exist) and scans everything it copies for secrets before
+reporting success.
+
+### AI triage
+
+`--ai-triage` labels each finding as a real leak, a placeholder, or unclear, so a docs
+sample stops looking exactly like a live key.
+
+It needs one extra gem, which `scan` itself does not:
+
+```bash
+gem install ruby_llm
+```
+
+That is deliberate. A secret scanner shouldn't drag a provider stack into every install, so
+`ruby_llm` is optional: `leakless scan` never loads it, and `--ai-triage` without it fails
+with instructions rather than a `LoadError`.
+
+```bash
+leakless scan --ai-triage                                        # any configured provider
+leakless scan --ai-triage --provider ollama --model qwen3:4b \
+                  --assume-model-exists                              # fully local
+```
+
+```text
+  ⚠  Secret patterns detected:
+    config/secrets.env:1 [AWS Access Key ID] …_KEY=AKIAEXAMPLEKEY000000
+      → likely real (95% confident) Config path, not a test or docs fixture.
+    docs/example.md:3 [AWS Access Key ID] …ple `AKIAIOSFODNN7EXAMPLE…
+      → likely placeholder (98% confident) Documentation path, context says "for example".
+
+  ⚠  AI verdicts are advisory: the high-severity gate ignores them.
+```
+
+**Secret values are never sent, and there is no flag to send them.** Before a prompt is
+built, each finding's line is re-read from disk and every secret in it is replaced by its
+shape alone, as `[REDACTED chars=20 entropy=3.8]`. What the model gets is the rule name,
+the path, the line number, that shape, and whatever context survived. Redaction runs on the
+whole line rather than the truncated `preview` for a reason: truncation can cut a secret so
+that its own rule no longer matches it, and the fragment would survive. Reasoning is in
+[the ADR](docs/adr/2026-07-26-redact-always-ai-triage.md).
+
+Credentials come from `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`. `--provider ollama` needs
+neither and defaults to `http://localhost:11434/v1` (override with `OLLAMA_API_BASE`), which
+keeps even the redacted shape on your machine.
+
+Verdicts annotate; they never unblock. A model deciding a live key isn't a key is not a
+failure mode worth having, so the gate stays independent of it.
+
+### Rules
+
+| Rule                          | Severity |
+|--------------------------------|----------|
+| Private Key Block              | high     |
+| AWS Access Key ID              | high     |
+| GitHub Personal Access Token   | high     |
+| Slack Token                    | high     |
+| Google API Key                 | high     |
+| Bearer Token (JWT)             | high     |
+| Home Directory Path Leak       | low      |
+| Env Var: Sensitive Key         | medium   |
+
+## Development
+
+```bash
+bin/setup                            # install dependencies
+bundle exec rspec                    # run the test suite (92 examples)
+bundle exec rubocop                  # lint
+bundle exec bundler-audit check --update  # dependency vulnerability scan
+bin/console                          # interactive prompt
+```
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/adr/2026-07-26-redact-always-ai-triage.md

@@ -0,0 +1,57 @@
+# Redact always in AI triage
+
+- Status: accepted
+- Date: 2026-07-26
+
+## Context
+
+`scan` is rule-driven, so it reports what a regex matched, not what the match
+means. `AKIAIOSFODNN7EXAMPLE` in `docs/example.md` and a live key in
+`config/secrets.env` produce the same high-severity finding, and the gate blocks
+on both. Classifying findings needs a model, which means deciding what a secret
+scanner is allowed to transmit about the secrets it just found.
+
+The tool's whole promise is that it runs before you publish something. Sending
+credentials to a third-party API in order to ask whether they are credentials
+would invert that promise, and "we only send it when you pass `--raw`" still
+ships a foot-gun in a security tool.
+
+## Decision
+
+Triage sends a finding's shape, never its value, with no opt-out.
+
+- Every payload line is passed through `Redactor` first. A masked token is
+  replaced by its length and Shannon entropy, e.g. `[REDACTED chars=20
+  entropy=3.8]`.
+- Redaction runs against the line re-read from disk, not the `Finding`'s
+  `preview`. Truncation can cut a secret mid-token so its own rule no longer
+  matches it, and the surviving fragment would ride along into the prompt.
+- Every `Scanner` rule is applied, not just the one that produced the finding,
+  so a second secret sharing the line is masked too. Sensitive env-var values are
+  masked by key name, and a generic backstop masks any remaining run of 20+
+  characters from the secret alphabet.
+- `--provider ollama` works with no configuration, so the redacted shape can stay
+  on the machine as well.
+- Verdicts are advisory. The high-severity gate ignores them.
+
+## Consequences
+
+Classification accuracy is lower than it would be with raw values: the model
+judges from rule name, path, line number, entropy and surviving context. That
+turned out to be enough on the cases that matter, because the strongest signal is
+the path (`docs/`, `spec/`, `*.example`) rather than the characters.
+
+The generic backstop is deliberately over-eager. It masks long URLs, hashes and
+base64 in prose, which makes some prompts noisier than necessary. Safety over
+prompt tidiness: the claim "nothing 20 characters or longer from the secret
+alphabet survives" is only true if it applies to material no rule claimed.
+
+Keeping the gate model-independent means a false `false_positive` cannot unblock
+a publish. It also means triage does not reduce the work when the verdict is
+right, it only tells you where to look first. Letting verdicts relax the gate is
+the obvious next request; it stays refused.
+
+## Revisit when
+
+Someone needs triage to change the exit code, or a provider offers an
+attestable-local guarantee strong enough to reconsider what may be transmitted.

data/exe/leakless

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "leakless"
+
+Leakless::Cli::App.start(ARGV)

data/lib/leakless/file_lister.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Leakless
+  module Cli
+    # Picks which files a scan should look at. Inside a git repo, defers to
+    # `git ls-files` (tracked + untracked-but-not-ignored) so .gitignore is
+    # respected for free instead of reimplementing its match semantics.
+    # Outside a git repo, falls back to a plain glob with noise directories
+    # excluded.
+    module FileLister
+      DEFAULT_EXCLUDED_DIRS = %w[.git node_modules vendor .bundle].freeze
+
+      module_function
+
+      def list(dir)
+        git_tracked_files(dir) || glob_files(dir)
+      end
+
+      # Returns nil (not an empty array) when +dir+ isn't inside a git repo or
+      # git isn't installed, so the caller falls back to glob_files instead of
+      # silently scanning nothing.
+      def git_tracked_files(dir)
+        out, status = Open3.capture2("git", "-C", dir, "ls-files", "--cached", "--others", "--exclude-standard")
+        return nil unless status.success?
+
+        out.lines.map { |line| File.join(dir, line.chomp) }
+      rescue Errno::ENOENT
+        nil
+      end
+
+      def glob_files(dir)
+        Dir.glob("#{dir}/**/*").select { |path| File.file?(path) && !excluded?(path) }
+      end
+
+      def excluded?(path)
+        DEFAULT_EXCLUDED_DIRS.any? { |dir_name| path.split(File::SEPARATOR).include?(dir_name) }
+      end
+    end
+  end
+end

data/lib/leakless/finding.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Leakless
+  module Cli
+    SEVERITY_RANK = { high: 2, medium: 1, low: 0 }.freeze
+
+    # Immutable value object for one scan hit. Data.define gives us structural
+    # equality and Hash-pattern deconstruction (`in {severity:, rule:}`) for free —
+    # a plain TS interface has neither.
+    #
+    # The triage fields default to nil, so a scan-only run builds a Finding the
+    # same way it always did, and `Triage` layers verdicts on with `#with` rather
+    # than mutating anything.
+    Finding = Data.define(:rule, :file, :line, :preview, :severity,
+                          :verdict, :confidence, :rationale) do
+      include Comparable
+
+      def initialize(verdict: nil, confidence: nil, rationale: nil, **) = super
+
+      def <=>(other)
+        SEVERITY_RANK.fetch(severity) <=> SEVERITY_RANK.fetch(other.severity)
+      end
+
+      def high? = severity == :high
+      def triaged? = !verdict.nil?
+    end
+  end
+end

data/lib/leakless/init.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Leakless
+  module Cli
+    # Scaffolds a publishable sharekit profile: sharekit.toml, a claude/
+    # CLAUDE.md, a cursor/.cursorrules, an empty shared/, and any requested
+    # skill directories — copied from the caller's own AI-tooling config, so
+    # the result becomes an install target for `sharekit install <user>`.
+    class Init
+      Result = Data.define(:profile_dir, :findings, :created)
+      SourceFile = Data.define(:source, :dest, :placeholder)
+
+      def self.call(profile_dir:, skill_names: [], source_root: ENV.fetch("HOME", Dir.pwd), force: false)
+        new(profile_dir:, skill_names:, source_root:, force:).call
+      end
+
+      def initialize(profile_dir:, skill_names:, source_root:, force:)
+        @profile_dir = profile_dir
+        @skill_names = skill_names
+        @source_root = source_root
+        @force = force
+        @findings = []
+        @created = []
+      end
+
+      STANDARD_FILES = [
+        SourceFile.new(source: [".claude", "CLAUDE.md"], dest: %w[claude CLAUDE.md],
+                       placeholder: "# My AI coding instructions\n"),
+        SourceFile.new(source: [".cursor", ".cursorrules"], dest: %w[cursor .cursorrules],
+                       placeholder: "# Cursor IDE rules\n")
+      ].freeze
+
+      def call
+        prepare_profile_dir
+        write_manifest
+        STANDARD_FILES.each { |file| scaffold(file) }
+        scaffold_shared
+        @skill_names.each { |name| scaffold_skill(name) }
+
+        Result.new(profile_dir: @profile_dir, findings: @findings, created: @created)
+      end
+
+      private
+
+      def prepare_profile_dir
+        if Dir.exist?(@profile_dir)
+          raise Error, "Profile directory already exists: #{@profile_dir}. Use --force to overwrite." unless @force
+
+          FileUtils.rm_rf(@profile_dir)
+        end
+        FileUtils.mkdir_p(@profile_dir)
+      end
+
+      def write_manifest
+        path = File.join(@profile_dir, "sharekit.toml")
+        File.write(path, <<~TOML)
+          [profile]
+          name = "#{ENV.fetch("USER", "unknown")}"
+          version = "0.1.0"
+          description = "My AI coding setup"
+        TOML
+        @created << path
+      end
+
+      def scaffold(file)
+        source = File.join(@source_root, *file.source)
+        dest = File.join(@profile_dir, *file.dest)
+        FileUtils.mkdir_p(File.dirname(dest))
+        if File.exist?(source)
+          FileUtils.cp(source, dest)
+          scan_and_record(dest)
+        else
+          File.write(dest, file.placeholder)
+        end
+        @created << dest
+      end
+
+      def scaffold_shared
+        dir = File.join(@profile_dir, "shared")
+        FileUtils.mkdir_p(dir)
+        FileUtils.touch(File.join(dir, ".gitkeep"))
+        @created << dir
+      end
+
+      def scaffold_skill(name)
+        source_dir = File.join(@source_root, ".claude", "skills", name)
+        unless Dir.exist?(source_dir)
+          puts "  ~ skill '#{name}' not found at #{source_dir}"
+          return
+        end
+
+        dest_base = File.join(@profile_dir, "claude", "skills", name)
+        Dir.glob("#{source_dir}/**/*").select { |f| File.file?(f) }.each do |source_file|
+          copy_skill_file(source_file, source_dir, dest_base)
+        end
+      end
+
+      def copy_skill_file(source_file, source_dir, dest_base)
+        dest_file = File.join(dest_base, source_file.delete_prefix("#{source_dir}/"))
+        FileUtils.mkdir_p(File.dirname(dest_file))
+        FileUtils.cp(source_file, dest_file)
+        scan_and_record(dest_file)
+        @created << dest_file
+      end
+
+      def scan_and_record(path)
+        content = File.read(path, encoding: "UTF-8")
+        @findings.concat(Scanner.scan(content, file: path).to_a)
+      end
+    end
+  end
+end

data/lib/leakless/redactor.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "scanner"
+
+module Leakless
+  module Cli
+    # Strips secret material out of a line before it can leave the machine.
+    #
+    # Redaction runs against the *original* line, never a Finding's truncated
+    # preview: truncation can cut a secret mid-token so that the rule pattern no
+    # longer matches it, which would let the surviving fragment through.
+    #
+    # A masked secret is replaced by its shape (length + Shannon entropy), which
+    # is what a classifier actually needs to tell a live key from EXAMPLE_KEY.
+    module Redactor
+      # Backstop for high-entropy material no Scanner rule claims. Runs last, so
+      # rule-labelled hits keep their own mask.
+      GENERIC_SECRET_PATTERN = %r{[A-Za-z0-9+/=_-]{20,}}
+      MASK_PREFIX = "[REDACTED"
+
+      module_function
+
+      # Masks every secret-shaped run in +line+: every Scanner rule, then
+      # sensitive env-var values, then the generic backstop. All rules run, not
+      # just the one that produced the finding, so a second secret sharing the
+      # line cannot ride along into a prompt.
+      def redact(line)
+        masked = Scanner::RULES.reduce(line) do |acc, rule|
+          acc.gsub(rule.pattern) { |hit| mask(hit) }
+        end
+        mask_env_values(masked).gsub(GENERIC_SECRET_PATTERN) { |hit| mask(hit) }
+      end
+
+      def mask(secret)
+        "#{MASK_PREFIX} chars=#{secret.length} entropy=#{format("%.1f", entropy(secret))}]"
+      end
+
+      # Shannon entropy in bits per character. Random tokens land near 4+ bits;
+      # placeholders like AKIAIOSFODNN7EXAMPLE sit noticeably lower.
+      def entropy(str)
+        return 0.0 if str.empty?
+
+        length = str.length.to_f
+        str.each_char.tally.values.sum do |count|
+          probability = count / length
+          -probability * Math.log2(probability)
+        end
+      end
+
+      # Scanner's ENV_VAR_PATTERN ends in `(.*)$`, which swallows the rest of the line,
+      # so the first assignment is the only one it ever examines. That is fine for
+      # reporting one finding per line, but as a redaction pass it leaks: in
+      # `PATH=/usr/bin API_KEY=short` the boring first key short-circuits the check and
+      # the real secret is never masked, while being too short for the generic
+      # backstop. Redaction therefore matches one assignment at a time. Quoted forms
+      # are listed explicitly because a bare `\S*` stops at the space in `KEY="a b"`.
+      ENV_ASSIGNMENT_PATTERN = /(?:^|\s)(?:export\s+)?([A-Z_]+)=("[^"]*"|'[^']*'|\S*)/
+
+      def mask_env_values(line)
+        line.gsub(ENV_ASSIGNMENT_PATTERN) do |hit|
+          key = Regexp.last_match(1)
+          value = Regexp.last_match(2)
+          next hit unless Scanner::SENSITIVE_KEY_PATTERN.match?(key)
+          next hit if value.empty? || value.start_with?(MASK_PREFIX)
+
+          hit.sub(value, mask(value))
+        end
+      end
+    end
+  end
+end

data/lib/leakless/reporter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Leakless
+  module Cli
+    # Formats findings for terminal output and gates high-severity secrets.
+    module Reporter
+      GREEN = "\e[32m"
+      YELLOW = "\e[33m"
+      RESET = "\e[0m"
+
+      VERDICT_LABELS = { "true_positive" => "likely real",
+                         "false_positive" => "likely placeholder",
+                         "uncertain" => "unclear" }.freeze
+
+      module_function
+
+      def report(findings, force: false)
+        if findings.empty?
+          puts "#{GREEN}  ✓ No secrets detected.\n#{RESET}"
+          return
+        end
+
+        print_findings(findings)
+        gate!(findings, force:)
+      end
+
+      def print_findings(findings)
+        puts "#{YELLOW}\n  ⚠  Secret patterns detected:#{RESET}"
+        findings.each { |finding| puts "#{YELLOW}    #{format_line(finding)}#{RESET}" }
+        puts "#{YELLOW}\n  ⚠  Review and redact secrets before pushing to a public repository.#{RESET}"
+        if findings.any?(&:triaged?)
+          puts "#{YELLOW}  ⚠  AI verdicts are advisory: the high-severity gate ignores them.#{RESET}"
+        end
+        puts ""
+      end
+
+      # Data.define objects deconstruct into a Hash for free, so `in` can match
+      # directly on the fields we care about — no case/when + manual field access.
+      # The untriaged branch comes first, so a nil verdict never reaches the
+      # formatting that assumes one.
+      def format_line(finding)
+        case finding
+        in { verdict: nil, file:, line:, rule:, preview: }
+          "#{file}:#{line} [#{rule}] #{preview}"
+        in { verdict:, confidence:, rationale:, file:, line:, rule:, preview: }
+          "#{file}:#{line} [#{rule}] #{preview}\n" \
+            "      → #{VERDICT_LABELS.fetch(verdict, verdict)} " \
+            "(#{(confidence * 100).round}% confident) #{rationale}"
+        end
+      end
+
+      def gate!(findings, force:)
+        high = findings.select(&:high?)
+        return if high.empty? || force
+
+        raise Error, "Secrets export blocked: #{high.size} high-severity finding(s) detected. " \
+                      "Review and remove secrets, or re-run with --force to override."
+      end
+    end
+  end
+end

data/lib/leakless/scanner.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "finding"
+
+module Leakless
+  module Cli
+    # Rule-driven secret scanner. Each rule is data (pattern + metadata), not a
+    # branch in an if/elsif chain — adding a rule means appending to RULES,
+    # never touching the scan loop.
+    class Scanner
+      Rule = Data.define(:name, :pattern, :severity, :context_before, :max_len, :leading_ellipsis)
+
+      RULES = [
+        Rule.new(name: "Private Key Block",
+                 pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+                 severity: :high, context_before: 0, max_len: 40, leading_ellipsis: false),
+        Rule.new(name: "AWS Access Key ID",
+                 pattern: /AKIA[0-9A-Z]{16}/,
+                 severity: :high, context_before: 5, max_len: 20, leading_ellipsis: true),
+        Rule.new(name: "GitHub Personal Access Token",
+                 pattern: /ghp_[A-Za-z0-9_]{20,}/,
+                 severity: :high, context_before: 5, max_len: 40, leading_ellipsis: true),
+        Rule.new(name: "GitHub Personal Access Token",
+                 pattern: /github_pat_[A-Za-z0-9_]{20,}/,
+                 severity: :high, context_before: 5, max_len: 40, leading_ellipsis: true),
+        Rule.new(name: "Slack Token",
+                 pattern: /xox[baprs]-[A-Za-z0-9-]{10,}/,
+                 severity: :high, context_before: 5, max_len: 40, leading_ellipsis: true),
+        Rule.new(name: "Google API Key",
+                 pattern: /AIza[0-9A-Za-z\-_]{30,40}/,
+                 severity: :high, context_before: 5, max_len: 40, leading_ellipsis: true),
+        Rule.new(name: "Bearer Token",
+                 pattern: /Bearer eyJ[A-Za-z0-9._-]*\.[A-Za-z0-9._-]+\.[A-Za-z0-9._-]+/,
+                 severity: :high, context_before: 0, max_len: 30, leading_ellipsis: false),
+        Rule.new(name: "Home Directory Path Leak",
+                 pattern: %r{(/Users/[a-zA-Z0-9_-]+|/home/[a-zA-Z0-9_-]+)},
+                 severity: :low, context_before: 5, max_len: 40, leading_ellipsis: true)
+      ].freeze
+
+      ENV_VAR_PATTERN = /(?:^|\s)(?:export\s+)?([A-Z_]+?)=(.*)$/
+      SENSITIVE_KEY_PATTERN = /(SECRET|TOKEN|PASSWORD|API_KEY|APIKEY|ACCESS_KEY)/i
+      PLACEHOLDER_PREFIXES = ['""', "''", "xxx", "<", "changeme", "your-", "your_"].freeze
+
+      class << self
+        # Scans +content+ line by line. Yields each Finding as it's found when
+        # a block is given; otherwise returns an Enumerator (same dual API as
+        # Array#each), so callers can stream (`each { }`) or collect (`.to_a`,
+        # `.first`, `.lazy`) without the scanner caring which.
+        def scan(content, file: nil)
+          return to_enum(:scan, content, file:) unless block_given?
+
+          content.each_line.with_index(1) do |raw_line, line_num|
+            line = raw_line.chomp
+            finding = rule_finding(line, file, line_num) || env_var_finding(line, file, line_num)
+            yield finding if finding
+          end
+        end
+
+        def truncate_preview(line, idx, context_before: 5, max_len: 40, leading_ellipsis: true)
+          start = [0, idx - context_before].max
+          finish = [line.length, idx + max_len].min
+          leading = leading_ellipsis && start.positive? ? "…" : ""
+          trailing = finish < line.length ? "…" : ""
+          "#{leading}#{line[start...finish]}#{trailing}"
+        end
+
+        private
+
+        def rule_finding(line, file, line_num)
+          rule = RULES.find { |r| r.pattern.match?(line) }
+          return unless rule
+
+          match = rule.pattern.match(line)
+          preview = truncate_preview(
+            line, match.begin(0),
+            context_before: rule.context_before, max_len: rule.max_len, leading_ellipsis: rule.leading_ellipsis
+          )
+          Finding.new(rule: rule.name, file:, line: line_num, preview:, severity: rule.severity)
+        end
+
+        def env_var_finding(line, file, line_num)
+          match = ENV_VAR_PATTERN.match(line)
+          return unless match
+
+          key_name = match[1].upcase
+          value = match[2]
+          return unless SENSITIVE_KEY_PATTERN.match?(key_name)
+          return if placeholder?(value)
+
+          Finding.new(rule: "Env Var: Sensitive Key", file:, line: line_num,
+                      preview: "#{key_name}=#{truncate_value(value)}", severity: :medium)
+        end
+
+        def placeholder?(value)
+          return true if value.empty? || value == '""' || value == "''"
+
+          PLACEHOLDER_PREFIXES.any? { |prefix| value.start_with?(prefix) }
+        end
+
+        def truncate_value(value)
+          value.length > 8 ? "#{value[0, 8]}…" : value
+        end
+      end
+    end
+  end
+end

data/lib/leakless/triage.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "ruby_llm/schema"
+require_relative "redactor"
+
+module Leakless
+  module Cli
+    # Classifies findings as real leaks or false positives with an LLM.
+    #
+    # SECURITY: the model never receives secret material, and there is no flag to
+    # opt out. Every payload line is rebuilt from the file on disk and passed
+    # through Redactor first, so what ships is the finding's *shape*: rule name,
+    # path, line number, length and entropy of the masked token, and whatever
+    # surrounding context survived redaction. Point --provider at Ollama to keep
+    # even that on the machine.
+    #
+    # Verdicts are advisory. Triage annotates output; it never relaxes the
+    # high-severity gate, because a model must not be what decides a live key
+    # isn't a key.
+    module Triage
+      VERDICTS = %w[true_positive false_positive uncertain].freeze
+
+      # Ollama's conventional local endpoint, so --provider ollama needs no setup.
+      OLLAMA_DEFAULT_BASE = "http://localhost:11434/v1"
+
+      RATIONALE_LIMIT = 120
+
+      SOURCE_UNAVAILABLE = "[source unavailable]"
+
+      # A missing API key or an unknown model id raise off a different branch of
+      # RubyLLM's hierarchy than provider/HTTP faults, and they are the two most
+      # likely failures here, so both branches are caught.
+      FAILURES = [RubyLLM::Error, RubyLLM::ConfigurationError,
+                  RubyLLM::ModelNotFoundError, Faraday::Error].freeze
+
+      # Findings go over as an indexed list in one request, and verdicts are
+      # matched back by index. A verdict for an index the model skipped or
+      # invented is dropped rather than shifting every later finding's answer.
+      class Schema < RubyLLM::Schema
+        array :verdicts do
+          object do
+            integer :index, description: "index of the finding being judged"
+            string :verdict, enum: VERDICTS
+            number :confidence, description: "0.0 to 1.0"
+            string :rationale, description: "one sentence, at most #{RATIONALE_LIMIT} characters"
+          end
+        end
+      end
+
+      SYSTEM_PROMPT = <<~PROMPT
+        You triage secret-scanner findings for a tool that runs before someone
+        publishes a directory. For each finding decide whether it is a real leaked
+        credential (true_positive), a placeholder, example, test fixture or
+        documentation sample (false_positive), or genuinely unclear (uncertain).
+
+        Secret values have been redacted before reaching you. A masked token shows
+        only its length and Shannon entropy, as
+        "[REDACTED chars=20 entropy=3.8]". Judge from the rule name, the file path,
+        the line number, and the surrounding context. High entropy and a config or
+        source path suggest a real credential; low entropy, or paths like
+        spec/, test/, fixtures/, docs/, README, *.example, *.sample suggest not.
+
+        Never claim to have read the secret. Reply for every index you are given.
+      PROMPT
+
+      module_function
+
+      # Returns a new array of findings, each with triage fields filled where the
+      # model answered. Findings the model skipped come back untouched.
+      def call(findings, **chat_options)
+        return findings if findings.empty?
+
+        verdicts = request(findings, **chat_options)
+        findings.each_with_index.map do |finding, index|
+          verdict = verdicts[index]
+          verdict ? finding.with(**verdict) : finding
+        end
+      end
+
+      def request(findings, **chat_options)
+        configure
+        chat = RubyLLM.chat(**chat_options.compact)
+                      .with_instructions(SYSTEM_PROMPT)
+                      .with_schema(Schema)
+        # On 1.16 a schema-backed reply arrives parsed on #content (there is no
+        # #parsed), and stays a String if the provider returned unparseable JSON.
+        parse(chat.ask(prompt_for(findings)).content, findings.size)
+      rescue *FAILURES => e
+        raise Error, "AI triage failed: #{e.class}: #{e.message}"
+      end
+
+      # RubyLLM reads no provider credentials from the environment on its own,
+      # and a CLI has nowhere else to get them.
+      def configure
+        RubyLLM.configure do |config|
+          config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
+          config.openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
+          config.ollama_api_base = ENV.fetch("OLLAMA_API_BASE", OLLAMA_DEFAULT_BASE)
+        end
+      end
+
+      # Rebuilds each finding's line from disk so redaction sees the whole line,
+      # never the already-truncated preview.
+      def prompt_for(findings)
+        lines = Hash.new { |cache, path| cache[path] = read_lines(path) }
+
+        findings.each_with_index.map { |finding, index| entry(finding, index, lines) }.join("\n")
+      end
+
+      # There is deliberately no fallback to `finding.preview` when the file cannot be
+      # read: the preview is truncated, and a fragment cut mid-token matches neither its
+      # own rule nor the generic backstop, which is the exact leak reading from disk
+      # exists to prevent. Losing one finding's context is the cheaper failure. The path
+      # is redacted too, so a token embedded in a filename cannot ride along.
+      def entry(finding, index, lines)
+        raw = lines[finding.file]&.[](finding.line - 1)
+        <<~ENTRY
+          #{index}. rule=#{finding.rule} severity=#{finding.severity}
+             location=#{Redactor.redact(finding.file)}:#{finding.line}
+             context=#{raw ? Redactor.redact(raw.chomp) : SOURCE_UNAVAILABLE}
+        ENTRY
+      end
+
+      def read_lines(path)
+        File.readlines(path, encoding: "UTF-8")
+      rescue ArgumentError, SystemCallError
+        nil
+      end
+
+      def parse(content, count)
+        return {} unless content.is_a?(Hash)
+
+        Array(content["verdicts"]).each_with_object({}) do |row, acc|
+          index = verdict_index(row, count)
+          next unless index
+
+          acc[index] = { verdict: row["verdict"],
+                         confidence: row["confidence"].to_f.clamp(0.0, 1.0),
+                         rationale: rationale(row["rationale"]) }
+        end
+      end
+
+      # Models routinely blow past the length the schema asks for, and these land
+      # in a terminal one line per finding, so the limit is enforced here too.
+      def rationale(raw)
+        text = raw.to_s.strip
+        return text if text.length <= RATIONALE_LIMIT
+
+        "#{text[0, RATIONALE_LIMIT - 1]}…"
+      end
+
+      # Only an in-range index paired with a label we asked for is usable; anything
+      # else is dropped so it cannot shift another finding's verdict.
+      def verdict_index(row, count)
+        return unless row.is_a?(Hash)
+
+        index = row["index"]
+        return unless index.is_a?(Integer) && index.between?(0, count - 1)
+        return unless VERDICTS.include?(row["verdict"])
+
+        index
+      end
+    end
+  end
+end

data/lib/leakless/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Leakless
+  module Cli
+    VERSION = "0.3.0"
+  end
+end

data/lib/leakless.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "leakless/version"
+require_relative "leakless/finding"
+require_relative "leakless/scanner"
+require_relative "leakless/reporter"
+require_relative "leakless/file_lister"
+require_relative "leakless/init"
+
+module Leakless
+  # Command-line entry points for scanning a directory for leaked secrets and
+  # scaffolding a publishable profile.
+  module Cli
+    class Error < StandardError; end
+
+    # Loading ruby_llm pulls in a provider stack that a plain `scan` never needs,
+    # so Triage is resolved on first reference instead of at boot.
+    autoload :Triage, "leakless/triage"
+
+    # Thor gives us subcommand dispatch, flag parsing, and --help for free —
+    # the TS original hand-parses process.argv/flags itself.
+    class App < Thor
+      def self.exit_on_failure? = true
+
+      desc "scan [DIR]", "scan a directory for secret patterns"
+      method_option :force,
+                    type: :boolean,
+                    default: false,
+                    desc: "exit 0 even if high-severity findings detected"
+      method_option :ai_triage,
+                    type: :boolean,
+                    default: false,
+                    desc: "label findings true/false positive with an LLM (secret values are redacted first)"
+      method_option :model,
+                    type: :string,
+                    desc: "model id for --ai-triage (default: RubyLLM's configured default)"
+      method_option :provider,
+                    type: :string,
+                    desc: "provider for --ai-triage, e.g. anthropic, openai, ollama"
+      method_option :assume_model_exists,
+                    type: :boolean,
+                    default: false,
+                    desc: "skip model-registry validation, needed for local Ollama models"
+      def scan(dir = ".")
+        findings = collect_findings(dir)
+        findings = triage(findings) if options[:ai_triage]
+        Reporter.report(findings, force: options[:force])
+      rescue Error => e
+        warn e.message
+        exit 1
+      end
+
+      desc "init [SKILL...]", "scaffold a publishable sharekit profile"
+      method_option :force,
+                    type: :boolean,
+                    default: false,
+                    desc: "overwrite existing dir; override secret blocking"
+      method_option :dir,
+                    type: :string,
+                    default: "./sharekit-profile",
+                    desc: "profile directory to create"
+      def init(*skill_names)
+        result = Init.call(profile_dir: options[:dir], skill_names:, force: options[:force])
+        print_init_summary(result)
+        Reporter.report(result.findings, force: options[:force])
+      rescue Error => e
+        warn e.message
+        exit 1
+      end
+
+      no_commands do
+        def collect_findings(dir)
+          FileLister.list(dir).flat_map do |path|
+            Scanner.scan(File.read(path, encoding: "UTF-8"), file: path).to_a
+          rescue ArgumentError, Errno::ENOENT, Errno::EACCES => e
+            puts "    ~ Skipped #{path}: #{e.class}"
+            []
+          end
+        end
+
+        def triage(findings)
+          return findings if findings.empty?
+
+          puts "\n  … AI triage: #{findings.size} finding(s), secret values redacted before sending"
+          Triage.call(findings,
+                      model: options[:model],
+                      provider: options[:provider]&.to_sym,
+                      assume_model_exists: options[:assume_model_exists])
+        rescue LoadError => e
+          # ruby_llm is optional: a scan-only install should not have to carry a
+          # provider stack. Autoloading Triage is what surfaces its absence here.
+          raise Error, "--ai-triage needs the ruby_llm gem, which is not installed. " \
+                        "Install it with `gem install ruby_llm` (or add it to your Gemfile). " \
+                        "(#{e.message})"
+        end
+
+        def print_init_summary(result)
+          result.created.each { |path| puts "  + #{path}" }
+          puts "\n  ✓ Created profile at #{result.profile_dir}\n\n"
+        end
+      end
+    end
+  end
+end

data/sig/leakless.rbs

@@ -0,0 +1,6 @@
+module Leakless
+  module Cli
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: leakless
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Lucas Santana
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: A small rule-driven CLI that scans files for private keys, cloud/API
+  tokens, and sensitive env vars, and blocks on high-severity findings unless --force
+  is given.
+email:
+- lucas.diassantana@gmail.com
+executables:
+- leakless
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ruby-version"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/adr/2026-07-26-redact-always-ai-triage.md
+- exe/leakless
+- lib/leakless.rb
+- lib/leakless/file_lister.rb
+- lib/leakless/finding.rb
+- lib/leakless/init.rb
+- lib/leakless/redactor.rb
+- lib/leakless/reporter.rb
+- lib/leakless/scanner.rb
+- lib/leakless/triage.rb
+- lib/leakless/version.rb
+- sig/leakless.rbs
+homepage: https://github.com/LucasSantana-Dev/leakless
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/LucasSantana-Dev/leakless
+  source_code_uri: https://github.com/LucasSantana-Dev/leakless/tree/main
+  changelog_uri: https://github.com/LucasSantana-Dev/leakless/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.2.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: Scan a directory for leaked secrets before you publish it.
+test_files: []