envtool.py

#!/usr/bin/env python3
"""
envtool — .env file manager, validator, and secret detector.

Validate .env files, diff against .env.example, generate templates,
and detect accidentally committed secrets.

Usage:
    py envtool.py validate .env                    # Check for errors
    py envtool.py diff .env .env.example           # Find missing/extra vars
    py envtool.py template .env -o .env.example    # Generate template (strip values)
    py envtool.py secrets .env                     # Detect hardcoded secrets
    py envtool.py merge .env.defaults .env.local   # Merge (local overrides defaults)
"""

import argparse
import os
import re
import sys
from pathlib import Path
from collections import OrderedDict


# --- Secret Detection Patterns ---
SECRET_PATTERNS = [
    (r'^[A-Za-z0-9+/]{40,}={0,2}$', "Base64-encoded value (possible key)"),
    (r'^sk-[a-zA-Z0-9]{20,}$', "OpenAI API key"),
    (r'^sk-ant-[a-zA-Z0-9\-]{20,}$', "Anthropic API key"),
    (r'^ghp_[a-zA-Z0-9]{36}$', "GitHub personal access token"),
    (r'^gho_[a-zA-Z0-9]{36}$', "GitHub OAuth token"),
    (r'^glpat-[a-zA-Z0-9\-]{20,}$', "GitLab personal access token"),
    (r'^xox[bpras]-[a-zA-Z0-9\-]+$', "Slack token"),
    (r'^AKIA[0-9A-Z]{16}$', "AWS Access Key ID"),
    (r'^[0-9a-f]{32}$', "Possible MD5 hash or hex key"),
    (r'^eyJ[a-zA-Z0-9_\-]+\.eyJ[a-zA-Z0-9_\-]+', "JWT token"),
    (r'-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----', "Private key"),
    (r'^SG\.[a-zA-Z0-9_\-]{22}\.[a-zA-Z0-9_\-]{43}$', "SendGrid API key"),
    (r'^rk_live_[a-zA-Z0-9]{24,}$', "Stripe restricted key"),
    (r'^sk_live_[a-zA-Z0-9]{24,}$', "Stripe secret key"),
]

# Keys that typically hold secrets
SECRET_KEY_PATTERNS = [
    r'(?i)(password|passwd|pwd)',
    r'(?i)(secret|token|key|apikey|api_key)',
    r'(?i)(credential|auth)',
    r'(?i)(private)',
    r'(?i)(connection_string|conn_str|dsn)',
]

# Safe placeholder values
SAFE_PLACEHOLDERS = {
    "your-key-here", "changeme", "xxx", "todo", "replace-me",
    "placeholder", "your_api_key", "your-api-key", "CHANGE_ME",
    "INSERT_KEY_HERE", "your_secret_here", "example", "test",
    "", "null", "none", "undefined",
}


def parse_env(filepath: Path) -> tuple[OrderedDict, list[dict]]:
    """Parse .env file into ordered dict + list of issues."""
    env = OrderedDict()
    issues = []

    try:
        lines = filepath.read_text(encoding="utf-8").splitlines()
    except Exception as e:
        return env, [{"line": 0, "severity": "ERROR", "message": f"Cannot read file: {e}"}]

    for i, line in enumerate(lines, 1):
        stripped = line.strip()

        # Skip empty lines and comments
        if not stripped or stripped.startswith("#"):
            continue

        # Check for common errors
        if "=" not in stripped:
            issues.append({"line": i, "severity": "ERROR", "message": f"Missing '=' separator: {stripped[:50]}"})
            continue

        key, _, value = stripped.partition("=")
        key = key.strip()
        value = value.strip()

        # Validate key format
        if not re.match(r'^[A-Za-z_][A-Za-z0-9_]*$', key):
            issues.append({"line": i, "severity": "WARN", "message": f"Non-standard key format: '{key}'"})

        # Check for spaces in key
        if " " in key:
            issues.append({"line": i, "severity": "ERROR", "message": f"Space in key name: '{key}'"})

        # Check for duplicate keys
        if key in env:
            issues.append({"line": i, "severity": "WARN", "message": f"Duplicate key: '{key}' (overrides line {list(env.keys()).index(key) + 1})"})

        # Strip quotes from value
        if (value.startswith('"') and value.endswith('"')) or \
           (value.startswith("'") and value.endswith("'")):
            value = value[1:-1]

        # Check for unquoted values with spaces
        if " " in value and not (stripped.count('"') >= 2 or stripped.count("'") >= 2):
            issues.append({"line": i, "severity": "WARN", "message": f"Unquoted value with spaces: {key}={value[:30]}..."})

        # Check for trailing whitespace in value
        if value != value.rstrip():
            issues.append({"line": i, "severity": "INFO", "message": f"Trailing whitespace in value: '{key}'"})

        env[key] = value

    return env, issues


def detect_secrets(env: OrderedDict) -> list[dict]:
    """Detect values that look like real secrets (not placeholders)."""
    findings = []

    for key, value in env.items():
        if not value or value.lower() in SAFE_PLACEHOLDERS:
            continue

        # Check value against secret patterns
        for pattern, description in SECRET_PATTERNS:
            if re.match(pattern, value):
                findings.append({
                    "key": key,
                    "severity": "CRITICAL",
                    "message": f"Detected: {description}",
                    "value_preview": value[:8] + "..." + value[-4:] if len(value) > 16 else value[:8] + "...",
                })
                break

        # Check if key name suggests a secret and value looks real
        for key_pattern in SECRET_KEY_PATTERNS:
            if re.search(key_pattern, key):
                if len(value) > 8 and value.lower() not in SAFE_PLACEHOLDERS:
                    # Check it's not a common non-secret value
                    if not any(value.startswith(p) for p in ["http://", "https://", "localhost", "127.0.0.1", "true", "false"]):
                        findings.append({
                            "key": key,
                            "severity": "HIGH",
                            "message": f"Key '{key}' likely holds a secret",
                            "value_preview": value[:4] + "****" + value[-2:] if len(value) > 8 else "****",
                        })
                break

    return findings


def diff_envs(env1: OrderedDict, env2: OrderedDict, name1: str, name2: str) -> dict:
    """Compare two env files."""
    keys1 = set(env1.keys())
    keys2 = set(env2.keys())

    return {
        "only_in_first": sorted(keys1 - keys2),
        "only_in_second": sorted(keys2 - keys1),
        "in_both": sorted(keys1 & keys2),
        "value_differs": sorted(k for k in keys1 & keys2 if env1[k] != env2[k]),
        "name1": name1,
        "name2": name2,
    }


def generate_template(env: OrderedDict) -> str:
    """Generate .env.example template (keep keys, strip secret values)."""
    lines = []
    for key, value in env.items():
        # Determine if value should be kept or replaced
        is_secret = False
        for kp in SECRET_KEY_PATTERNS:
            if re.search(kp, key):
                is_secret = True
                break
        for sp, _ in SECRET_PATTERNS:
            if re.match(sp, value):
                is_secret = True
                break

        if is_secret:
            lines.append(f"{key}=your-{key.lower().replace('_', '-')}-here")
        elif value in ("true", "false", "0", "1"):
            lines.append(f"{key}={value}")
        elif value.startswith("http://") or value.startswith("https://"):
            lines.append(f"{key}={value}")
        elif value.isdigit():
            lines.append(f"{key}={value}")
        elif not value:
            lines.append(f"{key}=")
        else:
            lines.append(f"{key}={value}")

    return "\n".join(lines) + "\n"


def merge_envs(base: OrderedDict, override: OrderedDict) -> OrderedDict:
    """Merge two env files (override takes precedence)."""
    result = OrderedDict(base)
    result.update(override)
    return result


# --- Commands ---

def cmd_validate(args):
    env, issues = parse_env(Path(args.file))
    print(f"\n  .env Validation: {args.file}")
    print(f"  Variables: {len(env)}")
    print(f"  Issues: {len(issues)}")
    if issues:
        print()
        for issue in issues:
            print(f"  [{issue['severity']:>5}] Line {issue['line']}: {issue['message']}")
    else:
        print("  [ok] No issues found.")
    print()


def cmd_secrets(args):
    env, _ = parse_env(Path(args.file))
    findings = detect_secrets(env)
    print(f"\n  Secret Detection: {args.file}")
    print(f"  Variables scanned: {len(env)}")
    print(f"  Secrets detected: {len(findings)}")
    if findings:
        print()
        for f in findings:
            print(f"  [{f['severity']:>8}] {f['key']}: {f['message']}")
            print(f"            Preview: {f['value_preview']}")
        print(f"\n  WARNING: {len(findings)} potential secret(s) found.")
        print("  Do NOT commit this file. Add to .gitignore.")
    else:
        print("  [ok] No secrets detected.")
    print()


def cmd_diff(args):
    env1, _ = parse_env(Path(args.file1))
    env2, _ = parse_env(Path(args.file2))
    result = diff_envs(env1, env2, args.file1, args.file2)

    print(f"\n  .env Diff: {args.file1} vs {args.file2}")
    print(f"  Variables in {args.file1}: {len(env1)}")
    print(f"  Variables in {args.file2}: {len(env2)}")

    if result["only_in_first"]:
        print(f"\n  Only in {args.file1} ({len(result['only_in_first'])}):")
        for k in result["only_in_first"]:
            print(f"    + {k}")

    if result["only_in_second"]:
        print(f"\n  Only in {args.file2} ({len(result['only_in_second'])}):")
        for k in result["only_in_second"]:
            print(f"    - {k}")

    if result["value_differs"]:
        print(f"\n  Different values ({len(result['value_differs'])}):")
        for k in result["value_differs"]:
            print(f"    ~ {k}")

    if not any([result["only_in_first"], result["only_in_second"], result["value_differs"]]):
        print("\n  [ok] Files are equivalent.")
    print()


def cmd_template(args):
    env, _ = parse_env(Path(args.file))
    template = generate_template(env)

    if args.output:
        Path(args.output).write_text(template, encoding="utf-8")
        print(f"  Template written to {args.output} ({len(env)} variables)")
    else:
        print(template, end="")


def cmd_merge(args):
    base, _ = parse_env(Path(args.base))
    override, _ = parse_env(Path(args.override))
    merged = merge_envs(base, override)

    output = "\n".join(f"{k}={v}" for k, v in merged.items()) + "\n"
    if args.output:
        Path(args.output).write_text(output, encoding="utf-8")
        print(f"  Merged {len(base)} + {len(override)} = {len(merged)} variables -> {args.output}")
    else:
        print(output, end="")


def main():
    parser = argparse.ArgumentParser(description="envtool -- .env file manager, validator, and secret detector")
    sub = parser.add_subparsers(dest="command")

    # validate
    p = sub.add_parser("validate", help="Validate .env file for errors")
    p.add_argument("file", help=".env file to validate")

    # secrets
    p = sub.add_parser("secrets", help="Detect hardcoded secrets")
    p.add_argument("file", help=".env file to scan")

    # diff
    p = sub.add_parser("diff", help="Compare two .env files")
    p.add_argument("file1", help="First .env file")
    p.add_argument("file2", help="Second .env file")

    # template
    p = sub.add_parser("template", help="Generate .env.example from .env")
    p.add_argument("file", help=".env file to create template from")
    p.add_argument("-o", "--output", help="Output file (default: stdout)")

    # merge
    p = sub.add_parser("merge", help="Merge two .env files (second overrides first)")
    p.add_argument("base", help="Base .env file")
    p.add_argument("override", help="Override .env file")
    p.add_argument("-o", "--output", help="Output file (default: stdout)")

    args = parser.parse_args()
    commands = {
        "validate": cmd_validate,
        "secrets": cmd_secrets,
        "diff": cmd_diff,
        "template": cmd_template,
        "merge": cmd_merge,
    }

    if args.command in commands:
        commands[args.command](args)
    else:
        parser.print_help()


if __name__ == "__main__":
    main()