env-auditor

Audit environment variable consistency across your codebase. Finds vars used in code but missing from .env.example, stale vars nobody references anymore, and required vars with no default value; in any language.

$ env-auditor .

env-auditor — environment variable audit
──────────────────────────────────────────

✗  3 undocumented variables (in code, missing from .env.example)
   DATABASE_URL          src/db/connection.py:14
   STRIPE_WEBHOOK_SECRET src/payments/webhook.py:8, src/payments/webhook.py:31
   REDIS_URL             src/cache.py:22

⚠  2 stale variables (in .env.example, not found in code)
   OLD_PAYMENT_KEY
   DEPRECATED_FEATURE_FLAG

○  2 variables with no default value (empty in .env.example)
   SECRET_KEY
   JWT_SECRET

⚡  1 dynamic reference (runtime key construction — cannot audit statically)
   src/config/loader.py:45  →  process.env[configKey]

──────────────────────────────────────────
Result: FAIL  (exit code 1)

Why

Your .env.example is a contract. It tells new contributors what the app needs to run. Over time that contract drifts: someone adds process.env.NEW_KEY to the source and forgets to document it, or removes a feature but leaves the stale key rotting in .env.example. env-auditor catches both automatically, in CI, before it becomes someone else's debugging session.

Installation

pip install env-auditor

Requires Python 3.10+. Zero runtime dependencies — pure stdlib.

Usage

# Audit current directory against .env.example (default)
env-auditor

# Audit a specific project
env-auditor /path/to/project

# Use a different env file
env-auditor --env .env.production

# Multiple env files (keys merged — union)
env-auditor --env .env.example --env .env.staging

# Strict mode: fail on stale vars too
env-auditor --strict

# JSON output for tooling / dashboards
env-auditor --format json | jq .undocumented

# Suppress specific sections
env-auditor --ignore-stale --ignore-missing

# Exclude extra directories
env-auditor --exclude vendor --exclude third_party

Config file

Commit a .env-auditorrc at your project root to persist settings for your whole team:

# .env-auditorrc
env_files = [".env.example", ".env.staging"]
exclude_dirs = ["vendor", "third_party"]
ignore_stale = false
strict = true
ignore_keys = ["CI", "HOME", "USER"]
required_keys = ["DATABASE_URL", "SECRET_KEY"]

Or add it to pyproject.toml under [tool.env-auditor]:

[tool.env-auditor]
env_files = [".env.example"]
strict = true
ignore_keys = ["CI"]

CLI flags always override config file values.

ignore_keys excludes specific variable names from every category (undocumented, stale, missing values, required). required_keys is the inverse: names that must appear in at least one env file; always reported as a failure if absent, whether or not they're referenced in code (useful for infra-only vars like DATABASE_URL that no source file ever touches directly).

Supported languages

Dynamic references like process.env[someVariable] are flagged separately, they can't be statically audited.

CLI reference

Exit codes

CI integration

Block deploys when env vars drift:

# .github/workflows/deploy.yml
jobs:
  env-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install env-auditor
      - run: env-auditor --strict

Save the report as a CI artifact:

- run: env-auditor --format json > env-auditor-report.json || true
- uses: actions/upload-artifact@v4
  with:
    name: env-auditor-report
    path: env-auditor-report.json

For monorepos, run per-service:

- run: env-auditor services/api --env services/api/.env.example
- run: env-auditor services/worker --env services/worker/.env.example

Security

• Symlinks are never followed
• Files over 1 MB are skipped (with a warning)
• Lines over 2000 characters are skipped (ReDoS protection)
• --exclude paths are validated to be within the scan root; path traversal rejected
• Actual .env values are never stored, logged, or printed; only key names
• No network calls, no telemetry, entirely local

Development

git clone https://github.com/SemTiOne/env-auditor
cd env-auditor
pip install -e .
pip install pytest pytest-cov
pytest --cov=env_auditor --cov-report=term-missing

License

MIT