netrun-env 2.1.0

Schema-based environment variable validator with security checks

Netrun Environment Validator (Service #69)

Schema-based environment variable validator with comprehensive security checks for .env files across development, staging, and production environments.

Features

• Schema-Based Validation: Generate and validate against JSON schemas
• Security Enforcement:
  • Minimum secret length requirements (32 chars)
  • JWT algorithm whitelisting (RS256/RS384/RS512/ES256 only)
  • HTTPS enforcement in production/staging
  • Secret strength validation
  • Placeholder detection
• Type Inference: Automatic detection of URLs, emails, integers, booleans, secrets
• Environment Comparison: Diff two environment files with secret masking
• CLI Interface: Simple command-line tool for all operations

Installation

# Install from source
cd Service_69_Unified_Env_Validator
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"

Quick Start

1. Generate Schema from Example

# Generate schema from .env.example
netrun-env generate-schema --from .env.example --out .env.schema.json

Example .env.example:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
DATABASE_POOL_SIZE=10

# Security
JWT_SECRET_KEY=[SECRET_KEY_HERE]
JWT_ALGORITHM=RS256

# API
API_BASE_URL=https://api.example.com
API_TIMEOUT=30
DEBUG=false

Generated schema (.env.schema.json):

{
  "$schema": "https://netrunsystems.com/env-schema/v1",
  "version": "1.0",
  "variables": {
    "DATABASE_URL": {
      "type": "url",
      "required": true,
      "protocols": ["postgresql", "postgresql+asyncpg"],
      "example": "postgresql://user:password@localhost:5432/dbname"
    },
    "JWT_SECRET_KEY": {
      "type": "secret",
      "required": true,
      "minLength": 32,
      "example": "[SECRET_VALUE]"
    },
    "JWT_ALGORITHM": {
      "type": "string",
      "required": true,
      "example": "RS256"
    }
  }
}

2. Validate Environment

# Validate .env against schema
netrun-env validate --env .env --schema .env.schema.json

# Validate with specific security level
netrun-env validate --env .env.production --security-level production

# Strict mode (treat warnings as errors)
netrun-env validate --env .env --schema .env.schema.json --strict

Example validation output:

Validating: .env
✓ Validation passed

Warnings (1):
  - Secret 'JWT_SECRET_KEY' appears to contain a placeholder value

3. Compare Environments

# Compare staging vs production
netrun-env diff --env1 .env.staging --env2 .env.production

# JSON output format
netrun-env diff --env1 .env.example --env2 .env --format json

# Show unmasked secrets (use with caution)
netrun-env diff --env1 .env.staging --env2 .env.production --no-mask

# Fail if differences found (useful in CI)
netrun-env diff --env1 .env.example --env2 .env --fail-on-diff

Example diff output:

Environment Comparison Report
============================================================
Baseline: .env.staging
Target:   .env.production
============================================================

Missing in target (1):
  - DEBUG_MODE

Added in target (1):
  + SENTRY_DSN

Changed values (2):
  ~ DATABASE_URL
      - postgresql://localhost:5432/staging
      + postgresql://production-db:5432/prod
  ~ JWT_SECRET_KEY
      - ab...yz
      + xy...ba

Security Features

Secret Strength Validation

# This will FAIL validation
JWT_SECRET_KEY=short

# Error: Secret 'JWT_SECRET_KEY' must be at least 32 characters (current: 5 characters)

JWT Algorithm Whitelisting

# This will FAIL validation
JWT_ALGORITHM=HS256

# Error: Forbidden JWT algorithm 'HS256'. Use asymmetric algorithms: ES256, ES384, ES512, RS256, RS384, RS512

HTTPS Enforcement

# In production/staging, this will FAIL
API_URL=http://api.example.com

# Error: URL 'API_URL' must use HTTPS in production

Placeholder Detection

# This will generate a WARNING
DATABASE_PASSWORD=[PASSWORD_HERE]

# Warning: Secret 'DATABASE_PASSWORD' appears to contain a placeholder value

Schema Format

Schemas are JSON files with the following structure:

{
  "$schema": "https://netrunsystems.com/env-schema/v1",
  "version": "1.0",
  "variables": {
    "VARIABLE_NAME": {
      "type": "string|integer|boolean|url|secret|email|path",
      "required": true|false,
      "minLength": 32,
      "min": 0,
      "max": 100,
      "protocols": ["https"],
      "allowed_values": ["true", "false"],
      "example": "example_value"
    }
  }
}

Supported Types

• string: Generic string value
• integer: Numeric value (validated as integer)
• boolean: Boolean value (true/false/yes/no/1/0)
• url: URL with protocol validation
• secret: Sensitive value with minimum length requirement
• email: Email address with format validation
• path: File system path

CI/CD Integration

GitHub Actions Example

name: Environment Validation

on: [push, pull_request]

jobs:
  validate-env:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install netrun-env
        run: pip install netrun-env

      - name: Validate environment schema
        run: |
          netrun-env validate \
            --env .env.example \
            --schema .env.schema.json \
            --security-level staging

      - name: Check environment differences
        run: |
          netrun-env diff \
            --env1 .env.example \
            --env2 .env.production.example \
            --fail-on-diff

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: validate-env
        name: Validate .env files
        entry: netrun-env validate --env .env.example --schema .env.schema.json
        language: system
        files: '\.env.*'

Development

Setup Development Environment

# Clone repository
git clone https://github.com/netrunsystems/netrun-service-library
cd Netrun_Service_Library_v2/Service_69_Unified_Env_Validator

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

Run Tests

# Run all tests with coverage
pytest

# Run specific test file
pytest tests/test_validator.py

# Run with verbose output
pytest -v

# Generate HTML coverage report
pytest --cov-report=html
open htmlcov/index.html

Code Quality

# Format code with black
black netrun_env tests

# Lint with ruff
ruff netrun_env tests

# Type check with mypy
mypy netrun_env

API Usage

You can also use netrun-env as a Python library:

from netrun_env import EnvValidator, SchemaGenerator, EnvDiff
from netrun_env.security import SecurityLevel
from pathlib import Path

# Generate schema
generator = SchemaGenerator()
schema = generator.generate_schema(Path(".env.example"))
generator.save_schema(schema, Path(".env.schema.json"))

# Validate environment
validator = EnvValidator(security_level=SecurityLevel.PRODUCTION)
result = validator.validate_file(Path(".env"), Path(".env.schema.json"))

if result.is_valid:
    print("✓ Validation passed")
else:
    print("✗ Validation failed")
    for error in result.errors:
        print(f"  - {error}")

# Compare environments
differ = EnvDiff(mask_secrets=True)
diff = differ.compare_files(Path(".env.staging"), Path(".env.production"))
print(diff)

Configuration

Security Levels

• development: Most permissive (allows HTTP, relaxed secret requirements)
• staging: Moderate (requires HTTPS, enforces secret length)
• production: Strictest (requires HTTPS, enforces all security rules)

Secret Detection Patterns

Variables matching these patterns are treated as secrets:

• *_SECRET*
• *_KEY
• *_TOKEN
• *_PASSWORD
• *_CREDENTIAL*
• *_API_KEY

Allowed JWT Algorithms

Production environments only allow asymmetric algorithms:

• RS256, RS384, RS512 (RSA)
• ES256, ES384, ES512 (ECDSA)

Forbidden: HS256, HS384, HS512, none

License

MIT License - Copyright (c) 2025 Netrun Systems

Support

• Website: https://netrunsystems.com
• Email: [e-mail]
• Issues: https://github.com/netrunsystems/netrun-service-library/issues

Related Services

• Service #61: Unified Logging Service
• Service #54: Meridian Distributed Tracing
• Service #29: Secrets Management Service

---

Version: 1.0.0 Created: November 2025 Author: Netrun Systems Part of: Netrun Service Library v2