/env-validator

name: env-validator
description: 'Validates .env files against code references and manifests for missing vars, type mismatches, insecure defaults, and unused entries. Triggers on: "validate env file", "check environment variables", "missing env vars", "check .env", "dotenv validation". NOT for secret scanning, use repo-sentinel.'
metadata:
  version: 1.0.1
  category: operations
  tags: [env, configuration, validation, dotenv, deployment]
  difficulty: intermediate
  phase: build

Env Validator

Validates environment variable configurations by cross-referencing `.env` files against project requirements. Catches missing variables, type errors, insecure defaults, and orphaned entries before they cause runtime failures.

Reference Files

| File | Contents | Load When | | ------------------------------------ | ------------------------------------------------- | ---------------------- | | `references/validation-rules.md` | Built-in validation rules and severity definitions | Always |

Prerequisites

• A `.env` file (or equivalent) in the project
• Optionally: `.env.example`, `docker-compose.yml`, or deployment manifests for cross-referencing

Workflow

Phase 1: Discovery

Locate environment configuration sources in the project:

1. **Primary file:** Find `.env` in the project root. If absent, check for `.env.local`, `.env.development`, `.env.production` 2. **Schema file:** Find `.env.example` or `.env.template` — this defines the expected variables 3. **Code references:** Grep for `os.environ`, `process.env`, `env::var`, `os.Getenv` patterns to find variables referenced in code 4. **Deployment manifests:** Check `docker-compose.yml`, `Dockerfile`, `k8s/` manifests for `${VAR}` or `ENV VAR` patterns

Report what was found before proceeding.

Phase 2: Schema Extraction

Build the expected variable schema from discovered sources:

For each variable found across all sources, record:

| Field | Source | | ----------- | --------------------------------------------------------- | | Name | Variable name (e.g., `DATABASE_URL`) | | Required | Present in code references or marked required in example | | Type hint | Inferred from usage (URL, integer, boolean, string, path) | | Default | Value in `.env.example` if present | | Used in | List of files that reference this variable |

Phase 3: Validation

Run these checks against the primary `.env` file:

1. **Missing required variables** (CRITICAL)

• Variable referenced in code but absent from `.env`
• Variable in `.env.example` without a default but absent from `.env`

2. **Type mismatches** (HIGH)

• `PORT=abc` when code does `int(os.environ["PORT"])`
• `DEBUG=yes` when code expects boolean (`true`/`false`)
• URL variables without valid URL format

3. **Insecure defaults** (HIGH)

• `SECRET_KEY=changeme`, `PASSWORD=password`, `API_KEY=xxx`
• `DEBUG=true` or `DEBUG=1` in production-targeted files
• Empty values for security-critical variables

4. **Unreferenced variables** (MEDIUM)

• Variables in `.env` not referenced anywhere in code or manifests
• May indicate stale configuration

5. **Format issues** (LOW)

• Lines without `KEY=VALUE` format
• Trailing whitespace in values
• Inconsistent quoting (mixing single/double/no quotes)
• Duplicate variable definitions (last wins, but likely a mistake)

See `references/validation-rules.md` for the complete rule catalog.

Phase 4: Report

Produce a structured validation report:

# Environment Validation Report

**File:** `.env`
**Schema:** `.env.example` + code references
**Verdict:** PASS | FAIL

## Summary

| Severity | Count |
|----------|-------|
| CRITICAL | N     |
| HIGH     | N     |
| MEDIUM   | N     |
| LOW      | N     |

## CRITICAL

### [ENV-001] Missing required variable: DATABASE_URL

- **Referenced in:** `src/db.py:12`, `docker-compose.yml:8`
- **Expected type:** URL (postgresql://...)
- **Fix:** Add `DATABASE_URL=postgresql://user:pass@localhost:5432/dbname` to `.env`

## HIGH

...

## Unreferenced Variables

| Variable        | In .env | In Code | In Manifests | Status       |
|-----------------|---------|---------|--------------|--------------|
| LEGACY_API_KEY  | Yes     | No      | No           | Unreferenced |

## Recommendations

1. [Highest priority fix]
2. [Second fix]

Error Handling

| Error | Resolution | | --------------------------------- | ----------------------------------------------------- | | No .env file found | Report absence; check for alternative env sources | | No .env.example or schema | Validate based on code references only | | Binary or very large .env | Skip; report as unsupported format | | No code references found | Validate format and security only; skip completeness |

Limitations

• Cannot validate runtime-injected variables (from vault, AWS SSM, etc.)
• Type inference is heuristic — may misclassify complex values
• Does not check variable values against external services (e.g., valid API key format)
• Production vs. development distinction requires file naming conventions