🛡️ EnvGuard

Environment Variable Validation, Security Scanning & Documentation Generator

English · 中文 · 日本語

🇬🇧 English

Why EnvGuard?

Misconfigured environment variables are a leading cause of production incidents. EnvGuard provides a single tool to validate, secure, and document your project's configuration — catching errors before they reach production.

Features

• Schema Validation — Define types, required fields, enums, ranges, and patterns for every variable
• Security Scanning — Detect accidentally committed secrets (AWS keys, GitHub tokens, private keys, etc.)
• Log Redaction — Automatically redact sensitive values in .env files and log output
• Framework Templates — One-command config generation for Next.js, Express, Django, Rails, and more
• Auto Documentation — Generate .env.example and markdown docs from your schema
• Environment Diff — Compare .env files across dev/staging/prod to find drift
• CI/CD Ready — Exit codes and GitHub Action integration for automated checks
• Zero Dependencies — Pure Node.js, no external packages required
• Multi-format Support — Works with .env, .env.local, .env.production, and more

Quick Start

# Install
npm install -g @anhuijie/envguard

# Create config
envguard init

# Validate environment variables
envguard validate

# Scan for secrets
envguard check

# Generate documentation
envguard docs

# Compare environments
envguard diff .env.development .env.production

# Redact sensitive values
envguard redact
envguard redact --output .env.redacted

# List available framework templates
envguard template list

# Apply a framework template
envguard template apply nextjs

# Merge template into existing config
envguard template apply express --merge

Configuration

Create envguard.config.js in your project root:

module.exports = {
  schema: {
    NODE_ENV: {
      required: true,
      type: 'string',
      enum: ['development', 'staging', 'production', 'test'],
      description: 'Application environment',
    },
    PORT: {
      required: false,
      type: 'port',
      default: '3000',
      description: 'Server port',
    },
    DATABASE_URL: {
      required: true,
      type: 'url',
      description: 'Database connection string',
    },
    JWT_SECRET: {
      required: true,
      type: 'string',
      description: 'Secret key for JWT signing',
    },
  },
  security: {
    minSeverity: 'medium',
    ignoreKeys: [],
  },
};

Supported Types

| Type | Description | Example | |------|-------------|---------| | string | Any string value | any text | | number | Numeric value with optional min/max | 42 | | boolean | true/false, 1/0, yes/no | true | | url | Valid URL | https://example.com | | email | Valid email address | [email protected] | | port | Valid port number (0-65535) | 3000 | | json | Valid JSON string | '{"key":"value"}' | | regex | Valid regex pattern | ^\\d+$ | | date | ISO 8601 date string | 2024-01-15 | | semver | Semantic version | 1.2.3 | | color | CSS color (hex, rgb, named) | #ff6600 |

Rule Options

| Option | Type | Description | |--------|------|-------------| | required | boolean | Variable must be set | | type | string | Value type validation | | default | any | Default value if not set | | enum | array | Allowed values | | min / max | number | Range constraints (for number type) | | pattern | string | Regex pattern the value must match | | deprecated | boolean | Mark as deprecated | | replacement | string | Suggested replacement for deprecated vars | | description | string | Human-readable description |

Security Scanning

EnvGuard detects these secret types:

• AWS Access Keys & Secret Keys
• GitHub / GitLab Tokens
• Slack Tokens
• Stripe Live Keys
• Private Keys (RSA, EC, DSA)
• JWT Secrets
• Database URLs with embedded passwords
• Generic API Keys, Passwords, and Secrets

Log Redaction

Redact sensitive values before sharing .env files or log output:

# Redact .env file values (shows which keys are redacted)
envguard redact

# Write redacted file to disk
envguard redact --output .env.redacted

# Redact a text string (e.g. log message)
envguard redact --text "Connected as admin:[email protected]"

# Custom redaction mask
envguard redact --mask "[REDACTED]"

# Skip specific keys
envguard redact --ignore-keys "NODE_ENV,APP_NAME"

Programmatic API:

const { redactObject, redactString, createRedactionMiddleware } = require('@anhuijie/envguard');

// Redact an object
const safe = redactObject(process.env);
// { API_KEY: '***', DATABASE_URL: '***', PORT: '3000' }

// Redact a string
const safeLog = redactString('User logged in with token=ghp_abc123');
// 'User logged in with token=***'

// Create middleware for logging libraries
const middleware = createRedactionMiddleware({ mask: '[HIDDEN]' });
console.log(middleware('JWT_SECRET=abc123'));
// 'JWT_SECRET=[HIDDEN]'

Framework Templates

Generate project-specific configuration from built-in templates:

# List all available templates
envguard template list

# Apply a template (creates envguard.config.js)
envguard template apply nextjs
envguard template apply express
envguard template apply django
envguard template apply rails
envguard template apply docker-compose
envguard template apply serverless

# Merge template into existing config
envguard template apply express --merge

# Overwrite existing config
envguard template apply nextjs --force

Available templates:

| Template | Description | Variables | |----------|-------------|-----------| | nextjs | Next.js full-stack application | 11 vars (5 required) | | express | Express.js REST API server | 12 vars (3 required) | | django | Django Python web application | 16 vars (4 required) | | rails | Ruby on Rails web application | 18 vars (3 required) | | docker-compose | Docker Compose multi-container setup | 18 vars (1 required) | | serverless | Serverless Framework AWS Lambda | 20 vars (2 required) |

CI/CD Integration

GitHub Actions:

- name: Validate env config
  run: npx @anhuijie/envguard validate

- name: Security check
  run: npx @anhuijie/envguard check

The command exits with code 1 on validation errors or critical security findings, failing the build.

Programmatic API

const { validateEnv, scanForSecrets, generateEnvExample, redactObject, redactString } = require('@anhuijie/envguard');

const schema = { PORT: { required: true, type: 'port' } };
const result = validateEnv(process.env, schema);
// { valid: true, errors: [], warnings: [], checked: 1 }

const secrets = scanForSecrets(process.env);
// { findings: [], hasCritical: false, total: 0 }

const example = generateEnvExample(schema);
// "# Server port\n# type: port\nPORT=\n"

const safeEnv = redactObject(process.env);
// { API_KEY: '***', PORT: '3000' }

License

MIT

🇨🇳 中文

为什么需要 EnvGuard？

环境变量配置错误是生产事故的主要原因之一。EnvGuard 提供一站式工具来验证、保护和文档化项目配置——在错误到达生产环境之前就将其捕获。

功能特性

• Schema 验证 — 为每个变量定义类型、必填、枚举、范围和正则模式
• 安全扫描 — 检测意外提交的密钥（AWS 密钥、GitHub Token、私钥等）
• 自动文档 — 从 Schema 生成 .env.example 和 Markdown 文档
• 环境对比 — 比较 dev/staging/prod 的 .env 文件差异
• CI/CD 就绪 — 退出码和 GitHub Action 集成，支持自动化检查
• 零依赖 — 纯 Node.js 实现，无需外部包
• 多格式支持 — 支持 .env、.env.local、.env.production 等

快速开始

# 安装
npm install -g @anhuijie/envguard

# 创建配置
envguard init

# 验证环境变量
envguard validate

# 扫描敏感信息
envguard check

# 生成文档
envguard docs

# 对比环境差异
envguard diff .env.development .env.production

配置

在项目根目录创建 envguard.config.js：

module.exports = {
  schema: {
    NODE_ENV: {
      required: true,
      type: 'string',
      enum: ['development', 'staging', 'production', 'test'],
      description: '应用运行环境',
    },
    PORT: {
      required: false,
      type: 'port',
      default: '3000',
      description: '服务端口',
    },
    DATABASE_URL: {
      required: true,
      type: 'url',
      description: '数据库连接字符串',
    },
    JWT_SECRET: {
      required: true,
      type: 'string',
      description: 'JWT 签名密钥',
    },
  },
  security: {
    minSeverity: 'medium',
    ignoreKeys: [],
  },
};

支持的类型

| 类型 | 说明 | 示例 | |------|------|------| | string | 任意字符串 | 任意文本 | | number | 数值，支持 min/max | 42 | | boolean | true/false、1/0、yes/no | true | | url | 合法 URL | https://example.com | | email | 合法邮箱 | [email protected] | | port | 合法端口号 (0-65535) | 3000 | | json | 合法 JSON 字符串 | '{"key":"value"}' | | regex | 合法正则表达式 | ^\\d+$ | | date | ISO 8601 日期字符串 | 2024-01-15 | | semver | 语义化版本号 | 1.2.3 | | color | CSS 颜色（hex、rgb、命名色） | #ff6600 |

安全扫描

EnvGuard 可检测以下密钥类型：

• AWS 访问密钥和密钥
• GitHub / GitLab Token
• Slack Token
• Stripe Live Key
• 私钥（RSA、EC、DSA）
• JWT 密钥
• 包含密码的数据库连接 URL
• 通用 API Key、密码和密钥

CI/CD 集成

GitHub Actions：

- name: 验证环境配置
  run: npx @anhuijie/envguard validate

- name: 安全检查
  run: npx @anhuijie/envguard check

验证失败或发现严重安全问题时，命令以退出码 1 退出，使构建失败。

编程式 API

const { validateEnv, scanForSecrets, generateEnvExample, redactObject, redactString } = require('@anhuijie/envguard');

const schema = { PORT: { required: true, type: 'port' } };
const result = validateEnv(process.env, schema);
// { valid: true, errors: [], warnings: [], checked: 1 }

const secrets = scanForSecrets(process.env);
// { findings: [], hasCritical: false, total: 0 }

const example = generateEnvExample(schema);
// "# Server port\n# type: port\nPORT=\n"

const safeEnv = redactObject(process.env);
// { API_KEY: '***', PORT: '3000' }

许可证

MIT

🇯🇵 日本語

なぜ EnvGuard が必要か？

環境変数の設定ミスは本番障害の主要な原因の一つです。EnvGuard は、プロジェクトの設定を検証・保護・文書化するオールインワンツールを提供し、エラーが本番環境に到達する前に検出します。

機能

• スキーマ検証 — 各変数の型、必須、列挙、範囲、正規表現パターンを定義
• セキュリティスキャン — 誤ってコミットされたシークレットの検出（AWS キー、GitHub トークン、秘密鍵など）
• 自動ドキュメント生成 — スキーマから .env.example と Markdown ドキュメントを生成
• 環境比較 — dev/staging/prod の .env ファイルの差分を検出
• CI/CD 対応 — 終了コードと GitHub Action 統合による自動チェック
• ゼロ依存 — 外部パッケージ不要のピュア Node.js 実装
• マルチフォーマット対応 — .env、.env.local、.env.production などに対応

クイックスタート

# インストール
npm install -g @anhuijie/envguard

# 設定ファイルの作成
envguard init

# 環境変数の検証
envguard validate

# セキュリティスキャン
envguard check

# ドキュメント生成
envguard docs

# 環境の比較
envguard diff .env.development .env.production

設定

プロジェクトルートに envguard.config.js を作成：

module.exports = {
  schema: {
    NODE_ENV: {
      required: true,
      type: 'string',
      enum: ['development', 'staging', 'production', 'test'],
      description: 'アプリケーション環境',
    },
    PORT: {
      required: false,
      type: 'port',
      default: '3000',
      description: 'サーバーポート',
    },
    DATABASE_URL: {
      required: true,
      type: 'url',
      description: 'データベース接続文字列',
    },
    JWT_SECRET: {
      required: true,
      type: 'string',
      description: 'JWT 署名用シークレットキー',
    },
  },
  security: {
    minSeverity: 'medium',
    ignoreKeys: [],
  },
};

サポート型

| 型 | 説明 | 例 | |----|------|-----| | string | 任意の文字列 | 任意のテキスト | | number | 数値（min/max 対応） | 42 | | boolean | true/false、1/0、yes/no | true | | url | 有効な URL | https://example.com | | email | 有効なメールアドレス | [email protected] | | port | 有効なポート番号 (0-65535) | 3000 | | json | 有効な JSON 文字列 | '{"key":"value"}' | | regex | 有効な正規表現パターン | ^\\d+$ | | date | ISO 8601 日付文字列 | 2024-01-15 | | semver | セマンティックバージョン | 1.2.3 | | color | CSS カラー（hex、rgb、名前付き） | #ff6600 |

セキュリティスキャン

EnvGuard は以下のシークレットタイプを検出します：

• AWS アクセスキー・シークレットキー
• GitHub / GitLab トークン
• Slack トークン
• Stripe ライブキー
• 秘密鍵（RSA、EC、DSA）
• JWT シークレット
• パスワード埋め込みデータベース URL
• 汎用 API キー、パスワード、シークレット

CI/CD 統合

GitHub Actions：

- name: 環境設定の検証
  run: npx @anhuijie/envguard validate

- name: セキュリティチェック
  run: npx @anhuijie/envguard check

検証エラーや重大なセキュリティ問題が見つかった場合、コマンドは終了コード 1 で終了し、ビルドを失敗させます。

プログラマティック API

const { validateEnv, scanForSecrets, generateEnvExample, redactObject, redactString } = require('@anhuijie/envguard');

const schema = { PORT: { required: true, type: 'port' } };
const result = validateEnv(process.env, schema);
// { valid: true, errors: [], warnings: [], checked: 1 }

const secrets = scanForSecrets(process.env);
// { findings: [], hasCritical: false, total: 0 }

const example = generateEnvExample(schema);
// "# Server port\n# type: port\nPORT=\n"

const safeEnv = redactObject(process.env);
// { API_KEY: '***', PORT: '3000' }

ライセンス

MIT