EnvGuard

Security linting for environment variables, Docker, CI, Kubernetes, and runtime configuration.

npm npm provenance CI

EnvGuard helps developers catch unsafe environment values, risky runtime defaults, Docker/Compose hazards, and CI/CD configuration issues before they reach production. It complements deep secret-history scanners like Gitleaks and TruffleHog rather than replacing them.

EnvGuard V2 is the current stable release and requires Node.js 22 or newer.

Quick Start

CLI

Run EnvGuard without installing it globally:

npx @bhargavmahanta/envguard scan .

GitHub Action

Add EnvGuard to pull requests without installing it in the repository:

name: EnvGuard

on:
  pull_request:

permissions:
  contents: read

jobs:
  envguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: bhargavmahanta/envGuard@v2
        with:
          fail-on: high

See the complete CI guide for SARIF uploads, annotations, and immutable version pins.

SDK

Use EnvGuard from TypeScript or JavaScript:

import { scan } from "@bhargavmahanta/envguard";

const result = await scan({ target: ".", failOn: "high" });
console.log(result.passed, result.findings);

Agents and MCP

Use deterministic, always-masked JSON from build systems and coding agents:

npx @bhargavmahanta/envguard scan . --agent

For tool-based integrations, use the root-restricted EnvGuard MCP server. See the agent integration guide for exit codes and safe focused scans.

Working Templates

• Node.js EnvGuard template — Node preset, safe example environment, npm script, and a passing Action workflow
• Next.js EnvGuard template — TypeScript App Router, Next preset, and a passing Action workflow

Features

• Scan .env, config, Docker, Compose, and GitHub Actions files
• Scan GitLab CI and CircleCI configuration
• Check .env hygiene and .env.example / .env.schema drift
• Detect real-looking secrets, weak secrets, unsafe runtime settings, and wildcard CORS
• Detect Docker and CI/CD security issues
• Detect conservative Kubernetes and Helm configuration risks
• Mask secrets by default in terminal, JSON, Markdown, SARIF, and GitHub annotation reports
• Support local CLI usage, pre-commit hooks, and GitHub Actions
• Scan only staged or changed files for fast developer workflows
• Use the bundled bhargavmahanta/envGuard@v2 GitHub Action
• Configure behavior with envguard.config.yml and .envguardignore

Installation

Install the stable V2 release:

npm install --save-dev @bhargavmahanta/envguard

Or install globally:

npm install -g @bhargavmahanta/envguard

EnvGuard releases are published through npm trusted publishing with provenance. Verify the installed dependency signatures with npm audit signatures.

Use a declarative framework preset:

npm install --save-dev @bhargavmahanta/envguard @bhargavmahanta/envguard-config-next

extends:
  - "@bhargavmahanta/envguard-config-next"

CLI Commands

envguard scan .
envguard scan . --ci --fail-on high
envguard scan . --format json --output report.json
envguard scan . --format markdown --output report.md
envguard scan --staged
envguard scan --changed origin/main
envguard scan . --format github
envguard baseline audit
envguard init
envguard rules
envguard doctor --json
envguard explain k8s-privileged
envguard scan . --agent

On Windows PowerShell, if script execution blocks the generated envguard.ps1 shim, use the .cmd shim:

envguard.cmd scan .
npx --package @bhargavmahanta/envguard envguard.cmd scan .

Example Output

[HIGH] Database URL contains a password (database-url-password)
  File: .env:3
  Preview: DATABASE_URL=postgres://admin:********@localhost:5432/app
  Risk: 100/100 | Confidence: high
  Fix: Move database credentials to a secret manager or untracked local env file.

Supported Detections

• AWS keys, GitHub tokens, Stripe keys, Slack tokens, Google API keys
• Private keys, JWT tokens, bearer tokens, database URLs with passwords
• Weak JWT/session/API secrets and placeholder values
• DEBUG=true, development runtimes, disabled SSL/TLS verification
• Wildcard CORS and wildcard CORS with credentials
• .env duplicate keys, empty values, malformed lines, invalid keys, and schema drift
• Dockerfiles that copy .env, use latest, run as root, miss .dockerignore, or use remote ADD
• Compose privileged containers, public database ports, host networking, unsafe volumes, inline secrets, and latest tags
• GitHub Actions secret printing, pull_request_target, floating actions, broad permissions
• GitLab CI and CircleCI secret-printing and risky defaults

Configuration

Create starter files:

envguard init

Example envguard.config.yml:

severity:
  fail_on: high

entropy:
  enabled: true
  threshold: 4.2

output:
  mask: true

rules:
  disabled: []
  packs:
    - node
    - python
    - docker
    - github-actions
    - ci
  custom: []

allow: []

scan:
  max_file_mb: 2
  timeout_seconds: 0
  include_gitignored: false

Example .envguardignore:

node_modules/
dist/
docs/fixtures/

Reports

EnvGuard supports:

terminal
json
markdown
sarif
github

Sample Vulnerable Project

Try EnvGuard against the included fake vulnerable project:

npm install
npm run build
node packages/envguard/dist/cli.js scan examples/vulnerable-project

How EnvGuard Fits

Tool	Primary focus	Use with EnvGuard for
EnvGuard	Environment, runtime, Docker, Kubernetes, and CI configuration	Fast configuration-security feedback before production
Gitleaks	Git history and repository secret scanning	Deep secret-history coverage
TruffleHog	Broad secret discovery and credential verification	Incident response and verified credential detection

EnvGuard does not replace a git-history secret scanner. See the full comparison and recommended pairing.

Limitations

EnvGuard uses pattern-based and heuristic detection. It may produce false positives or miss some secrets. It does not validate, transmit, or use detected credentials.

Documentation

• Rule catalog
• How EnvGuard compares
• Remediation guide
• GitHub Actions setup
• Pre-commit setup
• Integration examples
• Reporting
• Public API surface
• SDK guide
• Presets
• Container image
• Benchmarks
• Agent integration
• Package family
• MCP server
• Release process
• V2.0 release notes
• V1.0 release notes
• V1.0 readiness
• Compatibility
• Design notes
• Roadmap

Community

• Read CONTRIBUTING.md before opening a pull request.
• Report sensitive vulnerabilities privately according to SECURITY.md.

License

MIT

Disclaimer

EnvGuard is a defensive security tool. Only scan repositories you own or have permission to test.