EnvGuard

Stop leaking secrets. Validate your .env files, scan for exposed credentials, and keep your environment configurations secure.

The Problem

How many times have you:

• Committed .env files to git by accident?
• Deployed with missing environment variables?
• Had no idea what variables are actually required?
• Found API keys in your git history from months ago?

EnvGuard solves all of this.

Features

• Schema Validation - Define required variables, types, and formats
• Secret Detection - Scan for API keys, tokens, and credentials
• Auto-generate Examples - Create .env.example from your .env
• Git History Scanning - Find accidentally committed secrets
• Zero Config - Works out of the box, customize if needed

Installation

npm install -g envguard

Or run locally:

git clone https://github.com/ranjan98/envguard.git
cd envguard
npm install
npm run build
npm link

Quick Start

# Check your .env file for secrets
envguard check-secrets

# Generate .env.example
envguard generate-example

# Validate against a schema
envguard validate --schema env.schema.js

# Scan git history for leaked secrets
envguard scan-history

Usage

1. Check for Secrets

Scan your .env file for potentially exposed secrets:

envguard check-secrets

# Check a different file
envguard check-secrets .env.production

Output:

🔍 EnvGuard - Secret Scanner

⚠️  Found 2 potential secret(s):

  • AWS_SECRET_KEY: Looks like an AWS secret key
  • DATABASE_PASSWORD: Contains a hardcoded password

  Tip: Add these to .gitignore and use a secrets manager

2. Generate .env.example

Automatically create a template file:

envguard generate-example

# Custom output
envguard generate-example --output .env.template

Before (.env):

DATABASE_URL=postgresql://user:pass123@localhost:5432/mydb
API_KEY=sk_live_abc123xyz789
PORT=3000
NODE_ENV=development

After (.env.example):

# Generated by EnvGuard

DATABASE_URL=your-database-url-here
API_KEY=your-api-key-here
PORT=3000
NODE_ENV=development

3. Validate Environment Variables

Define a schema and validate your .env file:

env.schema.js:

const Joi = require('joi');

module.exports = {
  DATABASE_URL: Joi.string().uri().required(),
  API_KEY: Joi.string().pattern(/^sk_/).required(),
  PORT: Joi.number().port().default(3000),
  NODE_ENV: Joi.string().valid('development', 'production', 'test').required(),
  REDIS_URL: Joi.string().uri(),
  MAX_UPLOAD_SIZE: Joi.number().positive(),
};

Run validation:

envguard validate --schema env.schema.js

Output:

🛡️  EnvGuard - Validation

✗ Validation failed!

  • DATABASE_URL is required
  • API_KEY must start with "sk_"
  • NODE_ENV must be one of: development, production, test

4. Scan Git History

Find secrets that were accidentally committed:

# Scan last 100 commits (default)
envguard scan-history

# Scan more commits
envguard scan-history --depth 500

Output:

🔎 EnvGuard - Git History Scanner

Scanning last 100 commits...

⚠️  Found 1 potential secret(s) in history:

  Commit: a1b2c3d
  File: .env
  AWS_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

  ⚠️  These secrets may be compromised. Rotate them immediately!

Validation Schema Examples

Basic Schema

module.exports = {
  PORT: Joi.number().port(),
  NODE_ENV: Joi.string().valid('dev', 'prod'),
};

Complex Schema with Conditionals

const Joi = require('joi');

module.exports = {
  // Required in production
  DATABASE_URL: Joi.when('NODE_ENV', {
    is: 'production',
    then: Joi.string().uri().required(),
    otherwise: Joi.string().uri(),
  }),

  // Must be a valid email
  ADMIN_EMAIL: Joi.string().email().required(),

  // Custom pattern
  API_KEY: Joi.string().pattern(/^[A-Za-z0-9]{32}$/),

  // Number with range
  MAX_CONNECTIONS: Joi.number().min(1).max(100).default(10),

  // Multiple allowed values
  LOG_LEVEL: Joi.string().valid('error', 'warn', 'info', 'debug'),
};

Secret Detection

EnvGuard automatically detects:

• AWS Access Keys & Secret Keys
• GitHub Personal Access Tokens
• Slack API Tokens
• Stripe API Keys
• JWT Secrets
• Database Passwords
• Private Keys (RSA, SSH)
• OAuth Client Secrets
• And more...

Best Practices

1. Always use .env.example

   envguard generate-example
   git add .env.example

2. Validate in CI/CD

   # .github/workflows/ci.yml
   - name: Validate Environment
     run: envguard validate

3. Scan before deploying

   envguard check-secrets && envguard validate && npm run deploy

4. Rotate exposed secrets

   envguard scan-history --depth 1000
   # If secrets found, rotate them in your cloud provider

5. Use a secrets manager in production

   • AWS Secrets Manager
   • HashiCorp Vault
   • Google Secret Manager
   • Azure Key Vault

Pre-commit Hook

Add to .git/hooks/pre-commit:

#!/bin/sh
envguard check-secrets || exit 1

Make it executable:

chmod +x .git/hooks/pre-commit

Configuration File

Create envguard.config.js:

module.exports = {
  schema: './env.schema.js',
  ignore: ['TEMP_*', 'DEBUG_*'],
  secrets: {
    enabled: true,
    customPatterns: [
      /my_custom_secret_pattern_/i
    ]
  }
};

Supported Patterns

EnvGuard detects these secret patterns:

Type	Pattern	Example
AWS Access Key	AKIA[0-9A-Z]{16}	AKIAIOSFODNN7EXAMPLE
GitHub Token	ghp_[a-zA-Z0-9]{36}	ghp_abc123...
Slack Token	xox[baprs]-...	xoxb-123-456...
Stripe Key	sk_live_[0-9a-zA-Z]{24}	sk_live_abc123...
Private Key	-----BEGIN.*PRIVATE KEY-----	RSA/SSH keys

Roadmap

• Support for encrypted .env files
• Cloud secrets manager integration
• Slack/email notifications for exposed secrets
• VSCode extension
• Auto-fix common issues
• Environment diff tool

Contributing

Found a bug? Want to add more secret patterns?

git clone https://github.com/ranjan98/envguard.git
cd envguard
npm install
npm run dev validate

License

MIT License - see LICENSE for details

---

Protect your secrets. Use EnvGuard.

Give it a star if it saved you from a security incident! ⭐