🛡️ 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:

npm install -g shieldx

🖥️ 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):

shieldx generate .env

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:

shieldx scan ./src

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:

shieldx fix ./src

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:

shieldx audit

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

🛠️ 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

💡 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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🛡️ ShieldX

🚀 Features

📦 Installation

🖥️ Usage

1. Compare two `.env` files

2. Generate `.env.example`

3. Scan project for hardcoded secrets

4. Validate required variables

5. Fix hardcoded secrets

6. Full Security Audit

🔧 Advanced Usage

CI/CD Integration

Pre-commit Hook

JSON Output for Automation

📅 Roadmap

🛠️ Development

🧪 Testing

🤝 Contributing

📜 License

💡 Tips

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🛡️ ShieldX

🚀 Features

📦 Installation

🖥️ Usage

1. Compare two .env files

2. Generate .env.example

3. Scan project for hardcoded secrets

4. Validate required variables

5. Fix hardcoded secrets

6. Full Security Audit

🔧 Advanced Usage

CI/CD Integration

Pre-commit Hook

JSON Output for Automation

📅 Roadmap

🛠️ Development

🧪 Testing

🤝 Contributing

📜 License

💡 Tips

1. Compare two `.env` files

2. Generate `.env.example`