envguard

README

🛡️ EnvGuard

Smart .env file manager — scan, validate, diff, and sync environment variables

---

Ever deployed to production only to crash because DATABASE_URL was missing?

EnvGuard scans your code, validates your .env files, detects leaked secrets, and keeps environments in sync — all from one CLI.

✨ Features

• 🔍 Code Scanner — Finds every env var your code actually uses (JS/TS, Python, Go, Rust, Docker)
• ✅ Validator — Validates .env against a schema with type checking (int, bool, url, port, email, enum)
• 🔄 Cross-Validation — Detects vars used in code but missing from .env, and vars in .env but unused
• 📊 Diff — Compare .env files across environments with color-coded output
• 🔐 Secret Detection — Finds AWS keys, private keys, JWTs, and tokens in your codebase
• 🔒 Encrypted Sync — Share .env files via git safely with AES-256-GCM encryption
• 🪝 Pre-commit Hook — Validate before every commit automatically
• 📋 Schema Generator — Auto-generate .env.schema from existing .env with type inference
• 🚀 CI-Ready — Clean exit codes (0=ok, 1=warnings, 2=errors) for pipeline integration

📦 Installation

Go Install

go install github.com/AbdullahTarakji/envguard/cmd/envguard@latest

From Source

git clone https://github.com/AbdullahTarakji/envguard.git
cd envguard
make build
sudo mv envguard /usr/local/bin/

Binary Releases

Download pre-built binaries from Releases.

🎬 Demo

🚀 Quick Start

# Scan your code for env var usage
envguard scan

# Validate your .env file
envguard validate

# Run all checks (validate + security scan)
envguard check

# Compare dev vs prod env files
envguard diff .env .env.production

📖 Usage

envguard scan — Find Environment Variables in Code

Scans your source code to discover which environment variables are actually used:

$ envguard scan
Found 8 unique environment variables in 12 references:

  DATABASE_URL     src/db.ts:5 (js)
  PORT             src/index.ts:3 (js)
  API_KEY          src/api.ts:10 (js)
  DEBUG            src/config.py:8 (python)
  REDIS_URL        src/cache.go:15 (go)
  ...

Supported languages:

Language	Patterns Detected
JavaScript/TypeScript	process.env.VAR, process.env['VAR'], import.meta.env.VITE_*
Python	os.environ['VAR'], os.getenv('VAR'), os.environ.get('VAR')
Go	os.Getenv("VAR"), os.LookupEnv("VAR")
Rust	std::env::var("VAR"), env::var("VAR"), env!("VAR")
Docker	ENV VAR=val, ARG VAR, ${VAR} in compose

# Filter by language
envguard scan --lang js

# JSON output
envguard scan --json

# Scan specific directory
envguard scan ./src

envguard validate — Validate Your .env File

Against Code (default)

Checks that every env var your code uses is defined in .env, and warns about unused vars:

$ envguard validate
  ✗ MISSING_VAR: variable used in code but missing from .env
  ⚠ OLD_CONFIG: variable defined in .env but not used in code
  ✓ 12 variables validated successfully

Against a Schema

Create a .env.schema to enforce types and requirements:

# type: string, required
DATABASE_URL=
# type: port, required
PORT=
# type: bool, optional, default: false
DEBUG=
# type: enum(development,staging,production), required
NODE_ENV=
# type: url, required
API_ENDPOINT=
# type: email, optional
ADMIN_EMAIL=

$ envguard validate --schema .env.schema
  ✗ PORT: expected type "port", got "abc" (not a valid port number)
  ✗ NODE_ENV: expected one of [development, staging, production], got "test"
  ✓ 8/10 variables passed validation

Supported types: string, int, bool, url, email, port, enum(val1,val2,...)

# Strict mode (warnings become errors)
envguard validate --strict

# JSON output for CI
envguard validate --json

# Explicit paths
envguard validate --env .env.staging --schema .env.schema

envguard diff — Compare Environment Files

$ envguard diff .env .env.production
  ~ DATABASE_URL: localhost:5432/dev → prod-db:5432/app (line 1 → 1)
  ~ PORT: 3000 → 8080 (line 2 → 2)
  - DEBUG=true (line 3)
  + SENTRY_DSN=https://... (line 8)
  ~ NODE_ENV: development → production (line 5 → 4)

# Mask sensitive values (for sharing/logging)
envguard diff .env .env.prod --mask
  ~ DATABASE_URL: ***** → ***** (line 1 → 1)
  ~ API_KEY: ***** → ***** (line 4 → 3)

# JSON output
envguard diff .env .env.prod --json

envguard init — Generate Schema from .env

Auto-generates a .env.schema with inferred types:

$ envguard init
Generated .env.schema with 10 entries

$ cat .env.schema
# type: string, required
DATABASE_URL=
# type: port, required
PORT=
# type: bool, required
DEBUG=
# type: url, required
API_ENDPOINT=

Type inference:

• Numbers → int (or port if 1-65535)
• true/false/yes/no → bool
• http:///https:// → url
• Contains @ and . → email
• Everything else → string

envguard check — Run All Checks

Combined validation + security scan, perfect for CI:

$ envguard check
  ⚠ .env is not in .gitignore
  ✗ MISSING_VAR: used in code but not in .env
  ⚠ Found potential AWS key pattern in src/config.js:15
  ✓ Encryption check passed

$ echo $?
2  # exit code 2 = errors found

Exit codes: 0 = clean, 1 = warnings only, 2 = errors

envguard encrypt / decrypt — Secure .env Sharing

Share .env files through git safely with AES-256-GCM encryption:

# Encrypt .env → .env.enc (from project directory)
envguard encrypt --password "team-secret"

# Or specify the file path directly
envguard encrypt .env.staging --password "team-secret"

# Decrypt .env.enc → .env
envguard decrypt --password "team-secret"

# Decrypt a specific file
envguard decrypt .env.staging.enc --password "team-secret"

# Password from environment variable
export ENVGUARD_PASSWORD="team-secret"
envguard encrypt
envguard decrypt

Add .env.enc to git, add .env to .gitignore. Team members decrypt with the shared password.

envguard hook install — Pre-commit Hook

$ envguard hook install
Installed pre-commit hook at .git/hooks/pre-commit

This runs envguard check before every commit. Failed checks block the commit.

⚙️ Configuration

Create .envguard.yaml in your project root:

# Paths
env_file: .env
schema_file: .env.schema

# Scanning
scan_paths:
  - src/
  - lib/
  - cmd/
ignore_patterns:
  - node_modules/
  - vendor/
  - dist/
  - build/
  - .git/

# Custom secret patterns
secret_patterns:
  - name: internal_token
    pattern: "MYAPP_[A-Z]+_TOKEN"

# Variables to ignore in validation
ignore_vars:
  - PATH
  - HOME
  - USER
  - SHELL

🏗️ Tech Stack

• Language: Go — Fast, single binary, cross-platform
• CLI Framework: Cobra — Industry-standard Go CLI
• Encryption: AES-256-GCM with scrypt key derivation
• Color Output: fatih/color — Cross-platform terminal colors

📁 Project Structure

envguard/
├── cmd/envguard/
│   └── main.go              # Entry point, Cobra commands
├── internal/
│   ├── envfile/
│   │   ├── parser.go         # .env file parser
│   │   └── parser_test.go
│   ├── scanner/
│   │   ├── scanner.go        # Directory walker + interface
│   │   ├── javascript.go     # JS/TS patterns
│   │   ├── python.go         # Python patterns
│   │   ├── golang.go         # Go patterns
│   │   ├── rust.go           # Rust patterns
│   │   ├── docker.go         # Dockerfile/compose patterns
│   │   └── scanner_test.go
│   ├── validator/
│   │   ├── validator.go      # Validation engine
│   │   ├── schema.go         # Schema parsing
│   │   ├── types.go          # Type validators
│   │   └── validator_test.go
│   ├── differ/
│   │   ├── differ.go         # Env file diffing
│   │   └── differ_test.go
│   ├── gitguard/
│   │   ├── gitguard.go       # Security checks
│   │   ├── patterns.go       # Secret detection patterns
│   │   └── gitguard_test.go
│   ├── sync/
│   │   ├── crypto.go         # AES-256-GCM encrypt/decrypt
│   │   └── crypto_test.go
│   └── config/
│       ├── config.go         # .envguard.yaml parsing
│       └── config_test.go
├── .github/workflows/        # CI + Release
├── .goreleaser.yaml
├── Makefile
├── BACKLOG.md
├── CHANGELOG.md
├── CONTRIBUTING.md
└── README.md

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT — use it however you want.