baraa-rasheed/dotenv-guard

No problems traced to this repository code in these checks.

OSV scanned supported lockfiles; unpinned dependencies and unsupported formats are outside this check.

A short run cannot establish that code is safe.

Connections show IP addresses; proxies can hide the final hostname.

Tracing covers dispatched commands and their children, not the whole OS; guest root can interfere with tracing.

Full safety evidence →

• Running the tool reports a variable that is in .env.example but missing from .env: Real input produced the expected result: - API_KEY

  Source: Running the tool will report that `API_KEY` is missing.

  Input: .env missing API_KEY, .env.example lists API_KEY

  Expected: API_KEY reported as missing with exit code 1

  Command: <guest-path>

  Observed: - API_KEY Tip: Add this to your pre-commit hook or CI to catch issues early.

• Custom paths: checks the given env file against the given example file: Real input produced the expected result: Required variables are present

  Source: dotenv-guard .env.production .env.example

  Input: .env.production with all variables set, one secret-like key

  Expected: Required variables are present, exit code 0

  Command: <guest-path> .env.production .env.example

  Observed: Required variables are present (but review the secrets above).

Examples

• Default: checks .env against .env.example: command completed successfully

  Source: README.md Usage

  Input: no arguments, complete .env in cwd

  Expected: all required variables present, exit 0 (with secret warning)

  Command: <guest-path>

  Observed: 🔒 Potential secrets detected (review before committing): - API_KEY ✅ Required variables are present (but review the secrets above).

• Custom paths: dotenv-guard .env.production .env.example: command completed successfully

  Source: README.md Usage

  Input: .env.production .env.example

  Expected: all required variables present, exit 0

  Command: <guest-path> .env.production .env.example

  Observed: 🔒 Potential secrets detected (review before committing): - API_KEY ✅ Required variables are present (but review the secrets above).

Local or hosted: local

Validate a .env file against .env.example with the dotenv-guard CLI (missing, empty, and secret-warning checks, documented exit codes)

cd <guest-path> && pwd && ls -la && id -u && python3 --version && cat README.md | head -c 6000
cd <guest-path> && cat package.json index.js .gitignore && ls -la .coldpass && which node npm npx; node --version; npm --version; cat /etc/os-release | head -2
sudo -n apt-get -o DPkg::Lock::Timeout=300 update -qq && sudo -n apt-get -o DPkg::Lock::Timeout=300 install -y -qq nodejs npm >/tmp/apt.log 2>&1; echo rc=$?; tail -5 /tmp/apt.log; node --version; npm --version
export NODE_USE_ENV_PROXY=1; mkdir -p $HOME/.npm-global && npm config set prefix $HOME/.npm-global && npm install -g dotenv-guard 2>&1 | tail -5; echo rc=$?; ls $HOME/.npm-global/bin; $HOME/.npm-global/bin/dotenv-guard --help 2>&1 | head -5; cat $HOME/.npm-global/lib/node_modules/dotenv-guard/package.json | grep '"version"'
cd /tmp && npm view dotenv-guard name version 2>&1 | head -5; echo "---"; npm config get registry; grep -i -m5 "http fetch\|404" <guest-path> | head -8
export NODE_USE_ENV_PROXY=1; cd /tmp && npm install -g <guest-path> 2>&1 | tail -3; echo rc=$?; ls -la $(npm config get prefix)/bin/ ; which dotenv-guard
grep -i "error" <guest-path> | head -15; npm config get prefix
export NODE_USE_ENV_PROXY=1; mkdir -p <guest-path> && cd /tmp && npm install -g --prefix <guest-path> <guest-path> 2>&1 | tail -3; ls -la <guest-path> 2>&1; <guest-path> --help 2>&1 | head -3; echo "rc=$?"
mkdir -p <guest-path> && cd <guest-path> && printf 'DATABASE_URL=\nAPI_KEY=\n<secret>\n' > .env.example && printf 'DATABASE_URL=postgres://...\nPORT=3000\n' > .env && <guest-path>; echo "rc=$?"
cd <guest-path> && printf 'DATABASE_URL=postgres://db\nAPI_KEY=<secret>\nPORT=3000\n' > .env.production && <guest-path> .env.production .env.example; echo "rc=$?"; printf 'PORT=\n' > .env.empty && <guest-path> .env.empty .env.example; echo "rc=$?"
ls -la <guest-path> 2>&1; ls -la /inputs/ 2>&1; ls -la <guest-path>; grep -n "^##\|^- \`\|dotenv-guard " <guest-path>
mkdir -p <guest-path> && cat > <guest-path> <<'EOF'
[
  {"kind":"claim","claim":"Running the tool reports a variable that is in .env.example but missing from .env","source":"Running the tool will report that `API_KEY` is missing.","input":".env missing API_KEY, .env.example lists API_KEY","expected":"API_KEY reported as missing with exit code 1","probe_kind":"cli","argv":["<guest-path>"],"expected_returncode":1,"expected_text":"  - API_KEY","cwd":"<guest-path>"},
  {"kind":"claim","claim":"Custom paths: checks the given env file against the given example file","source":"dotenv-guard .env.production .env.example","input":".env.production with all variables set, one secret-like key","expected":"Required variables are present, exit code 0","probe_kind":"cli","argv":["<guest-path>",".env.production",".env.example"],"expected_text":"Required variables are present","cwd":"<guest-path>"}
]
EOF
python3 -I -c "import json;json.load(open('<guest-path>'));print('ok')"
cd <guest-path> && cat > probe.json <<'EOF'
{"kind":"cli","argv":["<guest-path>"],"cwd":"<guest-path>","expected_returncode":1,"expected_text":"  - API_KEY"}
EOF
cat > examples.json <<'EOF'
[
  {"kind":"example","claim":"Default: checks .env against .env.example","source":"README.md Usage","input":"no arguments, .env in cwd","expected":"reports API_KEY missing, exit 1","argv":["<guest-path>"],"cwd":"<guest-path>","expected_returncode":1,"expected_text":"  - API_KEY"},
  {"kind":"example","claim":"Custom paths: dotenv-guard .env.production .env.example","source":"README.md Usage","input":".env.production .env.example","expected":"all required variables present, exit 0","argv":["<guest-path>",".env.production",".env.example"],"cwd":"<guest-path>","expected_text":"Required variables are present"}
]
EOF
cat > cycles.json <<'EOF'
{"detected":false,"reason":"Entry points inspected: index.js (single synchronous run() that reads argv, prints results and calls process.exit) and package.json (bin + start script only). No cron, scheduler, loop, webhook, --once or --now option exists; the tool runs once per invocation, so there is no product cycle to trigger.","checks":[]}
EOF
for f in probe.json examples.json cycles.json claims.json; do python3 -I -m json.tool $f >/dev/null && echo "$f ok"; done
cd <guest-path> && cat > report.json <<'EOF'
{"outcome":"working","fault_owner":"repo","operation":"Validate a .env file against .env.example with the dotenv-guard CLI (missing, empty, and secret-warning checks, documented exit codes)","operation_scope":"Linux Ubuntu 24.04, Node v18.19.1 (meets engines node>=18), installed from the pinned local source into a user-local prefix. Tested only with local .env files; no CI or pre-commit hook run.","steps":["apt-get install nodejs npm (Node v18.19.1, npm 9.2.0)","npm install -g dotenv-guard (README Install) - FAILED: 404, package not on registry.npmjs.org","npm install -g --prefix <guest-path> <guest-path> (substitute, pinned source)","dotenv-guard (default: .env vs .env.example) - exit 1, reports API_KEY missing","dotenv-guard .env.production .env.example - exit 0, reports secret warning and 'Required variables are present'","dotenv-guard .env.production .env.example with empty PORT and missing vars - exit 1"],"deviations":["README 'npm install -g dotenv-guard' fails: npm registry returns 404 for dotenv-guard (no published package). Substituted installing the pinned source folder with npm install -g --prefix.","First global install attempt without --prefix failed with EACCES on /usr/local/lib/node_modules; retried with user-local prefix.","/inputs/coldpass-preflight.py does not exist in this guest; The tool itself works when installed from the source in this project.","suggested_fix":"Publish the package to npm under the name dotenv-guard, or change the README install instructions to say to install from the git repository or local source."}
EOF
python3 -I -m json.tool report.json >/dev/null && echo ok; cd <guest-path> && <env-var>=<guest-path> python3 -I <guest-path> --validate --replay 2>&1 | tail -60
cd <guest-path> && python3 -I - <<'EOF'
import json
p='<guest-path>'
d=json.load(open(p))
d[0]['expected_text']='API_KEY'
json.dump(d,open(p,'w'),indent=1)
print(d[0]['expected_returncode'], d[0]['expected_text'])
EOF
cd <guest-path> && <env-var>=<guest-path> python3 -I <guest-path> --validate --replay 2>&1 | python3 -I -c "import sys,json; t=sys.stdin.read(); i=t.find('{'); d=json.loads(t[i:]); print('valid=',d['valid']); print('problems=',d['problems']); print('replay=',d['replay']['status'])"
mkdir -p <guest-path> && cd <guest-path> && printf 'DATABASE_URL=postgres://db\nAPI_KEY=<secret>\nPORT=3000\n' > .env && printf 'DATABASE_URL=\nAPI_KEY=\n<secret>\n' > .env.example && <guest-path>; echo "rc=$?"; cd <guest-path> && python3 -I - <<'EOF'
import json
p='<guest-path>'
d=json.load(open(p))
d[0]={"kind":"example","claim":"Default: checks .env against .env.example","source":"README.md Usage","input":"no arguments, complete .env in cwd","expected":"all required variables present, exit 0","argv":["<guest-path>"],"cwd":"<guest-path>","expected_text":"All required environment variables are present"}
json.dump(d,open(p,'w'),indent=1)
print('written')
EOF
cd <guest-path> && python3 -I - <<'EOF'
import json
p='<guest-path>'
d=json.load(open(p))
d[0]['expected_text']='Required variables are present'
d[0]['expected']='all required variables present, exit 0 (with secret warning)'
json.dump(d,open(p,'w'),indent=1)
EOF
cd <guest-path> && <env-var>=<guest-path> python3 -I <guest-path> --validate --replay 2>&1 | python3 -I -c "import sys,json; t=sys.stdin.read(); i=t.find('{'); d=json.loads(t[i:]); print('valid=',d['valid']); print('problems=',d['problems']); print('replay=',d['replay']['status'])"
cd <guest-path> && ls -la && ls -la .coldpass && git status 2>/dev/null | head -2; pgrep -fa dotenv-guard || echo "no background processes"
cd <guest-path> && cat .npmrc; rm -f .npmrc && <env-var>=<guest-path> python3 -I <guest-path> --validate --replay 2>&1 | python3 -I -c "import sys,json; t=sys.stdin.read(); i=t.find('{'); d=json.loads(t[i:]); print('valid=',d['valid']); print('problems=',d['problems']); print('replay=',d['replay']['status'])"; ls -la <guest-path> | grep npmrc || echo "no .npmrc"