EnvGuard

A small CLI tool to catch leaked secrets, missing env vars, and .env drift.

What it does

Scans your project for common .env problems:

• Secrets accidentally committed to git
• API keys hardcoded in source files
• Variables in .env.example missing from .env (or vice versa)
• Variables defined but never used

Quick Start

npx envguard                        # Run in any project directory
npm install -g envguard              # Or install globally
envguard

No config file. No setup. Just run it.

Example Output

EnvGuard v1.0.0
   Scanned 47 files (3 env, 44 source)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  CRITICAL (2)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  [git-exposure] .env is tracked by git
  └─ .env
     Run: git rm --cached .env && echo ".env" >> .gitignore

  [secret-leak] Stripe Live Key exposed: sk_l...o345
  └─ src/payment.ts:23
     Use Stripe test keys for development. Rotate this live key now.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  HIGH (3)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  [secret-leak] GitHub Personal Access Token exposed
  └─ src/config.ts:15
     Revoke at github.com/settings/tokens.

  [secret-leak] OpenAI API Key exposed: sk-...b1f4
  └─ src/ai.ts:42
     Rotate at platform.openai.com/api-keys.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  MEDIUM (2)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  [missing-vars] SECRET_KEY is in .env.example but missing from .env
  [missing-vars] REDIS_URL is in .env.example but missing from .env

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Summary: 2 critical · 3 high · 2 medium · 0 low

5 Security Checks

| Check | Flag | Severity | What It Finds | |-------|------|----------|---------------| | Secret Leak | --secrets | Critical | Hardcoded API keys, tokens, passwords in source | | Git Exposure | --git-exposed | Critical | .env files tracked by version control | | Missing Vars | --missing | Medium | Keys in .env.example missing from .env | | Env Drift | --drift | Medium | Structural differences between .env and .env.example | | Unused Vars | --unused | Low | Variables defined but never referenced in code |

Secret Detection — 3 Layers

Layer 1: Known Patterns

30+ service signatures with exact regex matching:

| Service | Pattern | |---------|---------| | AWS | AKIA... | | Stripe | sk_live_... | | GitHub | ghp_..., github_pat_... | | OpenAI | sk-... | | Anthropic | sk-ant-... | | GitLab | glpat-... | | Slack | xoxb-... | | Twilio | SK... | | MongoDB | mongodb://user:pass@... | | PostgreSQL | postgres://user:pass@... | | HuggingFace | hf_... | | SendGrid | SG.... |

And 20+ more (Google Cloud, Azure, Discord, Telegram, NPM, JWT, private keys, etc.)

Layer 2: Keyword Heuristics

Catches anything named SECRET, TOKEN, PASSWORD, API_KEY, CREDENTIAL, etc.

Layer 3: Shannon Entropy

Detects random-looking strings (entropy > 4.5) that don't match known formats — catches custom tokens and keys. Includes false-positive filtering: automatically skips URLs, file paths, natural language text, UUIDs, and hashes.

CLI Reference

envguard [directory]                 # Scan directory (default: current)
envguard --secrets                   # Only check for hardcoded secrets
envguard --git-exposed               # Only check git tracking
envguard --missing                   # Only check missing vars
envguard --unused                    # Only check unused vars
envguard --drift                     # Only check .env/.env.example drift
envguard --format json               # JSON output (for CI/CD)
envguard --format markdown           # Markdown report
envguard --severity high             # Only show high severity and above
envguard --no-ignore                 # Don't respect .gitignore
envguard --install-hook              # Install git pre-commit hook
envguard --uninstall-hook            # Remove git pre-commit hook
envguard --strict                    # Treat all issues as blocking

Git Pre-Commit Hook

Block commits that leak secrets:

npx envguard --install-hook          # Install
git commit -m "update"               # EnvGuard runs automatically
SKIP_ENVGUARD=1 git commit -m "..."  # Skip if needed
npx envguard --install-hook --strict # Strict mode

The hook runs envguard --format json before each commit and blocks if critical/high issues are found.

CI/CD Integration

# .github/workflows/envguard.yml
name: EnvGuard
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx envguard --format json --severity high

JSON output works well for CI pipelines — parse it, send alerts, block merges, etc.

Installation

npx envguard                        # One-off (no install needed)
npm install -g envguard              # Global install
npm install --save-dev envguard       # Local dev dependency

Requirements: Node.js >= 18. Only 3 dependencies. Package size < 100KB.

Development

git clone https://github.com/your-username/envguard.git
cd envguard
npm install
npm run build                       # Compile TypeScript
node dist/index.js                  # Run from source

License

MIT