envvariablecheck 0.1.0

data/test/cli_test.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class CliTest < Minitest::Test
+  STRONG = 'aB3dE6gH9kL2mN5pQ8sT1uV4wX7yZ0cR'
+
+  def test_help_and_version
+    status = nil
+    out, err = capture_io { status = EnvVariableCheck::CLI.start([]) }
+    assert_equal 0, status
+    assert_match(/envcheck run/, out)
+    assert_match(/prints the env file in full/, out)
+    assert_equal '', err
+
+    status = nil
+    out, _err = capture_io { status = EnvVariableCheck::CLI.start(['version']) }
+    assert_equal 0, status
+    assert_equal "envvariablecheck #{EnvVariableCheck::VERSION}\n", out
+  end
+
+  def test_unknown_command_and_missing_file
+    status = nil
+    _out, err = capture_io { status = EnvVariableCheck::CLI.start(['nope']) }
+    assert_equal 2, status
+    assert_match(/Unknown command/, err)
+
+    status = nil
+    _out, err = capture_io { status = EnvVariableCheck::CLI.start(['audit', 'missing.env']) }
+    assert_equal 1, status
+    assert_match(/not found/, err)
+  end
+
+  def test_audit_text_and_json_include_the_file
+    contents = "DB_PASSWORD=ZzCanary!\nPORT=3000\n"
+    with_env_file(contents, mode: 0600) do |_dir, path|
+      status = nil
+      out, err = capture_io { status = EnvVariableCheck::CLI.start(['audit', '--env', path, '--no-color']) }
+      assert_equal 0, status, err
+      assert_match(/Overall: Weak/, out)
+      assert_match(/DB_PASSWORD/, out)
+      assert_match(/PORT/, out)
+      assert_includes out, contents
+      assert_equal '', err
+
+      json_status = nil
+      json_out, json_err = capture_io do
+        json_status = EnvVariableCheck::CLI.start(['audit', '--format', 'json', '--strict', path])
+      end
+      assert_equal 1, json_status, json_err
+      payload = JSON.parse(json_out)
+      assert_equal 'Weak', payload['overall_rank']
+      assert_equal contents, payload['contents']
+    end
+  end
+
+  def test_run_injects_env_and_arguments
+    with_env_file("FROM_DOTENV=loaded-from-file\nAPI_TOKEN=#{STRONG}\n", mode: 0600) do |dir, path|
+      script = File.join(dir, 'app.rb')
+      File.write(script, "puts [ENV.fetch('FROM_DOTENV'), ARGV.join(',')].join('|')\n")
+      stdout, stderr, status = Open3.capture3(
+        RbConfig.ruby, EnvCheckTest::EXE, 'run', '--env', path, script, 'hello', 'world'
+      )
+      assert status.success?, stderr
+      assert_equal "loaded-from-file|hello,world\n", stdout
+      assert_match(/injected/, stderr)
+      assert_match(/Excellent/, stderr)
+      assert_includes stderr, File.read(path)
+    end
+  end
+
+  def test_run_keeps_existing_variables_unless_override
+    with_env_file("FROM_DOTENV=from-file\nNEW_ONE=from-file\nAPI_TOKEN=#{STRONG}\n", mode: 0600) do |dir, path|
+      script = File.join(dir, 'app.rb')
+      File.write(script, "puts [ENV.fetch('FROM_DOTENV'), ENV.fetch('NEW_ONE')].join('|')\n")
+      stdout, stderr, status = Open3.capture3(
+        { 'FROM_DOTENV' => 'from-shell' },
+        RbConfig.ruby, EnvCheckTest::EXE, 'run', '--quiet', '--env', path, script
+      )
+      assert status.success?, stderr
+      assert_equal "from-shell|from-file\n", stdout
+
+      stdout, stderr, status = Open3.capture3(
+        { 'FROM_DOTENV' => 'from-shell' },
+        RbConfig.ruby, EnvCheckTest::EXE, 'run', '--quiet', '--override', '--env', path, script
+      )
+      assert status.success?, stderr
+      assert_equal "from-file|from-file\n", stdout
+    end
+  end
+
+  def test_strict_run_does_not_execute_a_weak_file
+    secret = 'ZzCanary!'
+    with_env_file("DB_PASSWORD=#{secret}\n", mode: 0600) do |dir, path|
+      marker = File.join(dir, 'ran.txt')
+      script = File.join(dir, 'app.rb')
+      File.write(script, "File.write(#{marker.inspect}, 'ran')\n")
+      stdout, stderr, status = Open3.capture3(
+        RbConfig.ruby, EnvCheckTest::EXE, 'run', '--strict', '--env', path, script
+      )
+      refute status.success?
+      assert_equal '', stdout
+      refute File.exist?(marker)
+      assert_match(/Critical|Weak/, stderr)
+      assert_includes stderr, File.read(path)
+    end
+  end
+
+  def test_export_command
+    with_env_file("FROM_DOTENV=loaded\n", mode: 0600) do |_dir, path|
+      status = nil
+      out, err = capture_io { status = EnvVariableCheck::CLI.start(['export', path]) }
+      assert_equal 0, status, err
+      assert_equal "export FROM_DOTENV='loaded'\n", out
+    end
+  end
+
+  def test_require_load_injects_before_the_script
+    with_env_file("FROM_DOTENV=from-require\n", mode: 0600) do |dir, _path|
+      stdout, stderr, status = Open3.capture3(
+        { 'HOME' => dir },
+        RbConfig.ruby, '-I', EnvCheckTest::LIB, '-r', 'envvariablecheck/load', '-e', 'puts ENV.fetch("FROM_DOTENV")'
+      )
+      assert status.success?, stderr
+      assert_equal "from-require\n", stdout
+    end
+  end
+
+  def test_audit_reads_home_dotenv_by_default
+    contents = "FROM_DOTENV=from-home\nAPI_TOKEN=#{STRONG}\n"
+    original_home = ENV['HOME']
+    with_env_file(contents, mode: 0600) do |dir, path|
+      ENV['HOME'] = dir
+      status = nil
+      out, err = capture_io { status = EnvVariableCheck::CLI.start(['audit', '--no-color']) }
+      assert_equal 0, status, err
+      assert_includes out, "File: #{path}"
+      assert_includes out, contents
+    end
+  ensure
+    ENV['HOME'] = original_home
+  end
+end

data/test/loader_test.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class LoaderTest < Minitest::Test
+  def teardown
+    %w[ENVCHECK_LOAD_A ENVCHECK_LOAD_B ENVCHECK_LOAD_NUL].each { |key| ENV.delete(key) }
+  end
+
+  def test_load_keeps_existing_variables_unless_override
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, '.env')
+      File.write(path, "ENVCHECK_LOAD_A=from-file\nENVCHECK_LOAD_B=from-file\n")
+      ENV['ENVCHECK_LOAD_A'] = 'from-shell'
+      ENV.delete('ENVCHECK_LOAD_B')
+
+      result = EnvVariableCheck.load!(path: path)
+      assert_equal 'from-shell', ENV['ENVCHECK_LOAD_A']
+      assert_equal 'from-file', ENV['ENVCHECK_LOAD_B']
+      assert_includes result.skipped, 'ENVCHECK_LOAD_A'
+      assert_includes result.applied, 'ENVCHECK_LOAD_B'
+
+      ENV['ENVCHECK_LOAD_A'] = 'from-shell'
+      overridden = EnvVariableCheck.load!(path: path, override: true)
+      assert_equal 'from-file', ENV['ENVCHECK_LOAD_A']
+      assert_includes overridden.applied, 'ENVCHECK_LOAD_A'
+    end
+  end
+
+  def test_null_bytes_are_skipped
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, '.env')
+      File.binwrite(path, "ENVCHECK_LOAD_NUL=a\0b\n")
+      result = EnvVariableCheck.load!(path: path)
+      refute ENV.key?('ENVCHECK_LOAD_NUL')
+      assert_match(/ENVCHECK_LOAD_NUL/, result.warnings.join)
+    end
+  end
+
+  def test_missing_file
+    error = assert_raises(EnvVariableCheck::Error) do
+      EnvVariableCheck.load!(path: 'missing-env-file.env')
+    end
+    assert_match(/not found/, error.message)
+  end
+
+  def test_shell_exports_round_trip_special_characters
+    value = "p@ss'w$rd;$(whoami)`id`"
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, '.env')
+      File.write(path, %q(FOO="p@ss'w\$rd;$(whoami)`id`") + "\n")
+      exported = EnvVariableCheck::Loader.shell_exports(EnvVariableCheck::Parser.parse(File.read(path), path: path))
+      stdout, stderr, status = Open3.capture3('sh', '-c', 'eval "$1"; printf "%s" "$FOO"', 'sh', exported)
+      assert status.success?, stderr
+      assert_equal value, stdout
+    end
+  end
+end

data/test/parser_test.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class ParserTest < Minitest::Test
+  def parse(contents)
+    EnvVariableCheck::Parser.parse(contents)
+  end
+
+  def test_comments_blanks_export_and_inline_comments
+    assignments = parse(<<~ENV)
+      # comment
+
+      export PORT=3000
+      NAME=value # trailing
+      HASH=value#keep
+    ENV
+    assert_equal %w[PORT NAME HASH], assignments.map(&:key)
+    assert_equal '3000', assignments[0].value
+    assert_equal 'value', assignments[1].value
+    assert_equal 'value#keep', assignments[2].value
+  end
+
+  def test_quotes_escapes_and_multiline
+    literal = parse("LITERAL='${KEEP} $KEEP'\n")
+    assert_equal '${KEEP} $KEEP', literal[0].value
+
+    escaped = parse('ESCAPED="a\nb\t\"quote\""' + "\n")
+    assert_equal "a\nb\t\"quote\"", escaped[0].value
+
+    multi = parse("MULTI=\"one\ntwo\"\n")
+    assert_equal "one\ntwo", multi[0].value
+  end
+
+  def test_interpolation_prefers_earlier_keys_then_env
+    ENV['ENVCHECK_PARSER_OUTSIDE'] = 'out'
+    assignments = parse(<<~'ENV')
+      INSIDE=in
+      MIXED=${INSIDE}-$ENVCHECK_PARSER_OUTSIDE
+      MISSING=pre-$ENVCHECK_PARSER_MISSING-post
+      QUOTED='${INSIDE}'
+    ENV
+    assert_equal 'in-out', assignments[1].value
+    assert_equal 'pre--post', assignments[2].value
+    assert_equal '${INSIDE}', assignments[3].value
+  ensure
+    ENV.delete('ENVCHECK_PARSER_OUTSIDE')
+  end
+
+  def test_dollar_escapes_are_literal
+    assignments = parse(<<~'ENV')
+      BARE=pass\$word
+      QUOTED="pass\$word"
+    ENV
+    assert_equal 'pass$word', assignments[0].value
+    assert_equal 'pass$word', assignments[1].value
+  end
+
+  def test_crlf_and_bom
+    assignments = parse("\uFEFFKEY=value\r\nNEXT=2\r\n")
+    assert_equal 'value', assignments[0].value
+    assert_equal '2', assignments[1].value
+  end
+
+  def test_last_assignment_wins_when_collapsed
+    assignments = parse("A=1\nA=2\n")
+    collapsed, counts = EnvVariableCheck::Parser.collapse(assignments)
+    assert_equal '2', collapsed[0].value
+    assert_equal 2, counts['A']
+  end
+
+  def test_parse_errors_do_not_include_the_line_contents
+    secret = 'canary-secret-value'
+    error = assert_raises(EnvVariableCheck::Error) { parse("NOT VALID=#{secret}\n") }
+    refute_includes error.message, secret
+    assert_match(/:1/, error.message)
+  end
+
+  def test_unclosed_quote
+    error = assert_raises(EnvVariableCheck::Error) { parse("KEY=\"abc\n") }
+    assert_match(/Unclosed/, error.message)
+    refute_includes error.message, 'abc'
+  end
+end

data/test/scorer_test.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class ScorerTest < Minitest::Test
+  TOKEN = 'aB3dE6gH9kL2mN5pQ8sT1uV4wX7yZ0cR'
+  HEX = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+
+  def score(value, kind: :password, name: 'PASSWORD', reused: [])
+    EnvVariableCheck::Scorer.score(value, kind: kind, name: name, reused_names: reused)
+  end
+
+  def test_rank_boundaries
+    assert_equal 'Critical', EnvVariableCheck::Scorer.rank_for(0)
+    assert_equal 'Critical', EnvVariableCheck::Scorer.rank_for(24)
+    assert_equal 'Weak', EnvVariableCheck::Scorer.rank_for(25)
+    assert_equal 'Weak', EnvVariableCheck::Scorer.rank_for(49)
+    assert_equal 'Fair', EnvVariableCheck::Scorer.rank_for(50)
+    assert_equal 'Fair', EnvVariableCheck::Scorer.rank_for(74)
+    assert_equal 'Strong', EnvVariableCheck::Scorer.rank_for(75)
+    assert_equal 'Strong', EnvVariableCheck::Scorer.rank_for(89)
+    assert_equal 'Excellent', EnvVariableCheck::Scorer.rank_for(90)
+    assert_equal 'Excellent', EnvVariableCheck::Scorer.rank_for(100)
+  end
+
+  def test_empty_and_common_passwords_are_critical
+    assert_equal 0, score('').score
+    assert_equal 'Critical', score('').rank
+
+    common = score('password')
+    assert_equal 'Critical', common.rank
+    assert_operator common.score, :<=, 12
+    assert_match(/commonly used/, common.findings.join)
+
+    assert_equal 'Critical', score('qwerty').rank
+    assert_equal 'Critical', score('changeme').rank
+    assert_equal 'Critical', score('correct horse battery staple').rank
+  end
+
+  def test_predictable_decoration_does_not_outrank_a_common_base
+    decorated = score('Summer2024!')
+    assert_equal 'Critical', decorated.rank
+    assert_operator decorated.score, :<=, 20
+    refute_includes decorated.findings.join, 'Summer2024!'
+  end
+
+  def test_length_caps
+    eight = score('aB3dE6gH')
+    twelve = score('aB3dE6gH9kL2')
+    twenty = score('aB3dE6gH9kL2mN5pQ8sT')
+    assert_equal 8, 'aB3dE6gH'.length
+    assert_equal 12, 'aB3dE6gH9kL2'.length
+    assert_equal 20, 'aB3dE6gH9kL2mN5pQ8sT'.length
+
+    assert_includes %w[Critical Weak], eight.rank
+    assert_equal 'Fair', twelve.rank
+    assert_includes %w[Strong Excellent], twenty.rank
+  end
+
+  def test_random_token_and_hex_are_excellent
+    assert_equal 32, TOKEN.length
+    assert_equal 64, HEX.length
+    token = score(TOKEN, kind: :token, name: 'API_TOKEN')
+    hex = score(HEX, kind: :token, name: 'API_TOKEN')
+    assert_equal 'Excellent', token.rank, token.findings.inspect
+    assert_equal 'Excellent', hex.rank, hex.findings.inspect
+    refute_includes token.findings.join, TOKEN
+  end
+
+  def test_short_tokens_cannot_rank_above_fair
+    short = score('aB3dE6gH9kL2mN5pQ8sT', kind: :token, name: 'API_TOKEN')
+    assert_operator short.score, :<=, 74
+    assert_match(/32 characters/, short.findings.join)
+  end
+
+  def test_reuse_blocks_excellent
+    reused = score(TOKEN, kind: :token, name: 'API_TOKEN', reused: ['OTHER_TOKEN'])
+    assert_operator reused.score, :<=, 89
+    refute_equal 'Excellent', reused.rank
+    assert_match(/OTHER_TOKEN/, reused.findings.join)
+    refute_includes reused.findings.join, TOKEN
+  end
+
+  def test_value_matching_the_name_is_critical
+    result = score('db_password', name: 'DB_PASSWORD')
+    assert_equal 'Critical', result.rank
+    assert_match(/variable name/, result.findings.join)
+  end
+
+  def test_placeholder_and_literal
+    assert_equal 'Critical', score('your_api_key').rank
+    assert_equal 'Critical', score('true', name: 'API_SECRET').rank
+    assert_equal 'Critical', score('xxx').rank
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require 'open3'
+require 'rbconfig'
+require 'tmpdir'
+require 'json'
+require 'envvariablecheck'
+
+module EnvCheckTest
+  ROOT = File.expand_path('..', __dir__)
+  EXE = File.join(ROOT, 'exe', 'envcheck')
+  LIB = File.join(ROOT, 'lib')
+end
+
+def with_env_file(contents, mode: 0600)
+  Dir.mktmpdir('envcheck') do |dir|
+    path = File.join(dir, '.env')
+    File.write(path, contents)
+    File.chmod(mode, path)
+    yield dir, path
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: envvariablecheck
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kellysec
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-10-15 00:00:00.000000000 Z
+dependencies: []
+description: |
+  envvariablecheck loads ~/.env into the environment before a Ruby
+  script runs, and reviews the file's keys and passwords against password best
+  practices. It ranks each secret, checks for reused and placeholder values,
+  and reports loose file permissions and a missing gitignore entry. The
+  review prints the env file in full.
+email:
+- 150852464+kellysec@users.noreply.github.com
+executables:
+- envcheck
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- exe/envcheck
+- lib/envvariablecheck.rb
+- lib/envvariablecheck/auditor.rb
+- lib/envvariablecheck/classifier.rb
+- lib/envvariablecheck/cli.rb
+- lib/envvariablecheck/common_passwords.rb
+- lib/envvariablecheck/entropy.rb
+- lib/envvariablecheck/load.rb
+- lib/envvariablecheck/loader.rb
+- lib/envvariablecheck/parser.rb
+- lib/envvariablecheck/report.rb
+- lib/envvariablecheck/scorer.rb
+- lib/envvariablecheck/version.rb
+- test/auditor_test.rb
+- test/cli_test.rb
+- test/loader_test.rb
+- test/parser_test.rb
+- test/scorer_test.rb
+- test/test_helper.rb
+homepage: 
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Inject ~/.env into a Ruby process and rank secret strength.
+test_files: []