envseal

Security auditor for .env files — detect weak secrets, drift, leaks, duplicates, and misconfigurations.

Every project has .env files. Most have security issues — empty secrets, weak passwords, placeholder values, duplicate keys, files not in .gitignore. envseal catches them all.

Install

npm install -g envseal

Quick Start

# Scan all .env files in current directory
envseal scan .

# Check a specific file
envseal check .env

# List all detection rules
envseal rules

Commands

envseal scan [dir]

Scan all .env files in a directory.

envseal scan .
envseal scan . --fail-on high          # Exit 1 if high/critical findings
envseal scan . --format json           # JSON output
envseal scan . --format sarif          # SARIF for GitHub Advanced Security

envseal check <file>

Check a single .env file.

envseal check .env
envseal check .env --example .env.example   # Include drift detection
envseal check .env --format json

envseal init

Generate pre-commit hooks for automatic security scanning.

envseal init                              # Generate Husky hook (recommended)
envseal init --framework husky            # Generate Husky hook
envseal init --framework pre-commit       # Generate pre-commit config
envseal init --framework native           # Generate native Git hook
envseal init --fail-on high               # Set minimum severity for failures

envseal fix <file>

Auto-fix security issues in .env files.

envseal fix .env                          # Fix all auto-correctable issues
envseal fix .env --dry-run                # Preview changes without applying
envseal fix .env --backup                 # Create backup before fixing
envseal fix .env --rules duplicate-key    # Fix only specific rules

What can be auto-fixed:

• Duplicate keys - Removes duplicates, keeps last occurrence
• Empty secrets - Generates cryptographically secure random values
• Missing variables - Adds variables from .env.example

Safety features:

• Dry-run mode to preview changes
• Automatic backup creation (.env.backup)
• Selective fixing by rule ID
• Detailed diff display

envseal rules

List all 17 detection rules.

Detection Rules

| Rule | Severity | Description | |------|----------|-------------| | empty-secret | 🔴 Critical | Sensitive key with empty value | | weak-value | 🔴 Critical | Known weak/default password | | not-in-gitignore | 🔴 Critical | .env file not in .gitignore | | tracked-by-git | 🔴 Critical | .env file tracked by git | | duplicate-key | 🟡 High | Duplicate key (last value wins silently) | | missing-variable | 🟡 High | Variable in .env.example but not in .env | | no-gitignore | 🟡 High | No .gitignore file found | | bind-all-interfaces | 🟡 High | Service bound to 0.0.0.0 | | wildcard-cors | 🟡 High | Wildcard (*) CORS configuration | | placeholder-value | 🔵 Medium | Placeholder or template value | | short-secret | 🔵 Medium | Secret shorter than 16 characters | | weak-encoding | 🔵 Medium | Weak base64-encoded secret | | localhost-url | 🔵 Medium | Production URL pointing to localhost | | http-url | 🔵 Medium | Insecure HTTP URL | | debug-enabled | 🔵 Medium | Debug flag set to true | | key-specific | 🔵 Medium | Key-specific misconfiguration | | extra-variable | ⚪ Low | Variable in .env but not in .env.example |

Pre-commit Hooks

Generate and install pre-commit hooks to automatically scan .env files before every commit.

Husky (Recommended)

# Generate Husky hook
envseal init --framework husky

# Install Husky (if not already installed)
npm install --save-dev husky
npx husky install

# Make the hook executable
chmod +x .husky/pre-commit

The hook will run envseal check .env --fail-on critical before each commit.

Pre-commit Framework

# Generate pre-commit config
envseal init --framework pre-commit

# Install pre-commit framework
pip install pre-commit  # macOS/Linux
brew install pre-commit  # macOS with Homebrew

# Install the hooks in your repository
pre-commit install

Native Git Hooks

# Generate native Git hook
envseal init --framework native

# Make the hook executable
chmod +x .git/hooks/pre-commit

⚠️ Warning: Native Git hooks are not tracked in version control. Consider using Husky or the pre-commit framework for team collaboration.

GitHub Actions

A ready-to-use GitHub Actions workflow is included for CI/CD integration.

# .github/workflows/envseal.yml
name: envseal security scan

on:
  push:
    branches: [main, master, develop]
  pull_request:
    branches: [main, master, develop]

jobs:
  envseal:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npx envseal scan . --fail-on high --format sarif > envseal-results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: envseal-results.sarif

The workflow:

• Runs on every push and pull request
• Tests across Node.js 18, 20, and 22
• Uploads SARIF results to GitHub Advanced Security
• Fails the build on high/critical findings

Ignoring Findings

Create a .envsealignore file to suppress false positives without modifying your code.

Ignore File Format

{
  "globalIgnores": ["localhost-url", "debug-enabled"],
  "paths": {
    ".env.local": {
      "ignore": ["debug-enabled"]
    },
    ".env": {
      "lineSpecific": {
        "5": ["short-secret"],
        "10": ["weak-value"]
      }
    }
  }
}

Ignore Types

• Global ignores: Suppress specific rule IDs across all files
• File-specific ignores: Suppress specific rules for a particular file
• Line-specific ignores: Suppress specific rules for particular lines

CLI Options

# Use custom ignore file location
envseal check .env --ignore-file /path/to/.envsealignore

# Disable ignore processing
envseal check .env --no-ignore

Search Order

envseal searches for .envsealignore in this order:

1. Same directory as the .env file
2. Current working directory
3. Custom path specified via --ignore-file

Configuration File

Create a .envsealrc.json file to customize envseal behavior for your project.

Configuration Options

{
  "rules": {
    "enable": ["empty-secret", "weak-value"],
    "disable": ["localhost-url"],
    "severity": {
      "debug-enabled": "low"
    }
  },
  "thresholds": {
    "secretLength": 32,
    "base64MinLength": 32
  },
  "failOn": "high",
  "strict": false,
  "patterns": {
    "weakValues": ["password", "admin", "test"],
    "sensitiveKeys": [".*SECRET.*", ".*API.*", ".*TOKEN.*"]
  }
}

Configuration Features

• Rule enable/disable - Turn specific rules on or off
• Severity customization - Change severity levels per rule
• Threshold overrides - Customize secret length requirements
• Pattern customization - Add project-specific weak values or sensitive keys
• Default settings - Set fail-on severity and strict mode

CLI Options

# Use custom config file location
envseal scan . --config /path/to/.envsealrc.json

# Print effective configuration
envseal scan . --print-config

Search Order

envseal searches for .envsealrc.json in this order:

1. Same directory as the .env file
2. Current working directory
3. Custom path specified via --config

# GitHub Actions
- name: Audit .env files
  run: npx envseal scan . --fail-on high --format sarif > envseal-results.sarif

# Pre-commit hook
npx envseal check .env --fail-on critical

Output Example

🔍 .env
  🔴 [CRITICAL] Weak/default value detected for 'JWT_SECRET': pa****rd
     → Replace 'password' with a strong, unique value
  🟡 [HIGH    ] Duplicate key 'DATABASE_URL' — first defined at line 2, redefined at line 20
     → Remove one of the duplicate 'DATABASE_URL' entries
  🔵 [MEDIUM  ] Debug/verbose flag set to true — may leak sensitive info
     → Set to false in production

  Score: 55/100 (Grade: F)
  Issues: 17 findings

Comparison with Alternatives

| Feature | envseal | dotenv-linter | gitleaks | trufflehog | |---------|---------|---------------|----------|------------| | .env-specific | ✅ Yes | ✅ Yes | ❌ No | ❌ No | | Security scoring | ✅ 0-100 | ❌ No | ❌ No | ❌ No | | Drift detection | ✅ Yes | ❌ No | ❌ No | ❌ No | | SARIF output | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes | | Pre-commit hooks | ✅ Yes | ✅ Yes | ❌ No | ❌ No | | Auto-fix | ✅ Yes | ❌ No | ❌ No | ❌ No | | Config file | ✅ Yes | ❌ No | ❌ No | ❌ No | | Ignore file | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | | Language | TypeScript | Rust | Go | Go | | GitHub stars | New | 2.7K | 17K | 25.7K |

Why envseal?

• Unique scoring system - Quantifies .env security risk with 0-100 grade
• Drift detection - Only tool comparing .env vs .env.example
• Auto-fix capability - Corrects common issues automatically
• Developer experience - Most user-friendly CLI in this space
• .env-specific - Purpose-built for .env files, not generic secret scanning

Programmatic API

import { scanEnv, parseEnvFile } from "envseal";

const parsed = parseEnvFile(".env");
const result = scanEnv(parsed);
console.log(`Score: ${result.score}/100 (Grade: ${result.grade})`);

Tech Stack

• TypeScript, Commander.js, Chalk, Zod
• 25 unit tests with Vitest
• Zero runtime dependencies beyond CLI basics

License

MIT