๐ก๏ธ ShieldX
ShieldX is a blazing-fast CLI tool to compare, sync, validate, audit, and scan your environment/config files.
It helps developers avoid missing variables, catch hardcoded secrets in code, and keep configs consistent across environments.
Short. Secure. Smart. โ That's ShieldX.
๐ Features
- ๐ Compare: Check differences between
.env files (e.g., .env vs .env.production)
- โก Generate: Create a
.env.example automatically from an existing .env
- ๐ก๏ธ Scan: Detect hardcoded secrets (API keys, tokens, DB URLs) with severity levels
- ๐ง Fix: Interactively move hardcoded secrets to
.env and replace them in code
- โ
Validate: Ensure
.env files have all required variables
- ๐ Audit: Run a full security health check with a scored report
- ๐ JSON Output: Perfect for CI/CD pipelines
- ๐ซ Smart Ignoring: Use
.shieldxignore to skip files
- ๐ฏ Exit Codes: Non-zero exit on issues for CI/CD integration
- ๐ฆ Lightweight: Zero bloat
- ๐ Security-first: 30+ secret pattern detectors with severity levels
๐ฆ Installation
Use it instantly with npx (no install required):
npx shieldx compare .env .env.example
Or install globally:
๐ฅ๏ธ Usage
1. Compare two .env files
Compare files and see missing/extra variables:
shieldx compare .env .env.production
Options:
-j, --json - Output in JSON format
-v, --verbose - Show detailed output
Example output:
๐ Comparison: .env vs .env.production
โ Missing in .env.production (2):
- SECRET_KEY
- API_TOKEN
โ ๏ธ Extra in .env.production (1):
+ NEW_FEATURE_FLAG
Total: 10 keys in .env, 9 keys in .env.production
CI/CD Integration:
# Exit code 1 if files don't match
shieldx compare .env .env.example --json > comparison.json
2. Generate .env.example
Create a template file with keys only (no sensitive values):
Options:
-o, --output <file> - Custom output path (default: .env.example)
-f, --force - Overwrite existing file
-j, --json - Output in JSON format
-v, --verbose - List all generated keys
Examples:
# Generate with custom output
shieldx generate .env -o .env.template
# Force overwrite
shieldx generate .env --force
# See what keys were generated
shieldx generate .env --verbose
3. Scan project for hardcoded secrets
Detect hardcoded API keys, passwords, tokens, and more:
Options:
-j, --json - Output in JSON format for parsing
-v, --verbose - Show skipped files
-q, --quiet - Only show errors
Security Patterns Detected:
- โ
Stripe API keys (live & test)
- โ
AWS credentials
- โ
GitHub tokens
- โ
Google API keys
- โ
Database connection strings
- โ
JWT tokens
- โ
Private keys (RSA, PEM, SSH)
- โ
OAuth tokens (Slack, Facebook, Google)
- โ
Bearer tokens
- โ
And 20+ more patterns!
Severity Levels:
- ๐ด CRITICAL - Private keys, credentials with immediate risk
- ๐ HIGH - API keys, tokens, passwords
- ๐ก MEDIUM - Session IDs, JWTs
- ๐ต LOW - Potential secrets, long strings
Example output:
๐ Scanning ./src for hardcoded secrets...
๐จ [HIGH] Stripe Live Key in src/payment.js:15
const key = "sk_live_abcd1234..."
๐ก Move this to .env file
โ ๏ธ Security Report:
Total issues: 3
Files scanned: 47
CRITICAL: 1
High: 2
Use .shieldxignore:
Create a .shieldxignore file to skip certain paths:
# ShieldX Ignore Patterns
**/test/**
*.test.js
docs/
4. Validate required variables
Ensure .env files have all required keys:
shieldx validate .env --keys "DATABASE_URL,API_KEY,SECRET"
Options:
-k, --keys <keys> - Comma-separated required keys
-c, --config <file> - Load required keys from file
-j, --json - Output in JSON format
-v, --verbose - Show all present keys
Using a config file:
Create required-keys.txt:
DATABASE_URL
API_KEY
SECRET_KEY
Then run:
shieldx validate .env --config required-keys.txt
Example output:
๐ Validating .env
โ Missing 2 required variable(s):
โ API_KEY
โ SECRET_KEY
๐ก Add the missing variables to .env
5. Fix hardcoded secrets
Interactively move secrets from your code to .env:
Options:
--auto - Move all High/Critical secrets automatically
--dry-run - Preview changes without modifying files
--env-file <file> - Target .env file (default: .env)
Example:
ShieldX will find a secret:
const KEY = "sk_live_12345";
And replace it with:
const KEY = process.env.STRIPE_LIVE_KEY;
While adding the following to your .env:
STRIPE_LIVE_KEY="sk_live_12345"
6. Full Security Audit
Run a comprehensive security health check across your entire project:
Options:
-j, --json - Output in JSON format for CI/CD
-s, --strict - Fail on any issue (even warnings)
-d, --dir <path> - Directory to scan (default: .)
--env-file <file> - Path to .env file (default: .env)
What it checks:
| Check |
Description |
| ๐ Gitignore Safety |
Ensures .env is in .gitignore |
| ๐ Env Files Exist |
Verifies .env and .env.example are present |
| ๐ Env Sync |
Compares .env vs .env.example for drift |
| ๐ก๏ธ Secret Scan |
Scans codebase for hardcoded secrets |
| ๐ Empty Values |
Flags .env keys with no value |
Example output:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ก๏ธ ShieldX Security Audit โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ CHECK RESULTS โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ PASS ๐ Gitignore Safety โ
โ .env is protected in .gitignore โ
โ โ PASS ๐ Env Files Exist โ
โ .env and .env.example both present โ
โ โ WARN ๐ Env Sync โ
โ 2 keys not in .env.example โ
โ โ FAIL ๐ก๏ธ Secret Scan โ
โ 3 issue(s) found (1 critical, 2 high) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ SECURITY SCORE โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ C 55/100 โ
โ NEEDS ATTENTION โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
CI/CD Integration:
# Fail pipeline on any critical/high issues
shieldx audit --json > audit-report.json
# Strict mode: fail on ANY issue
shieldx audit --strict
๐ง Advanced Usage
CI/CD Integration
ShieldX returns exit code 1 on issues, perfect for CI/CD:
# GitHub Actions example
- name: Validate environment
run: |
shieldx compare .env.example .env.production --json
shieldx scan ./src
shieldx validate .env.production --keys "DATABASE_URL,API_KEY"
Pre-commit Hook
Add to .git/hooks/pre-commit:
#!/bin/bash
shieldx scan ./src --quiet
if [ $? -ne 0 ]; then
echo "โ Secrets detected! Fix them before committing."
exit 1
fi
JSON Output for Automation
All commands support --json flag:
# Get JSON output for parsing
shieldx scan ./src --json > security-report.json
# Parse with jq
shieldx scan ./src --json | jq '.issuesFound'
๐
Roadmap
- Compare
.env files
- Generate
.env.example
- Scan for secrets with severity levels
- Validate required keys
- JSON output for CI/CD
-
.shieldxignore support
- Exit codes for automation
- GitHub Actions integration
- Auto-fix suggestions
- Full project security audit with scoring
- Sync configs across environments
- VSCode plugin integration
- AI-powered secret detection (v2)
- Encrypt/decrypt
.env files
๐ ๏ธ Development
Clone and run locally:
git clone https://github.com/zeemscript/shieldx.git
cd shieldx
npm install
npm link
Run tests:
npm test
npm run test:watch
Now you can run:
shieldx compare .env .env.example
๐งช Testing
ShieldX includes a comprehensive test suite:
# Run all tests
npm test
# Run with coverage
npm test -- --coverage
# Watch mode
npm run test:watch
๐ค Contributing
Contributions, issues, and feature requests are welcome!
- Fork the repo
- Create your feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
Check issues for ideas!
๐ License
MIT ยฉ 2025 zeemscript
๐ก Tips
Best Practices:
- โ
Run
shieldx scan before every commit
- โ
Use
shieldx validate in deployment pipelines
- โ
Keep
.env.example updated with shieldx generate
- โ
Never commit
.env files (add to .gitignore)
- โ
Use
.shieldxignore for test fixtures
Common Workflows:
# Setup new project
shieldx generate .env
git add .env.example
# Before deploying
shieldx validate .env.production --keys "DATABASE_URL,API_KEY"
shieldx compare .env.example .env.production
# Security audit
shieldx scan ./src --verbose
Made with โค๏ธ by developers, for developers.