Back to search
env-guard-cli
MCP serverGitHub
Zero-dependency .env parser, polyglot drift scanner, secret hygiene guard, schema validator, and secret-safe MCP server
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/pie527645-cloud--env-guard-cli)HTML
<a href="/listings/pie527645-cloud--env-guard-cli"><img src="/api/listings/pie527645-cloud--env-guard-cli/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requires **Node.js `>= 20.18.1`**.
git clone https://github.com/pie527645-cloud/env-guard-cli.git cd env-guard-cli npm install npm run build
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 156 lines
- # @pie527645-cloud/env-guard-cli
- Spec-compliant zero-dependency `.env` parser, polyglot source-code drift scanner, secret hygiene guard, `.env.schema.json` validator, and secret-safe Model Context Protocol (MCP) server.
- ## Features
- - **Spec-Compliant Linear `.env` Parser & Serializer:** Supports UTF-8 BOM stripping, CRLF normalization, `#` full-line and inline comments, `export KEY=VAL`, unquoted, single-quoted, and double-quoted multiline values, escape sequences (`\n`, `\r`, `\t`, `\"`, `\\`, `\$`), `${VAR}` and `${VAR:-default}` variable interpolation with circular-reference cycle detection, and null-prototype (`Object.create(null)`) lookup maps.
- - **Polyglot Code Reference Scanner:** Linear O(N) scanner across TypeScript/JavaScript (`process.env.X`, `process.env['X']`, `import.meta.env.X`), Python (`os.environ[...]`, `os.getenv`), Go (`os.Getenv`, `os.LookupEnv`), and Rust (`env::var`, `option_env!`). Respects `.gitignore` with bounded rule lengths (`<= 4096`), skips binaries and files larger than `512 KB`.
- - **`.env.schema.json` Validation:** Enforces `string`, `int`, `port` (`1..65535`), `url`, `bool`, `email`, `secret` (minimum length, Shannon entropy, and placeholder rejection), `enum`, `required`, and `default` constraints without echoing raw values.
- - **Secret-Safe Redaction & SARIF 2.1.0 Reporting:** Flags leaked credentials in `.env.example`, weak/placeholder values in `.env`, missing required keys, and undocumented code variables across `pretty`, `json`, `markdown`, and GitHub Code Scanning `sarif` formats (`***` redacted).
- - **3 Secret-Safe MCP Tools:** Confined strictly to `--root` with canonical `realpathSync` symlink/traversal protection and a hard non-disclosure invariant (returns key names, booleans, bucketed length masks, `file:line` references, and rule compliance statuses — never raw values).
- ## Architecture
- ```mermaid
- flowchart LR
- Code["Polyglot Codebase (TS/JS, Python, Go, Rust)"] --> Scanner["Linear Code & .gitignore Scanner"]
- EnvFile[".env & .env.example"] --> Parser["Linear .env Spec Parser & Cycle Detector"]
- SchemaFile[".env.schema.json"] --> Validator["Schema & Secret Hygiene Validator"]
- Scanner --> Analyzer["Workspace Drift & Redaction Engine"]
- Parser --> Analyzer
- Validator --> Analyzer
- Analyzer --> CLI["CLI (sync / check / SARIF 2.1.0)"]
- Analyzer --> MCP["Secret-Safe Stdio MCP Server (--root confined)"]
- ```
- ## Installation (From Source)
- Requires **Node.js `>= 20.18.1`**.
- ```bash
- git clone https://github.com/pie527645-cloud/env-guard-cli.git
- cd env-guard-cli
- npm install
- npm run build
- ```
- ## CLI Usage
- ### 1. Audit Drift, Schema Rules & Secret Hygiene (`check`)
- ```bash
- node dist/cli.js check .
- node dist/cli.js check ./services/api --schema .env.schema.json --format pretty
- node dist/cli.js check . --format sarif --fail-on high > results.sarif
- ```
- **Options:**
- - `--env <path>`: Relative path to environment file (default: `.env`)
- - `--example <path>`: Relative path to example file (default: `.env.example`)
- - `--schema <path>`: Relative path to schema file (default: `.env.schema.json`)
- - `--format pretty|json|markdown|sarif`: Output format (default: `pretty`)
- - `--fail-on critical|high|medium|low`: Minimum severity threshold returning exit code `1` (default: `medium`)
- **Exit Codes:**
- - `0`: All checks passed below threshold
- - `1`: One or more findings met or exceeded `--fail-on`
- - `2`: Invalid CLI arguments or blocked out-of-root file path
- ### 2. Synchronize Keys & Generate Scrubbed `.env.example` (`sync`)
- ```bash
- node dist/cli.js sync . --format pretty
- node dist/cli.js sync . --write-example --schema .env.schema.json
- ```
- `--write-example` generates a deterministic `.env.example` containing only safe placeholders or empty assignments. Real values from `.env` are never copied.
- ### 3. Launch Secret-Safe MCP Server (`mcp`)
- ```bash
- node dist/cli.js mcp --root /path/to/project
- # Or directly via the MCP entrypoint:
- node dist/mcp.js --root /path/to/project
- ```
- #### MCP Client Configuration
- ```json
- {
- "mcpServers": {
- "env-guard": {
- "command": "node",
- "args": [
- "/absolute/path/to/env-guard-cli/dist/mcp.js",
- "--root",
- "/absolute/path/to/workspace"
- ]
- }
- }
- }
- ```
- #### Exposed MCP Tools
- 1. `list_env_keys(subpath?)`: Lists discovered environment variable keys across source code, `.env.example`, `.env.schema.json`, and `.env` presence booleans (`hasEnvValue`, `inExample`, `maskedLength`, `codeLocations`, `validationStatus`) without exposing values.
- 2. `check_env_drift(subpath?)`: Returns missing, unused, undocumented, and redacted secret-hygiene findings (`***`).
- 3. `validate_env_schema(schemaPath?)`: Validates workspace environment variables against `.env.schema.json` rules without returning secret values.
- #### Security Audit Note (MCP104)
- `list_env_keys` inspects `.env` presence flags by design while enforcing strict non-disclosure (it returns only key names, presence booleans, and bucketed mask lengths, never raw values). When auditing `env-guard` with `@pie527645-cloud/mcp-doctor`, `list_env_keys` produces 1 expected `MCP104` (`critical`) finding for referencing `.env` in its tool description, while `validate_env_schema` references to `.env.schema.json` report as `info`.
- ## `.env.schema.json` Example
- ```json
- {
- "variables": {
- "PORT": {
- "type": "port",
- "required": true,
- "default": 3000,
- "description": "HTTP listen port"
- },
- "PUBLIC_BASE_URL": {
- "type": "url",
- "required": true
- },
- "LOG_LEVEL": {
- "type": "enum",
- "values": ["debug", "info", "warn", "error"],
- "default": "info"
- },
- "ENABLE_WORKERS": {
- "type": "bool",
- "default": false
- },
- "MAX_RETRIES": {
- "type": "int",
- "min": 0,
- "max": 10,
- "default": 3
- },
- "SESSION_SECRET": {
- "type": "secret",
- "required": true,
- "minLength": 24,
- "minEntropy": 3.5
- }
- }
- }
- ```
- ## Development & Testing
- ```bash
- npm run lint
- npm run build
- npm test
- ```
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.