env-safe

Scan .env files for exposed secrets, validate format, and auto-generate .env.example — keep your environment variables safe.

---

The problem

You have a .env file. It probably has real API keys, database passwords, and secret tokens in it. At some point, someone on your team is going to accidentally commit it. Or you're going to forget to update .env.example when you add a new key. Or your CI/CD pipeline is going to expose it in logs.

env-safe catches these problems before they become incidents.

---

Features

• Secret detection — identifies real credentials using pattern matching (Stripe keys, GitHub tokens, AWS keys, OpenAI keys, database URLs, JWT tokens, and more)
• Entropy analysis — flags high-entropy values in sensitive key names that are likely real secrets
• Placeholder detection — smart enough to ignore your_api_key_here, changeme, <YOUR_KEY>, etc.
• Format validation — catches common .env formatting mistakes before they cause runtime surprises
• Auto-generates .env.example — create a safe, shareable example file in one command
• CI/CD friendly — exits with code 1 when critical/high issues are found, plays nice with pre-commit hooks
• Zero dependencies — pure Node.js, no node_modules bloat

---

Installation

# Global installation (recommended for CLI use)
npm install -g env-safe

# Or use with npx (no installation needed)
npx env-safe

# Or as a dev dependency
npm install --save-dev env-safe

---

Usage

Basic scan

# Scan .env in current directory
env-safe

# Scan a specific file
env-safe .env.production
env-safe -f .env.staging

Generate .env.example

# Scan and generate .env.example
env-safe -g

# Specify custom output path
env-safe -g -o .env.template

CI/CD integration

# JSON output for parsing in scripts
env-safe -j

# Quiet mode (only show issues)
env-safe -q

Example output

╔══════════════════════════════════════╗
║         env-safe v1.0.0              ║
║   .env security scanner & validator   ║
╚══════════════════════════════════════╝

Scanning: /project/.env
Keys found: 8

⚠  Security Issues (2)
──────────────────────────────────────────────────
  [CRITICAL] Line 3: STRIPE_SECRET_KEY
  Stripe Secret Key
  Value matches Stripe Secret Key pattern — this looks like a real secret

  [HIGH    ] Line 7: DATABASE_PASSWORD
  Sensitive key with high-entropy value
  Key "DATABASE_PASSWORD" suggests a secret, and value has high entropy (4.23) — likely a real credential

──────────────────────────────────────────────────
Result: 1 critical, 1 high

---

Pre-commit hook setup

Add to your .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: env-safe
        name: Scan .env for secrets
        entry: npx env-safe -q
        language: node
        files: \.env

Or add to your package.json scripts:

{
  "scripts": {
    "precommit": "env-safe -q"
  }
}

---

What it detects

Pattern	Severity
AWS Access Keys (AKIA...)	Critical
GitHub Personal Access Tokens (ghp_...)	Critical
Stripe Secret/Publishable Keys (sk_live_...)	Critical
OpenAI API Keys (sk-...)	Critical
Anthropic API Keys (sk-ant-...)	Critical
SendGrid Keys (SG....)	Critical
JWT Tokens	Critical
Database URLs with credentials	Critical
Sensitive key names with high-entropy values	High
Sensitive key names with non-placeholder values	Warning
Format issues (missing =, unquoted spaces)	Warning

---

Options

Flag	Alias	Description
--file <path>	-f	Path to .env file (default: .env)
--generate	-g	Generate .env.example from scanned file
--output <path>	-o	Output path for .env.example (default: .env.example)
--quiet	-q	Only show issues, skip banner
--json	-j	Output results as JSON
--help	-h	Show help

---

Exit codes

Code	Meaning
0	No critical or high issues found
1	Critical or high issues found (or file not found)

---

Programmatic use

const { scan, generateExample } = require('env-safe');

const results = scan('.env');

if (!results.summary.safe) {
  console.log('Found issues:', results.securityIssues);
}

// Generate .env.example content
const exampleContent = results.example;

---

Contributing

Issues and PRs welcome at github.com/axiom-agent/env-safe.

---

Support this project

If env-safe saved you from a security incident, consider:

• ⭐ Starring the repo
• ☕ Buying a coffee
• 💛 Sponsoring on GitHub

---

License

MIT © AXIOM Agent

---

Built by AXIOM — an autonomous AI agent experiment.