envvariablecheck 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 539d08ccfcb79bf98abb1635af6e813c5bc2ac0ea77b910a976cb29ec0f77b2d
+  data.tar.gz: 440b23e45504d8142f0be5ade66e12d41c9811df412ed070c55b1ffb57b6ae66
+SHA512:
+  metadata.gz: 3ca8a0e2755be719d4d78f0ffdda648290981967c4b7803ee9fd4931b39dded1313ab8908a076142dcfd7cd867f13e8c1b7894e77a12421e7c0357a54638eaa1
+  data.tar.gz: fd0947623002d2df2c84f491823b4c80da8ab3c57a84a08b01b7bbab144d408e3d283f897fbb8c7929e81aef4f1bb26edb66afb4b15a860f8dd087e30a750979

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kellysec
+
+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,151 @@
+# envvariablecheck
+
+Load `~/.env` into a Ruby process, then rank how strong its keys and passwords are.
+
+Secret values stay on the machine. The review prints the env file in full, then the rank of each key and password. Nothing is uploaded.
+
+## Install
+
+From this repository:
+
+```sh
+gem build envvariablecheck.gemspec
+gem install ./envvariablecheck-0.1.0.gem
+```
+
+While developing, you can skip the install:
+
+```sh
+ruby -Ilib exe/envcheck audit
+```
+
+Requires Ruby 2.6 or newer. The gem has no runtime dependencies.
+
+## Inject, then run a script
+
+`envcheck run` reads `~/.env`, merges it into the environment, and replaces the process with your Ruby script. The script sees the variables in `ENV` the same way it would if the shell had exported them. Pass `--env` to use a different file.
+
+```sh
+envcheck run script.rb
+envcheck run --env .env.local script.rb --port 3000
+```
+
+Variables already set in the environment are kept. Pass `--override` to let the file win.
+
+```sh
+envcheck run --override script.rb
+```
+
+`--strict` refuses to start the script when any secret ranks Weak or Critical, when the file is readable by group or others, or when it is inside a git repo and not gitignored.
+
+```sh
+envcheck run --strict script.rb
+```
+
+To inject `~/.env` into the current terminal session instead of a child process:
+
+```sh
+eval "$(envcheck export)"
+```
+
+To inject it from inside a Ruby program, before the rest of the program runs:
+
+```ruby
+require 'envvariablecheck'
+EnvVariableCheck.load!
+```
+
+Or load it before the script starts:
+
+```sh
+ruby -r envvariablecheck/load script.rb
+```
+
+## Review keys and passwords
+
+```sh
+envcheck audit
+envcheck audit .env.production
+envcheck audit --format json
+envcheck audit --strict
+```
+
+`--strict` exits 1 when the review fails, which makes it usable as a check before deploy.
+
+Config names such as `PORT` and `RACK_ENV` are listed and not password-scored. These names are scored:
+
+- passwords (`PASSWORD`, `PASSWD`, `PWD`)
+- tokens and keys (`SECRET`, `TOKEN`, `API_KEY`, `MASTER_KEY`, `PRIVATE_KEY`, and similar)
+- connection URLs (`DATABASE_URL`, `REDIS_URL`, and any URL that embeds `user:password`)
+
+A connection URL is ranked on the embedded password only. `AWS_ACCESS_KEY_ID` and other key ids are identifiers, not passwords.
+
+### Ranks
+
+| Rank | Score | Meaning |
+| --- | --- | --- |
+| Excellent | 90–100 | Long, high-entropy, no practice issues |
+| Strong | 75–89 | Solid, or strong with a smaller practice issue such as reuse |
+| Fair | 50–74 | Usable, but below the bar this tool applies |
+| Weak | 25–49 | Too short, patterned, or low diversity |
+| Critical | 0–24 | Empty, common, placeholder, or far too short |
+
+The rubric follows password best practices:
+
+- Length comes first. NIST SP 800-63B requires at least 8 characters. This tool still caps application passwords under 15 characters at Fair, and tokens under 32 characters at Fair.
+- Character classes add a bonus. They are not required. A long random value beats a short value with a symbol tacked on.
+- A local blocklist catches common passwords, light leet-speak (`p@ssw0rd`), and the same word with digits added (`Summer2024!`).
+- Placeholders (`changeme`, `your_api_key`, `example`), environment names (`production`), and a value that repeats the variable name are capped at Critical.
+- Sequential runs (`abcd`, `1234`, `qwerty`), repeated chunks, and digits-only values are capped.
+- A secret copied into two variables cannot rank Excellent.
+- The file should be mode `0600`. In a git repo it should be ignored.
+
+The bit estimate is the size of the character set the value actually uses, times its length. That number assumes the value was generated at random. The pattern and blocklist checks exist so a value like `Password1!` cannot hide behind a high estimate.
+
+Replace a weak secret with a random value:
+
+```sh
+ruby -e 'require "securerandom"; puts SecureRandom.hex(32)'
+```
+
+This is a local heuristic, not a search of a breach corpus. Checking a secret against a remote breach list would send the secret off the machine, so this gem does not do that.
+
+## Env file format
+
+```
+# comment
+PORT=3000
+export APP_ENV=development
+PASSWORD='single quotes are literal, including $'
+TOKEN="double quotes expand $OTHER and \n"
+```
+
+- `export` is optional.
+- Bare and double-quoted values expand `$NAME` and `${NAME}` from earlier lines, then from the current environment. An unknown name expands to empty.
+- Single quotes do not expand. Use them for secrets that contain `$`.
+- Put a value that contains a single quote in double quotes, for example `"it's"`.
+- Unquoted values are trimmed. Quote a value to keep surrounding spaces.
+- The last assignment wins when a key is repeated.
+
+## Library
+
+```ruby
+require 'envvariablecheck'
+
+EnvVariableCheck.load!(override: false)
+report = EnvVariableCheck.audit
+
+puts report.overall_rank
+report.variables.each do |variable|
+  next unless variable.scored
+  puts "#{variable.name}: #{variable.rank} (#{variable.score})"
+end
+```
+
+`report.contents` is the env file text. `variable.findings` explains each rank.
+
+## Tests
+
+```sh
+rake test
+```

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib' << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.warning = false
+end
+
+task default: :test

data/exe/envcheck

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'envvariablecheck'
+
+exit EnvVariableCheck::CLI.start(ARGV)

data/lib/envvariablecheck/auditor.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module EnvVariableCheck
+  # Reviews every variable in an env file and the file's own exposure.
+  class Auditor
+    RANK_ORDER = %w[Critical Weak Fair Strong Excellent].freeze
+
+    Variable = Struct.new(
+      :name, :kind, :line, :score, :rank, :charset_bits, :findings, :scored,
+      keyword_init: true
+    ) do
+      def to_h
+        {
+          'name' => name,
+          'kind' => kind.to_s,
+          'line' => line,
+          'scored' => scored,
+          'score' => score,
+          'rank' => rank,
+          'estimated_bits' => charset_bits,
+          'findings' => findings
+        }
+      end
+    end
+
+    Audit = Struct.new(:path, :variables, :file_findings, :contents, keyword_init: true) do
+      def secrets
+        variables.select(&:scored)
+      end
+
+      def overall_rank
+        return nil if secrets.empty?
+
+        secrets.min_by { |variable| RANK_ORDER.index(variable.rank) }.rank
+      end
+
+      def overall_score
+        return nil if secrets.empty?
+
+        secrets.map(&:score).min
+      end
+
+      def failing?
+        secrets.any? { |variable| variable.rank == 'Critical' || variable.rank == 'Weak' } ||
+          !file_findings.empty?
+      end
+
+      def counts
+        result = {
+          'Critical' => 0,
+          'Weak' => 0,
+          'Fair' => 0,
+          'Strong' => 0,
+          'Excellent' => 0,
+          'Unscored' => 0
+        }
+        variables.each do |variable|
+          key = variable.scored ? variable.rank : 'Unscored'
+          result[key] += 1
+        end
+        result
+      end
+
+      def to_h
+        {
+          'file' => path,
+          'overall_rank' => overall_rank,
+          'overall_score' => overall_score,
+          'counts' => counts,
+          'file_findings' => file_findings,
+          'contents' => contents,
+          'variables' => variables.map(&:to_h)
+        }
+      end
+    end
+
+    Prepared = Struct.new(
+      :name, :value, :material, :kind, :line, :embedded, :score_kind,
+      keyword_init: true
+    )
+
+    def self.audit_file(path)
+      contents = Parser.read(path)
+      assignments = Parser.parse(contents, path: path)
+      audit_assignments(assignments, path: path, contents: contents)
+    end
+
+    def self.audit_assignments(assignments, path: nil, contents: nil)
+      Audit.new(
+        path: path,
+        variables: rank_variables(assignments),
+        file_findings: file_findings_for(path),
+        contents: contents
+      )
+    end
+
+    def self.rank_variables(assignments)
+      collapsed, counts = Parser.collapse(assignments)
+      items = collapsed.map { |assignment| prepare(assignment) }
+      index = Hash.new { |hash, key| hash[key] = [] }
+      items.each do |item|
+        next if item.material.nil? || item.material.strip.empty?
+
+        index[item.material] << item.name
+      end
+
+      items.map do |item|
+        reused = []
+        if item.material && !item.material.strip.empty?
+          reused = index[item.material].reject { |name| name == item.name }
+        end
+        build(item, reused, counts[item.name])
+      end
+    end
+
+    def self.prepare(assignment)
+      kind = Classifier.classify(assignment.key, assignment.value)
+      embedded = false
+      material = nil
+      score_kind = nil
+
+      case kind
+      when :connection_url
+        extracted = Classifier.extract_password(assignment.value)
+        if !extracted.nil?
+          embedded = true
+          material = extracted
+          score_kind = :password
+        elsif !Classifier.url?(assignment.value)
+          material = assignment.value
+          score_kind = :password
+        end
+      when :password
+        material = assignment.value
+        score_kind = :password
+      when :token
+        material = assignment.value
+        score_kind = :token
+      else
+        material = assignment.value
+      end
+
+      Prepared.new(
+        name: assignment.key,
+        value: assignment.value,
+        material: material,
+        kind: kind,
+        line: assignment.line,
+        embedded: embedded,
+        score_kind: score_kind
+      )
+    end
+
+    def self.build(item, reused, count)
+      findings = []
+      if count > 1
+        findings << 'Assigned more than once. The last value is the one that gets injected.'
+      end
+
+      if item.score_kind
+        scored(item, reused, findings)
+      else
+        unscored(item, findings)
+      end
+    end
+
+    def self.scored(item, reused, findings)
+      if item.kind == :connection_url && item.embedded
+        findings << 'Ranked the embedded password. The rest of the URL was not treated as secret material.'
+      elsif item.kind == :connection_url
+        findings << 'Name looks like a connection URL, but the value is not a URL. Ranked the whole value.'
+      end
+
+      result = Scorer.score(item.material, kind: item.score_kind, name: item.name, reused_names: reused)
+      Variable.new(
+        name: item.name,
+        kind: item.kind,
+        line: item.line,
+        score: result.score,
+        rank: result.rank,
+        charset_bits: result.charset_bits,
+        findings: findings + result.findings,
+        scored: true
+      )
+    end
+
+    def self.unscored(item, findings)
+      case item.kind
+      when :identifier
+        if item.value.strip.empty?
+          findings << 'Identifier is empty.'
+        elsif item.value.include?('EXAMPLE')
+          findings << 'Looks like a sample or placeholder identifier.'
+        else
+          findings << 'Identifier, not a secret. Strength is not ranked.'
+        end
+      when :public
+        findings << 'Public key material. Strength is not ranked as a password.'
+      when :connection_url
+        findings << 'Connection URL has no embedded password to assess.'
+      when :config
+        if high_entropy_blob?(item.value)
+          findings << 'Value looks long and random, but the name does not mark it as a secret. Confirm it is not a credential.'
+        end
+      end
+
+      Variable.new(
+        name: item.name,
+        kind: item.kind,
+        line: item.line,
+        score: nil,
+        rank: nil,
+        charset_bits: nil,
+        findings: findings,
+        scored: false
+      )
+    end
+
+    def self.high_entropy_blob?(value)
+      return false if value.nil? || value.length < 24
+      return false if Classifier.url?(value)
+      return false if value.match?(/\s/)
+
+      Entropy.charset_bits(value) >= 100
+    end
+
+    def self.file_findings_for(path)
+      return [] if path.nil? || !File.exist?(path)
+
+      findings = permission_findings(path)
+      git = gitignore_finding(path)
+      findings << git if git
+      findings
+    end
+
+    def self.permission_findings(path)
+      findings = []
+      if File.symlink?(path)
+        findings << 'File is a symlink. Confirm the target is not shared or world-readable.'
+      end
+      mode = File.stat(path).mode & 0777
+      if mode & 0077 != 0
+        findings << format('File mode is %04o, so group or others can read it. Restrict it to 0600.', mode)
+      end
+      findings
+    rescue SystemCallError
+      []
+    end
+
+    def self.gitignore_finding(path)
+      root = git_root(File.dirname(File.expand_path(path)))
+      return nil unless root
+
+      _output, status = Open3.capture2(
+        'git', '-C', root, 'check-ignore', '-q', '--', File.expand_path(path)
+      )
+      return nil if status.success?
+      return nil unless status.exitstatus == 1
+
+      "#{File.basename(path)} is not ignored by git. Add it to .gitignore before committing secrets."
+    rescue Errno::ENOENT, SystemCallError
+      nil
+    end
+
+    def self.git_root(start)
+      dir = File.expand_path(start)
+      loop do
+        return dir if File.exist?(File.join(dir, '.git'))
+
+        parent = File.dirname(dir)
+        return nil if parent == dir
+
+        dir = parent
+      end
+    end
+  end
+end

data/lib/envvariablecheck/classifier.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module EnvVariableCheck
+  # Decides whether a variable should be ranked as a secret.
+  class Classifier
+    PASSWORD_NAME = /(PASSWORD|PASSWD|PWD)/i.freeze
+    PUBLIC_NAME = /(PUBLIC[_-]?KEY|PUBLISHABLE[_-]?KEY)/i.freeze
+    IDENTIFIER_NAME = /(KEY_ID|ACCESS_KEY_ID|CLIENT_ID)\z/i.freeze
+    CONNECTION_NAME = /(DATABASE|DB|REDIS|MONGO(?:DB)?|MYSQL|POSTGRES(?:QL)?|AMQP|RABBIT(?:MQ)?|BROKER|CACHE|ELASTIC(?:SEARCH)?)[_-]?(?:URL|URI|DSN)/i.freeze
+    SECRET_NAME = /(SECRET|TOKEN|API[_-]?KEY|PRIVATE[_-]?KEY|MASTER[_-]?KEY|CLIENT[_-]?SECRET|CREDENTIAL|SIGNING[_-]?KEY|ENCRYPTION[_-]?KEY|SESSION[_-]?(?:SECRET|KEY)|JWT|SALT|AUTH[_-]?(?:TOKEN|SECRET|KEY)|ACCESS[_-]?KEY)/i.freeze
+    EMBEDDED_PASSWORD = %r{\A[A-Za-z][A-Za-z0-9+.\-]*://[^/\s]*:[^/\s]*@}i.freeze
+    CREDENTIAL_VALUE = /\A(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]+\z/.freeze
+
+    def self.classify(name, value)
+      value = value.to_s
+      return :token if value.include?('PRIVATE KEY') || value.match?(CREDENTIAL_VALUE)
+      return :identifier if name.match?(IDENTIFIER_NAME)
+      return :connection_url if name.match?(CONNECTION_NAME) || value.match?(EMBEDDED_PASSWORD)
+      return :password if name.match?(PASSWORD_NAME)
+      return :public if name.match?(PUBLIC_NAME)
+      return :token if name.match?(SECRET_NAME)
+
+      :config
+    end
+
+    # Password embedded in a connection URL, or nil when the URL has no
+    # user:password section. An empty string means the password is present
+    # and blank.
+    def self.extract_password(value)
+      match = value.to_s.match(%r{\A[A-Za-z][A-Za-z0-9+.\-]*://([^/\s@]*)@}i)
+      return nil unless match
+
+      userinfo = match[1]
+      return nil unless userinfo.include?(':')
+
+      _user, password = userinfo.split(':', 2)
+      percent_decode(password.to_s)
+    end
+
+    def self.percent_decode(text)
+      decoded = text.gsub(/%([0-9A-Fa-f]{2})/) { [Regexp.last_match(1).to_i(16)].pack('C') }
+      decoded.force_encoding('UTF-8')
+      decoded.valid_encoding? ? decoded : decoded.scrub
+    end
+
+    def self.url?(value)
+      value.to_s.match?(%r{\A[A-Za-z][A-Za-z0-9+.\-]*://}i)
+    end
+  end
+end