Skip to content
Back to search

env-guard-cli

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pie527645-cloud--env-guard-cli/badge.svg)](/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
  1. # @pie527645-cloud/env-guard-cli
  2. 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.
  3. ## Features
  4. - **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.
  5. - **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`.
  6. - **`.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.
  7. - **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).
  8. - **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).
  9. ## Architecture
  10. ```mermaid
  11. flowchart LR
  12. Code["Polyglot Codebase (TS/JS, Python, Go, Rust)"] --> Scanner["Linear Code & .gitignore Scanner"]
  13. EnvFile[".env & .env.example"] --> Parser["Linear .env Spec Parser & Cycle Detector"]
  14. SchemaFile[".env.schema.json"] --> Validator["Schema & Secret Hygiene Validator"]
  15. Scanner --> Analyzer["Workspace Drift & Redaction Engine"]
  16. Parser --> Analyzer
  17. Validator --> Analyzer
  18. Analyzer --> CLI["CLI (sync / check / SARIF 2.1.0)"]
  19. Analyzer --> MCP["Secret-Safe Stdio MCP Server (--root confined)"]
  20. ```
  21. ## Installation (From Source)
  22. Requires **Node.js `>= 20.18.1`**.
  23. ```bash
  24. git clone https://github.com/pie527645-cloud/env-guard-cli.git
  25. cd env-guard-cli
  26. npm install
  27. npm run build
  28. ```
  29. ## CLI Usage
  30. ### 1. Audit Drift, Schema Rules & Secret Hygiene (`check`)
  31. ```bash
  32. node dist/cli.js check .
  33. node dist/cli.js check ./services/api --schema .env.schema.json --format pretty
  34. node dist/cli.js check . --format sarif --fail-on high > results.sarif
  35. ```
  36. **Options:**
  37. - `--env <path>`: Relative path to environment file (default: `.env`)
  38. - `--example <path>`: Relative path to example file (default: `.env.example`)
  39. - `--schema <path>`: Relative path to schema file (default: `.env.schema.json`)
  40. - `--format pretty|json|markdown|sarif`: Output format (default: `pretty`)
  41. - `--fail-on critical|high|medium|low`: Minimum severity threshold returning exit code `1` (default: `medium`)
  42. **Exit Codes:**
  43. - `0`: All checks passed below threshold
  44. - `1`: One or more findings met or exceeded `--fail-on`
  45. - `2`: Invalid CLI arguments or blocked out-of-root file path
  46. ### 2. Synchronize Keys & Generate Scrubbed `.env.example` (`sync`)
  47. ```bash
  48. node dist/cli.js sync . --format pretty
  49. node dist/cli.js sync . --write-example --schema .env.schema.json
  50. ```
  51. `--write-example` generates a deterministic `.env.example` containing only safe placeholders or empty assignments. Real values from `.env` are never copied.
  52. ### 3. Launch Secret-Safe MCP Server (`mcp`)
  53. ```bash
  54. node dist/cli.js mcp --root /path/to/project
  55. # Or directly via the MCP entrypoint:
  56. node dist/mcp.js --root /path/to/project
  57. ```
  58. #### MCP Client Configuration
  59. ```json
  60. {
  61. "mcpServers": {
  62. "env-guard": {
  63. "command": "node",
  64. "args": [
  65. "/absolute/path/to/env-guard-cli/dist/mcp.js",
  66. "--root",
  67. "/absolute/path/to/workspace"
  68. ]
  69. }
  70. }
  71. }
  72. ```
  73. #### Exposed MCP Tools
  74. 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.
  75. 2. `check_env_drift(subpath?)`: Returns missing, unused, undocumented, and redacted secret-hygiene findings (`***`).
  76. 3. `validate_env_schema(schemaPath?)`: Validates workspace environment variables against `.env.schema.json` rules without returning secret values.
  77. #### Security Audit Note (MCP104)
  78. `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`.
  79. ## `.env.schema.json` Example
  80. ```json
  81. {
  82. "variables": {
  83. "PORT": {
  84. "type": "port",
  85. "required": true,
  86. "default": 3000,
  87. "description": "HTTP listen port"
  88. },
  89. "PUBLIC_BASE_URL": {
  90. "type": "url",
  91. "required": true
  92. },
  93. "LOG_LEVEL": {
  94. "type": "enum",
  95. "values": ["debug", "info", "warn", "error"],
  96. "default": "info"
  97. },
  98. "ENABLE_WORKERS": {
  99. "type": "bool",
  100. "default": false
  101. },
  102. "MAX_RETRIES": {
  103. "type": "int",
  104. "min": 0,
  105. "max": 10,
  106. "default": 3
  107. },
  108. "SESSION_SECRET": {
  109. "type": "secret",
  110. "required": true,
  111. "minLength": 24,
  112. "minEntropy": 3.5
  113. }
  114. }
  115. }
  116. ```
  117. ## Development & Testing
  118. ```bash
  119. npm run lint
  120. npm run build
  121. npm test
  122. ```
  123. ## License
  124. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.