envvariablecheck 0.1.0

data/lib/envvariablecheck/cli.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'rbconfig'
+
+module EnvVariableCheck
+  # Command line for injecting .env and printing a security review.
+  module CLI
+    HELP = <<~'HELP'.freeze
+      envcheck — load ~/.env and rank secret strength
+
+      Usage:
+        envcheck run [options] SCRIPT [ARGS...]
+        envcheck audit [options] [FILE]
+        envcheck export [options] [FILE]
+        envcheck version
+        envcheck help
+
+      Commands:
+        run      Inject ~/.env into the environment, then execute a Ruby script
+        audit    Rank the keys and passwords in ~/.env
+        export   Print shell exports for the current terminal
+                 eval "$(envcheck export)"
+
+      Options:
+        --env PATH       Env file to read (default: ~/.env)
+        --override       Replace variables already set in the environment (run)
+        --strict         Exit 1 when a secret is Weak or Critical, or the file
+                         is group-readable or not gitignored
+        --format FORMAT  audit output: text or json (default: text)
+        --quiet          On run, do not print the injection summary
+        --[no-]color     Color the text report
+
+      Quote rules for the env file follow the shell:
+        KEY=value          bare values expand $VAR and ${VAR}
+        export KEY=value   same, with an optional export prefix
+        'literal $VALUE'   single quotes are not expanded
+        "line\nnext"       double quotes expand $VAR plus \n \t \r \\ \" \$
+
+      Use single quotes for secrets that contain $. The last assignment wins.
+      The review prints the env file in full. Nothing is uploaded.
+    HELP
+
+    module_function
+
+    def start(argv)
+      dispatch(Array(argv).dup)
+    rescue UsageError => e
+      warn "envcheck: #{e.message}"
+      warn 'See `envcheck help`.'
+      2
+    rescue Error => e
+      warn "envcheck: #{e.message}"
+      1
+    end
+
+    def dispatch(argv)
+      command = argv.shift
+      case command
+      when nil, 'help', '-h', '--help'
+        $stdout.puts HELP
+        0
+      when 'version', '-v', '--version'
+        $stdout.puts "envvariablecheck #{VERSION}"
+        0
+      when 'audit'
+        audit(argv)
+      when 'run'
+        run(argv)
+      when 'export'
+        export_cmd(argv)
+      else
+        raise UsageError, "Unknown command #{command.inspect}."
+      end
+    end
+
+    def audit(argv)
+      options = defaults
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: envcheck audit [options] [FILE]'
+        opts.on('--env PATH', 'Env file (default: ~/.env)') { |value| options[:env] = value }
+        opts.on('--strict', 'Exit 1 for Weak, Critical, or an exposed file') { options[:strict] = true }
+        opts.on('--format FORMAT', 'text or json (default: text)') { |value| options[:format] = value }
+        opts.on('--[no-]color', 'Colorize the text report') { |value| options[:color] = value }
+      end
+      parse!(parser, argv)
+      path = argv.shift || options[:env]
+      raise UsageError, "Unexpected argument #{argv.first.inspect}." unless argv.empty?
+
+      report = Auditor.audit_file(path)
+      case options[:format].to_s.downcase
+      when 'text'
+        $stdout.puts Report.text(report, color: color_enabled?(options, $stdout))
+      when 'json'
+        $stdout.print Report.json(report)
+      else
+        raise UsageError, "Unknown format #{options[:format].inspect}. Use text or json."
+      end
+      options[:strict] && report.failing? ? 1 : 0
+    end
+
+    def export_cmd(argv)
+      options = defaults
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: envcheck export [options] [FILE]'
+        opts.on('--env PATH', 'Env file (default: ~/.env)') { |value| options[:env] = value }
+      end
+      parse!(parser, argv)
+      path = argv.shift || options[:env]
+      raise UsageError, "Unexpected argument #{argv.first.inspect}." unless argv.empty?
+
+      assignments = Parser.parse(Parser.read(path), path: path)
+      $stdout.print Loader.shell_exports(assignments)
+      0
+    end
+
+    def run(argv)
+      options = defaults
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: envcheck run [options] SCRIPT [ARGS...]'
+        opts.on('--env PATH', 'Env file (default: ~/.env)') { |value| options[:env] = value }
+        opts.on('--override', 'Replace variables already set in the environment') { options[:override] = true }
+        opts.on('--strict', 'Do not run when the review fails') { options[:strict] = true }
+        opts.on('--quiet', 'Do not print the injection summary') { options[:quiet] = true }
+        opts.on('--[no-]color', 'Colorize ranks in the summary') { |value| options[:color] = value }
+      end
+      order!(parser, argv)
+      script = argv.shift
+      raise UsageError, 'Missing Ruby script. Usage: envcheck run [options] SCRIPT [ARGS...]' if script.nil? || script.empty?
+      raise UsageError, "Ruby script not found: #{script}" unless File.file?(script)
+
+      path = options[:env]
+      report = Auditor.audit_file(path)
+      if options[:strict] && report.failing?
+        $stderr.puts Report.text(report, color: color_enabled?(options, $stderr))
+        return 1
+      end
+
+      loaded = Loader.load(path, override: options[:override])
+      unless options[:quiet]
+        $stderr.puts Report.run_banner(
+          report,
+          path: path,
+          applied: loaded.applied,
+          skipped: loaded.skipped,
+          color: color_enabled?(options, $stderr)
+        )
+        loaded.warnings.each { |warning| $stderr.puts "envcheck: #{warning}" }
+      end
+      $stderr.flush
+      $stdout.flush
+      exec(RbConfig.ruby, script, *argv)
+    rescue SystemCallError => e
+      raise Error, "Could not execute #{script}: #{e.message}"
+    end
+
+    def defaults
+      {
+        env: EnvVariableCheck.default_path,
+        override: false,
+        strict: false,
+        format: 'text',
+        quiet: false,
+        color: nil
+      }
+    end
+
+    def parse!(parser, argv)
+      parser.parse!(argv)
+    rescue OptionParser::ParseError => e
+      raise UsageError, e.message
+    end
+
+    def order!(parser, argv)
+      parser.order!(argv)
+    rescue OptionParser::ParseError => e
+      raise UsageError, e.message
+    end
+
+    def color_enabled?(options, io)
+      return options[:color] unless options[:color].nil?
+      return false if ENV.key?('NO_COLOR')
+
+      io.respond_to?(:tty?) && io.tty?
+    end
+  end
+end

data/lib/envvariablecheck/common_passwords.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module EnvVariableCheck
+  # Local blocklist of commonly chosen passwords. This stays on the machine:
+  # secrets are never sent to a breach-search service.
+  module CommonPasswords
+    BASE = %w[
+      000000 111111 11111111 112233 121212 123123 12345 123456 1234567
+      12345678 123456789 1234567890 123qwe 131313 159753 1q2w3e 1q2w3e4r
+      1q2w3e4r5t 1qaz2wsx 555555 654321 666666 696969 7777777 888888
+      987654321 999999 aaaaaa abc123 abc123456 abcd1234 access admin
+      admin123 adobe123 amanda andrew ashley austin azerty baseball batman
+      biteme bonjour buster changeme changeme123 charlie cheese chelsea
+      computer corvette dallas daniel default dragon dragon1 facebook
+      ferrari football freedom ginger guest harley hello hello123 hockey
+      hunter hunter2 iloveyou iloveyou1 jennifer jessica jordan letmein
+      letmein1 login love maggie master matrix mercedes michael michelle
+      money monkey monkey1 mustang nicole pass123 passwd passwd123 password
+      password1 password123 passw0rd p@ssw0rd p@ssword pepper princess
+      princess1 qazwsx qazwsxedc qwerty qwerty123 qwertyuiop ranger robert
+      root secret secret123 shadow soccer starwars summer sunshine superman
+      taylor test test123 thomas thunder tigger toor trustno1 welcome
+      welcome1 whatever yankees zaq12wsx zxcvbn
+    ].freeze
+
+    PHRASES = [
+      'correct horse battery staple',
+      'correcthorsebatterystaple',
+      'deadbeef'
+    ].freeze
+
+    WORDS = {}
+    (BASE + PHRASES).each { |word| WORDS[word] = true }
+    WORDS.freeze
+
+    # :exact when the whole value is a blocked password.
+    # :variant when digits, symbols, or light leet-speak are wrapped around one.
+    # nil otherwise.
+    def self.match(value)
+      base = value.to_s.strip.downcase
+      return :exact if WORDS.key?(base)
+
+      squished = base.gsub(/\s+/, '')
+      return :exact if WORDS.key?(squished)
+      return nil if base.length >= 24
+      return nil if base.match?(/\A[0-9a-f]{16,}\z/i)
+
+      folded = leet_fold(base)
+      return :variant if WORDS.key?(folded)
+
+      # Drop a trailing year, digits, or symbol before folding. Folding first
+      # would turn the 0 in 2024 into a letter and hide the base word.
+      stem = base.sub(/[^a-z]+\z/, '')
+      return nil if stem.length < 4 || stem == base
+
+      return :variant if WORDS.key?(stem) || WORDS.key?(leet_fold(stem))
+
+      nil
+    end
+
+    def self.leet_fold(text)
+      text.tr('@0$3', 'aose')
+    end
+  end
+end

data/lib/envvariablecheck/entropy.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module EnvVariableCheck
+  # Estimates how hard a value is to guess, and flags shapes that only look random.
+  module Entropy
+    ALPHABETS = [
+      'abcdefghijklmnopqrstuvwxyz',
+      '01234567890',
+      'qwertyuiop',
+      'asdfghjkl',
+      'zxcvbnm',
+      'qwertyuiopasdfghjklzxcvbnm'
+    ].freeze
+
+    def self.charset_bits(value)
+      pool = pool_size(value)
+      return 0.0 if value.empty? || pool <= 1
+
+      value.length * Math.log2(pool)
+    end
+
+    def self.shannon_bits(value)
+      return 0.0 if value.empty?
+
+      freq = Hash.new(0)
+      value.each_char { |char| freq[char] += 1 }
+      length = value.length.to_f
+      per_char = freq.each_value.inject(0.0) do |sum, count|
+        probability = count / length
+        sum - (probability * Math.log2(probability))
+      end
+      per_char * length
+    end
+
+    def self.low_diversity?(value)
+      return false if value.length < 4
+
+      shannon_bits(value) / value.length < 2.0
+    end
+
+    def self.estimate_bits(value)
+      if value.empty? || low_diversity?(value) || repeated_pattern?(value)
+        shannon_bits(value)
+      else
+        charset_bits(value)
+      end
+    end
+
+    def self.pool_size(value)
+      return 16 if value.match?(/\A[0-9a-f]+\z/i)
+      return 64 if value.match?(%r{\A[A-Za-z0-9+/]+=*\z}) && value.match?(%r{[+/]})
+
+      pool = 0
+      pool += 26 if value.match?(/[a-z]/)
+      pool += 26 if value.match?(/[A-Z]/)
+      pool += 10 if value.match?(/\d/)
+      pool += 32 if value.match?(/[^A-Za-z0-9]/)
+      pool
+    end
+
+    def self.sequential_run(value)
+      downcased = value.downcase
+      best = 1
+      alphabets.each do |alphabet|
+        max = [downcased.length, alphabet.length].min
+        4.upto(max) do |length|
+          0.upto(downcased.length - length) do |index|
+            best = length if alphabet.include?(downcased[index, length])
+          end
+        end
+      end
+      best
+    end
+
+    def self.sequential?(value)
+      run = sequential_run(value)
+      return false if run < 4
+
+      value.length < 16 || (run.to_f / value.length) >= 0.5
+    end
+
+    def self.repeated_pattern?(value)
+      return false if value.length < 4
+      return true if value.match?(/(.)\1{3,}/)
+      return true if value.length.even? && value[0, value.length / 2] * 2 == value
+
+      limit = [6, value.length / 3].min
+      1.upto(limit) do |size|
+        times = value.length / size
+        next if times < 3
+        next if (times * size) != value.length
+
+        chunk = value[0, size]
+        return true if chunk * times == value
+      end
+      false
+    end
+
+    def self.alphabets
+      reversed = ALPHABETS.map(&:reverse)
+      ALPHABETS + reversed
+    end
+  end
+end

data/lib/envvariablecheck/load.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Inject ~/.env into the current Ruby process.
+# Usage: ruby -r envvariablecheck/load script.rb
+require 'envvariablecheck'
+
+EnvVariableCheck.load!

data/lib/envvariablecheck/loader.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module EnvVariableCheck
+  # Merges parsed assignments into the current process environment.
+  class Loader
+    LoadResult = Struct.new(:applied, :skipped, :warnings, keyword_init: true)
+
+    def self.load(path, override: false)
+      assignments = Parser.parse(Parser.read(path), path: path)
+      apply(assignments, override: override)
+    end
+
+    def self.apply(assignments, override: false)
+      collapsed, _counts = Parser.collapse(assignments)
+      applied = []
+      skipped = []
+      warnings = []
+
+      collapsed.each do |assignment|
+        if !override && ENV.key?(assignment.key)
+          skipped << assignment.key
+          next
+        end
+
+        begin
+          ENV[assignment.key] = assignment.value
+          applied << assignment.key
+        rescue ArgumentError => e
+          warnings << "#{assignment.key} was not injected (#{e.message})."
+        end
+      end
+
+      LoadResult.new(applied: applied, skipped: skipped, warnings: warnings)
+    end
+
+    def self.shell_exports(assignments)
+      collapsed, _counts = Parser.collapse(assignments)
+      return '' if collapsed.empty?
+
+      lines = collapsed.map do |assignment|
+        "export #{assignment.key}=#{shell_single_quote(assignment.value)}"
+      end
+      "#{lines.join("\n")}\n"
+    end
+
+    def self.shell_single_quote(value)
+      "'" + value.to_s.gsub("'", "'\"'\"'") + "'"
+    end
+  end
+end

data/lib/envvariablecheck/parser.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module EnvVariableCheck
+  # Parses a shell-style env file. Resolved values are what will be injected.
+  # Single quotes are literal. Double quotes and bare values expand $VAR and
+  # ${VAR} from earlier keys in the file, then from ENV.
+  class Parser
+    Assignment = Struct.new(:key, :value, :line, keyword_init: true)
+
+    LINE = /\A\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\z/.freeze
+    INTERPOLATION = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/.freeze
+    DOLLAR = "\uE000".freeze
+
+    def self.read(path)
+      if File.directory?(path)
+        raise Error, "#{path} is a directory, not an env file."
+      end
+      unless File.file?(path)
+        raise Error, "Env file not found: #{path}"
+      end
+
+      contents = File.binread(path)
+      contents.force_encoding('UTF-8')
+      contents.valid_encoding? ? contents : contents.scrub
+    end
+
+    def self.parse(contents, path: '.env')
+      new(contents.to_s, path).parse
+    end
+
+    # Last assignment wins, matching shell and ENV behavior.
+    # Returns [assignments, counts] where counts includes duplicates.
+    def self.collapse(assignments)
+      order = []
+      last = {}
+      counts = Hash.new(0)
+      assignments.each do |assignment|
+        order << assignment.key unless last.key?(assignment.key)
+        last[assignment.key] = assignment
+        counts[assignment.key] += 1
+      end
+      [order.map { |key| last[key] }, counts]
+    end
+
+    def initialize(contents, path)
+      normalized = contents.dup
+      normalized.sub!(/\A\uFEFF/, '')
+      normalized.gsub!(/\r\n?/, "\n")
+      @path = path
+      @lines = normalized.split("\n", -1)
+      @index = 0
+      @defined = {}
+    end
+
+    def parse
+      assignments = []
+      while @index < @lines.length
+        line = @lines[@index]
+        line_no = @index + 1
+        if blank_or_comment?(line)
+          @index += 1
+          next
+        end
+
+        match = line.match(LINE)
+        unless match
+          raise Error, "Cannot parse #{@path}:#{line_no}. Expected KEY=VALUE."
+        end
+
+        key = match[1]
+        style, raw = read_value(match[2], line_no)
+        value = resolve(raw, style)
+        @defined[key] = value
+        assignments << Assignment.new(key: key, value: value, line: line_no)
+      end
+      assignments
+    end
+
+    private
+
+    def blank_or_comment?(line)
+      stripped = line.strip
+      stripped.empty? || stripped.start_with?('#')
+    end
+
+    def read_value(rest, line_no)
+      if rest.start_with?("'")
+        [:single, read_quoted(rest, "'", line_no)]
+      elsif rest.start_with?('"')
+        [:double, read_quoted(rest, '"', line_no)]
+      else
+        @index += 1
+        [:bare, rest.sub(/\s+#.*\z/, '').rstrip.sub(/\A[ \t]+/, '')]
+      end
+    end
+
+    def read_quoted(rest, quote, line_no)
+      body = rest[1..-1].to_s
+      chunks = []
+      loop do
+        idx = quote == "'" ? body.index("'") : index_unescaped_quote(body)
+        if idx
+          chunks << body[0...idx]
+          trailing = body[(idx + 1)..-1].to_s
+          unless trailing.strip.empty? || trailing.strip.start_with?('#')
+            raise Error, "Unexpected trailing content at #{@path}:#{@index + 1}."
+          end
+          @index += 1
+          return chunks.join("\n")
+        end
+
+        chunks << body
+        @index += 1
+        if @index >= @lines.length
+          raise Error, "Unclosed #{quote} quote starting at #{@path}:#{line_no}."
+        end
+        body = @lines[@index]
+      end
+    end
+
+    def index_unescaped_quote(body)
+      search_from = 0
+      while (idx = body.index('"', search_from))
+        slashes = 0
+        cursor = idx - 1
+        while cursor >= 0 && body[cursor] == '\\'
+          slashes += 1
+          cursor -= 1
+        end
+        return idx if slashes.even?
+
+        search_from = idx + 1
+      end
+      nil
+    end
+
+    def resolve(raw, style)
+      case style
+      when :single
+        raw
+      when :double
+        interpolate(unescape_double(raw))
+      else
+        interpolate(raw.gsub('\\$', DOLLAR))
+      end
+    end
+
+    def unescape_double(value)
+      value.gsub(/\\./m) do |seq|
+        case seq[1]
+        when 'n' then "\n"
+        when 'r' then "\r"
+        when 't' then "\t"
+        when '\\' then '\\'
+        when '"' then '"'
+        when '$' then DOLLAR
+        else seq[1]
+        end
+      end
+    end
+
+    def interpolate(value)
+      expanded = value.gsub(INTERPOLATION) do
+        name = Regexp.last_match(1) || Regexp.last_match(2)
+        if @defined.key?(name)
+          @defined[name]
+        elsif ENV.key?(name)
+          ENV[name]
+        else
+          ''
+        end
+      end
+      expanded.gsub(DOLLAR, '$')
+    end
+  end
+end