🛡️ 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	user@example.com
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:s3cret@db.example.com"

# 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	合法邮箱	user@example.com
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	有効なメールアドレス	user@example.com
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