envvariablecheck 0.1.0

data/lib/envvariablecheck/report.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module EnvVariableCheck
+  # Renders an audit, including the raw env file when it was read from disk.
+  module Report
+    LABELS = {
+      'password' => 'password',
+      'token' => 'token',
+      'connection_url' => 'connection url',
+      'config' => 'config',
+      'identifier' => 'identifier',
+      'public' => 'public key'
+    }.freeze
+
+    module_function
+
+    def text(audit, color: false)
+      secrets, unscored = ordered(audit)
+      lines = []
+      lines << "envvariablecheck #{VERSION}"
+      lines << "File: #{audit.path || '(assignments)'}"
+      if secrets.empty?
+        lines << 'Overall: nothing to rank'
+      else
+        rank = paint(audit.overall_rank, audit.overall_rank, color)
+        lines << "Overall: #{rank} (weakest secret #{audit.overall_score}/100)"
+      end
+      lines << ''
+
+      if secrets.empty?
+        lines << 'No secret-like variables found.'
+      else
+        lines << 'Secrets'
+        secrets.each { |variable| lines.concat(secret_lines(variable, color)) }
+      end
+
+      unless unscored.empty?
+        lines << '' if lines.last != ''
+        lines << 'Not scored'
+        unscored.each { |variable| lines.concat(plain_lines(variable)) }
+      end
+
+      unless audit.file_findings.empty?
+        lines << ''
+        lines << 'File'
+        audit.file_findings.each { |finding| lines << "  - #{finding}" }
+      end
+
+      lines << ''
+      lines << summary_line(audit)
+      lines << 'Length is the primary control (NIST SP 800-63B). Use a unique random value per secret: at least 15 characters for passwords, and at least 32 for API keys and tokens.'
+      with_contents(lines.join("\n"), audit)
+    end
+
+    def json(audit)
+      JSON.pretty_generate(audit.to_h) + "\n"
+    end
+
+    def run_banner(audit, path:, applied:, skipped:, color: false)
+      lines = []
+      lines << "envcheck: injected #{count_label(applied.length, 'variable')} from #{path}"
+      unless skipped.empty?
+        lines << "envcheck: kept #{count_label(skipped.length, 'variable')} already set (#{skipped.join(', ')})"
+      end
+      audit.file_findings.each { |finding| lines << "envcheck: #{finding}" }
+
+      if audit.secrets.empty?
+        lines << 'envcheck: no secret-like variables to rank'
+      else
+        lines << "envcheck: #{path} security rank #{paint(audit.overall_rank, audit.overall_rank, color)}"
+        weak = audit.secrets.select { |variable| variable.rank == 'Critical' || variable.rank == 'Weak' }
+        weak.sort_by { |variable| [Auditor::RANK_ORDER.index(variable.rank), variable.score] }.each do |variable|
+          lines << format('  %s  %s  %d/100', variable.name, paint(variable.rank, variable.rank, color), variable.score)
+          variable.findings.each { |finding| lines << "    - #{finding}" }
+        end
+      end
+      with_contents(lines.join("\n"), audit)
+    end
+
+    def with_contents(text, audit)
+      return text if audit.contents.nil?
+
+      "#{text}\n\nContents\n#{audit.contents}"
+    end
+
+    def ordered(audit)
+      secrets = audit.variables.select(&:scored).sort_by do |variable|
+        [Auditor::RANK_ORDER.index(variable.rank), variable.score, variable.name]
+      end
+      [secrets, audit.variables.reject(&:scored)]
+    end
+
+    def secret_lines(variable, color)
+      bits = variable.charset_bits.nil? ? '?' : "~#{variable.charset_bits.round} bits"
+      lines = [variable.name]
+      lines << "  #{label(variable.kind)} · #{paint(variable.rank, variable.rank, color)} · #{variable.score}/100 · #{bits} · line #{variable.line}"
+      variable.findings.each { |finding| lines << "  - #{finding}" }
+      lines << ''
+      lines
+    end
+
+    def plain_lines(variable)
+      lines = ["  #{variable.name} · #{label(variable.kind)} · line #{variable.line}"]
+      variable.findings.each { |finding| lines << "    - #{finding}" }
+      lines
+    end
+
+    def summary_line(audit)
+      counts = audit.counts
+      [
+        count_label(audit.variables.length, 'variable'),
+        "#{counts['Critical']} critical",
+        "#{counts['Weak']} weak",
+        "#{counts['Fair']} fair",
+        "#{counts['Strong']} strong",
+        "#{counts['Excellent']} excellent",
+        "#{counts['Unscored']} not scored"
+      ].join(' · ')
+    end
+
+    def label(kind)
+      LABELS[kind.to_s] || kind.to_s
+    end
+
+    def count_label(count, noun)
+      count == 1 ? "1 #{noun}" : "#{count} #{noun}s"
+    end
+
+    def paint(text, rank, enabled)
+      return text unless enabled
+
+      code = {
+        'Critical' => '1;31',
+        'Weak' => '31',
+        'Fair' => '33',
+        'Strong' => '36',
+        'Excellent' => '32'
+      }[rank]
+      return text unless code
+
+      "\e[#{code}m#{text}\e[0m"
+    end
+  end
+end

data/lib/envvariablecheck/scorer.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module EnvVariableCheck
+  # Ranks one secret using password best practices.
+  #
+  # Length is the main control (NIST SP 800-63B requires at least 8 and this
+  # tool expects 15 or more for application passwords). Composition is only a
+  # bonus. Common passwords, placeholders, reuse, repetition, and predictable
+  # shapes are capped hard so they cannot outscore a random value.
+  class Scorer
+    Result = Struct.new(:score, :rank, :findings, :charset_bits, keyword_init: true)
+
+    PLACEHOLDER = Regexp.new(
+      '\A(?:changeme\d*|change\s*me\d*|todo|fixme|x{3,}|your[-_].+|example\d*|' \
+      'placeholder|sample|dummy|fake|temp(?:orary)?|test(?:ing)?\d*|foo|bar|baz|' \
+      'n/a|none|null|nil|undefined|default|replace[-_].+|insert[-_].+|\*{3,}|' \
+      '<[^>]*>|\$\{[^}]+\})\z',
+      Regexp::IGNORECASE
+    ).freeze
+
+    WEAK_LITERALS = %w[
+      true false yes no on off dev development prod production staging local
+      localhost enable enabled disable disabled debug release
+    ].each_with_object({}) { |word, hash| hash[word] = true }.freeze
+
+    PREDICTABLE = [
+      [/\A[A-Z][a-z]{2,16}\d{2,4}[^A-Za-z0-9]?\z/, 'a capitalized word, digits, and an optional symbol'],
+      [/\A[A-Za-z]{4,16}\d{1,6}\z/, 'a word followed by digits'],
+      [/\A[A-Za-z]{4,16}[^A-Za-z0-9]\z/, 'a short word plus one symbol']
+    ].freeze
+
+    def self.score(value, kind:, name:, reused_names: [])
+      new(value.to_s, kind, name.to_s, reused_names).result
+    end
+
+    def self.rank_for(score)
+      if score >= 90
+        'Excellent'
+      elsif score >= 75
+        'Strong'
+      elsif score >= 50
+        'Fair'
+      elsif score >= 25
+        'Weak'
+      else
+        'Critical'
+      end
+    end
+
+    def initialize(value, kind, name, reused_names)
+      @value = value
+      @kind = kind
+      @name = name
+      @reused_names = reused_names
+      @findings = []
+      @caps = [100]
+    end
+
+    def result
+      if @value.strip.empty?
+        return Result.new(score: 0, rank: 'Critical', findings: ['Value is empty.'], charset_bits: 0.0)
+      end
+
+      bits = Entropy.estimate_bits(@value)
+      add_length_findings
+      add_blocklist_findings
+      add_shape_findings
+      add_reuse_finding
+      add_prefix_findings
+
+      points = length_points + diversity_points + entropy_points(bits)
+      @caps << length_cap
+      score = points.clamp(0, @caps.min)
+
+      Result.new(
+        score: score,
+        rank: self.class.rank_for(score),
+        findings: @findings.uniq,
+        charset_bits: bits.round(1)
+      )
+    end
+
+    private
+
+    def add_length_findings
+      length = @value.length
+      if @kind == :token
+        if length < 8
+          @findings << 'Below the 8 character minimum from NIST SP 800-63B.'
+        elsif length < 32
+          @findings << 'Shorter than 32 characters. API keys and tokens should be at least 32 characters from a CSPRNG.'
+        end
+      elsif length < 8
+        @findings << 'Below the 8 character minimum from NIST SP 800-63B.'
+      elsif length < 15
+        @findings << 'Meets the 8 character minimum, but application secrets should be at least 15 characters.'
+      end
+    end
+
+    def add_blocklist_findings
+      case CommonPasswords.match(@value)
+      when :exact
+        @findings << 'Matches a commonly used password. Replace it with a value from a CSPRNG.'
+        @caps << 12
+      when :variant
+        @findings << 'Built on a common password with small changes. Those changes are easy to guess.'
+        @caps << 20
+      end
+
+      if @value.match?(PLACEHOLDER)
+        @findings << 'Looks like a placeholder or example, not a real secret.'
+        @caps << 10
+      end
+
+      if WEAK_LITERALS.key?(@value.strip.downcase)
+        @findings << 'Value is a common literal such as true, false, or an environment name.'
+        @caps << 15
+      end
+
+      if same_as_name?
+        @findings << 'Value matches the variable name.'
+        @caps << 8
+      end
+    end
+
+    def add_shape_findings
+      pattern = predictable_pattern
+      if pattern
+        @findings << "Matches a predictable pattern (#{pattern})."
+        @caps << 40
+      end
+
+      if Entropy.low_diversity?(@value) && !Entropy.repeated_pattern?(@value)
+        @findings << 'Low character diversity for its length, so the value looks repetitive.'
+        @caps << 35
+      end
+
+      if Entropy.sequential?(@value)
+        @findings << 'Contains a sequential or keyboard run such as 1234, abcd, or qwerty.'
+        @caps << (@value.length < 20 ? 35 : 70)
+      end
+
+      if Entropy.repeated_pattern?(@value)
+        @findings << 'Contains a long repeated character or a repeating chunk.'
+        @caps << 20
+      end
+
+      if @value.match?(/\A\d+\z/)
+        @findings << 'Digits only. A numeric secret has a small alphabet and needs to be much longer.'
+        @caps << (@value.length >= 32 ? 80 : 20)
+      elsif single_class? && !@value.match?(/\A[0-9a-f]+\z/i) && @value.length < 20
+        @findings << 'Uses only one character class, so length has to carry the strength.'
+      end
+    end
+
+    def add_reuse_finding
+      return if @reused_names.empty?
+
+      @findings << "Same value is also used by #{@reused_names.join(', ')}. Use a unique secret for each variable."
+      @caps << 89
+    end
+
+    def add_prefix_findings
+      if @value.include?('PRIVATE KEY')
+        @findings << 'A PEM private key is embedded in the env file. Prefer a separate file with mode 0600 and keep it out of git.'
+      end
+      if @value.match?(/\A(?:sk|pk|rk)_test_/i)
+        @findings << 'Uses a test-mode key prefix. Test keys are still secrets; keep them out of git.'
+        @caps << 89
+      end
+      return unless @value.match?(/\Apk_(?:live|test)_/i)
+
+      @findings << 'Uses a publishable-key prefix. Confirm this is not a secret key.'
+    end
+
+    def length_points
+      length = @value.length
+      return 40 if length >= 32
+      return 36 if length >= 20
+      return 32 if length >= 16
+      return 30 if length >= 15
+      return 22 if length >= 12
+      return 14 if length >= 8
+
+      4
+    end
+
+    def diversity_points
+      classes = 0
+      classes += 1 if @value.match?(/[a-z]/)
+      classes += 1 if @value.match?(/[A-Z]/)
+      classes += 1 if @value.match?(/\d/)
+      classes += 1 if @value.match?(/[^A-Za-z0-9]/)
+      classes * 5
+    end
+
+    def entropy_points(bits)
+      return 40 if bits >= 128
+      return 36 if bits >= 80
+      return 28 if bits >= 60
+      return 18 if bits >= 40
+      return 10 if bits >= 28
+
+      0
+    end
+
+    def length_cap
+      length = @value.length
+      if @kind == :token
+        return 24 if length < 16
+        return 74 if length < 32
+
+        return 100
+      end
+      return 20 if length < 8
+      return 49 if length < 12
+      return 74 if length < 15
+
+      100
+    end
+
+    def predictable_pattern
+      PREDICTABLE.each do |pattern, label|
+        return label if @value.match?(pattern)
+      end
+      nil
+    end
+
+    def same_as_name?
+      left = @value.downcase.gsub(/[^a-z0-9]/, '')
+      right = @name.downcase.gsub(/[^a-z0-9]/, '')
+      !left.empty? && left == right
+    end
+
+    def single_class?
+      classes = 0
+      classes += 1 if @value.match?(/[a-z]/)
+      classes += 1 if @value.match?(/[A-Z]/)
+      classes += 1 if @value.match?(/\d/)
+      classes += 1 if @value.match?(/[^A-Za-z0-9]/)
+      classes == 1
+    end
+  end
+end

data/lib/envvariablecheck/version.rb

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

data/lib/envvariablecheck.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'envvariablecheck/version'
+
+module EnvVariableCheck
+  # Raised when an env file cannot be read, parsed, or injected.
+  class Error < StandardError; end
+
+  # Raised for bad commands and flags. The CLI turns this into exit status 2.
+  class UsageError < Error; end
+
+  # Default env file: ~/.env, expanded when a command runs.
+  def self.default_path
+    File.expand_path('~/.env')
+  end
+
+  # Read +path+ and merge it into ENV. Existing variables are kept unless
+  # +override+ is true. Returns a Loader::LoadResult.
+  def self.load!(path: default_path, override: false)
+    Loader.load(path, override: override)
+  end
+
+  # Rank the keys and passwords in an env file. The report includes the file text.
+  def self.audit(path: default_path)
+    Auditor.audit_file(path)
+  end
+end
+
+require 'envvariablecheck/parser'
+require 'envvariablecheck/loader'
+require 'envvariablecheck/classifier'
+require 'envvariablecheck/common_passwords'
+require 'envvariablecheck/entropy'
+require 'envvariablecheck/scorer'
+require 'envvariablecheck/auditor'
+require 'envvariablecheck/report'
+require 'envvariablecheck/cli'

data/test/auditor_test.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+require 'fileutils'
+
+class AuditorTest < Minitest::Test
+  STRONG = 'aB3dE6gH9kL2mN5pQ8sT1uV4wX7yZ0cR'
+
+  def audit(contents)
+    assignments = EnvVariableCheck::Parser.parse(contents)
+    EnvVariableCheck::Auditor.audit_assignments(assignments)
+  end
+
+  def variable(report, name)
+    report.variables.find { |item| item.name == name }
+  end
+
+  def test_overall_rank_follows_the_weakest_secret
+    report = audit(<<~ENV)
+      PORT=3000
+      API_TOKEN=#{STRONG}
+      DB_PASSWORD=password
+    ENV
+    assert_equal 'Critical', report.overall_rank
+    assert_equal 'Excellent', variable(report, 'API_TOKEN').rank
+    refute variable(report, 'PORT').scored
+    assert_equal 'config', variable(report, 'PORT').kind.to_s
+  end
+
+  def test_connection_url_ranks_the_embedded_password_only
+    secret = 'UrlCanarySecret99!'
+    report = audit("DATABASE_URL=postgres://app:#{secret}@localhost:5432/app\nAPP_URL=https://example.com\n")
+    database = variable(report, 'DATABASE_URL')
+    assert database.scored
+    assert_includes %w[Strong Excellent], database.rank
+    assert_match(/embedded password/, database.findings.join)
+    refute_includes EnvVariableCheck::Report.text(report), secret
+
+    plain = variable(report, 'APP_URL')
+    refute plain.scored
+    assert_equal 'config', plain.kind.to_s
+  end
+
+  def test_url_without_a_password_is_not_scored
+    report = audit("DATABASE_URL=postgres://localhost/app\n")
+    database = variable(report, 'DATABASE_URL')
+    refute database.scored
+    assert_match(/no embedded password/, database.findings.join)
+  end
+
+  def test_percent_encoded_password_is_ranked_and_not_printed
+    report = audit("DATABASE_URL=postgres://app:p%40ssword@localhost/app\n")
+    text = EnvVariableCheck::Report.text(report)
+    assert_equal 'Critical', variable(report, 'DATABASE_URL').rank
+    refute_includes text, 'p@ssword'
+    refute_includes text, 'p%40ssword'
+  end
+
+  def test_key_id_is_an_identifier
+    report = audit("AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\nAWS_SECRET_ACCESS_KEY=#{STRONG}\n")
+    identifier = variable(report, 'AWS_ACCESS_KEY_ID')
+    refute identifier.scored
+    assert_match(/sample or placeholder/, identifier.findings.join)
+    assert_equal 'Excellent', variable(report, 'AWS_SECRET_ACCESS_KEY').rank
+  end
+
+  def test_reused_secrets_are_named_but_not_printed
+    report = audit(<<~ENV)
+      API_TOKEN=#{STRONG}
+      BACKUP_TOKEN=#{STRONG}
+    ENV
+    assert_match(/BACKUP_TOKEN/, variable(report, 'API_TOKEN').findings.join)
+    refute_includes EnvVariableCheck::Report.text(report), STRONG
+    refute_equal 'Excellent', report.overall_rank
+  end
+
+  def test_high_entropy_config_is_called_out
+    report = audit("ASSET_HASH=#{STRONG}\n")
+    asset = variable(report, 'ASSET_HASH')
+    refute asset.scored
+    assert_match(/does not mark it as a secret/, asset.findings.join)
+  end
+
+  def test_duplicate_assignment_is_reported
+    report = audit("API_TOKEN=first\nAPI_TOKEN=#{STRONG}\n")
+    token = variable(report, 'API_TOKEN')
+    assert_equal 'Excellent', token.rank
+    assert_match(/more than once/, token.findings.join)
+  end
+
+  def test_loose_permissions_are_reported
+    with_env_file("API_TOKEN=#{STRONG}\n", mode: 0644) do |_dir, path|
+      report = EnvVariableCheck.audit(path: path)
+      assert report.file_findings.any? { |finding| finding.include?('0600') }
+      assert report.failing?
+    end
+  end
+
+  def test_private_file_outside_git_has_no_file_findings
+    with_env_file("API_TOKEN=#{STRONG}\n", mode: 0600) do |_dir, path|
+      report = EnvVariableCheck.audit(path: path)
+      assert_equal 'Excellent', report.overall_rank
+      assert_empty report.file_findings
+      refute report.failing?
+    end
+  end
+
+  def test_git_ignore_check
+    skip 'git is not available' unless system('git', '--version', out: File::NULL, err: File::NULL)
+
+    dir = File.expand_path('../tmp/git-check', __dir__)
+    FileUtils.rm_rf(dir)
+    FileUtils.mkdir_p(dir)
+    path = File.join(dir, '.env')
+    File.write(path, "API_TOKEN=#{STRONG}\n")
+    File.chmod(0600, path)
+    template = File.join(dir, 'git-template')
+    Dir.mkdir(template)
+    _out, err, status = Open3.capture3(
+      { 'GIT_TEMPLATE_DIR' => template },
+      'git', 'init', '-q', chdir: dir
+    )
+    flunk(err) unless status.success?
+
+    exposed = EnvVariableCheck.audit(path: path)
+    assert exposed.file_findings.any? { |finding| finding.include?('not ignored by git') }, exposed.file_findings.inspect
+
+    File.write(File.join(dir, '.gitignore'), ".env\n")
+    ignored = EnvVariableCheck.audit(path: path)
+    refute ignored.file_findings.any? { |finding| finding.include?('not ignored') }, ignored.file_findings.inspect
+  ensure
+    FileUtils.rm_rf(dir) if dir
+  end
+
+  def test_json_report_includes_the_file_and_not_a_separate_value_field
+    contents = "DB_PASSWORD=JsonCanarySecret99!\nPORT=3000\n"
+    with_env_file(contents, mode: 0600) do |_dir, path|
+      report = EnvVariableCheck.audit(path: path)
+      payload = JSON.parse(EnvVariableCheck::Report.json(report))
+      assert_equal contents, payload['contents']
+      assert_equal 'DB_PASSWORD', payload['variables'][0]['name']
+      assert payload['variables'][0]['scored']
+      refute payload['variables'][1]['scored']
+      assert_nil payload['variables'][0]['value']
+      assert_includes EnvVariableCheck::Report.text(report), contents
+    end
+  end
+end