mathews-tom/armory/env-validator

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

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:

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

1. 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

1. 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

1. Unreferenced variables (MEDIUM)

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

1. 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

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