env-secrets-manager

---
name: env-secrets-manager
description: Use when auditing .env files for committed secrets, planning a credential rotation, debugging a missing-env-var production incident, or hardening a new project against secrets leakage.
category: Engineering
version: 1.0.0
tools: []
---

# Env & Secrets Manager

Manage environment-variable hygiene and secrets safety across local development and production — practical auditing, drift awareness, and rotation readiness for `.env` files, repository leaks, and production secret stores.

**Use when:** auditing `.env` files for committed secrets, planning a credential rotation, debugging a missing-env-var production incident, or hardening a new project against secrets leakage.

## Recommended workflow

Scan the repository (working tree and history) for likely secret leaks; prioritize `critical` and `high` findings first; rotate any real credentials found and remove the exposed values; update `.env.example` and `.gitignore`; then add or tighten pre-commit/CI secret-scanning gates so the same leak can't recur.

**Common pitfalls:** committing real values into `.env.example`; rotating one system but missing a downstream consumer of the same credential; logging secrets during debugging or incident response; treating a suspected leak as low urgency without validating it first.

**Best practices:** use a secret manager as the production source of truth, never `.env` files or baked-in environment variables; keep dev env files local and gitignored; enforce detection in CI before merge; re-test every dependent application path immediately after rotating a credential.

## Cloud secret store integration

Production applications should never read secrets from `.env` files or values baked into container images — use a dedicated secret store.

| Provider | Best for | Key feature |
|---|---|---|
| HashiCorp Vault | Multi-cloud / hybrid | Dynamic secrets, policy engine, pluggable backends |
| AWS Secrets Manager | AWS-native workloads | Native Lambda/ECS/EKS integration, automatic RDS rotation |
| Azure Key Vault | Azure-native workloads | Managed HSM, Azure AD RBAC, certificate management |
| GCP Secret Manager | GCP-native workloads | IAM-based access, automatic replication, versioning |

Single-cloud → use that cloud's native manager (tighter IAM integration, less operational overhead, cheaper than self-hosting). Multi-cloud/hybrid → HashiCorp Vault (uniform API, dynamic secrets — database credentials and cloud IAM keys that auto-expire). Kubernetes-heavy → pair the External Secrets Operator with any backend above to sync into K8s `Secret` objects without hardcoding.

Applications reach secrets via: SDK/API pull at startup or on-demand; sidecar injection (e.g. Vault Agent writing to a shared volume or env vars); a Kubernetes init container that fetches before the main container starts; or a CSI driver mounting secrets as a filesystem volume.

## Secret rotation

**Detection:** track creation/expiry metadata in the secret store; alert at 30, 14, and 7 days before expiry; flag any secret with no recorded rotation date.

**Rotation:** generate the new credential; deploy it to all consumers (apps, services, pipelines) in parallel; verify every consumer authenticates with the new credential; revoke the old one only once all consumers are confirmed healthy; record the new rotation timestamp and next due date.

**Automation:** AWS Secrets Manager's built-in Lambda-based rotation for RDS/Redshift/DocumentDB; HashiCorp Vault dynamic secrets with TTLs that auto-expire; Azure Key Vault via Event Grid-triggered rotation functions; GCP Secret Manager via Pub/Sub-triggered Cloud Functions.

**Emergency rotation** (confirmed leak): revoke the compromised credential immediately at the provider; deploy a replacement to all consumers; audit access logs for unauthorized use during the exposure window; scan git history, CI logs, and artifact registries for the leaked value; file an incident report with scope, timeline, and remediation; tighten detection controls to prevent recurrence.

## CI/CD secret injection

GitHub Actions: repository or environment secrets via `${{ secrets.NAME }}`; prefer OIDC federation (e.g. `aws-actions/configure-aws-credentials` with `role-to-assume`) over long-lived keys; environment secrets with required reviewers add an approval gate for production; GitHub masks secrets in logs automatically, but never `echo` or `toJSON()` a secret value.

GitLab CI: store as CI/CD variables with `masked` and `protected` flags; use Vault integration (`secrets:vault`) for dynamic injection without storing values in GitLab; scope variables per environment for least privilege.

Universal: never print secret values in pipeline output, even for debugging; prefer short-lived tokens (OIDC, STS AssumeRole) over static credentials; never expose secrets to pipelines triggered by forks or untrusted branches; rotate CI secrets on the same schedule as application secrets — pipeline credentials are attack vectors too; periodically audit pipeline logs for exposure that masking may have missed.

## Pre-commit secret detection

**gitleaks** — scans against a default ruleset extendable with custom regex rules (e.g. an internal token pattern); run as a pre-commit hook against staged changes, or as a full baseline scan over history; manage confirmed false positives in a shared `.gitleaksignore`.

**detect-secrets** — generates a baseline of currently-known findings, then a pre-commit hook fails only on *new* secrets not in that baseline; supports custom plugins for org-specific patterns; an interactive audit mode marks entries true/false positive.

Keep the ignore/baseline file in version control so exclusions are shared team-wide, and review it periodically — over time it can mask a real leak. Prefer tightening the detection regex over broadly ignoring a whole file.

## Audit logging

| Provider | Service | Captures |
|---|---|---|
| AWS | CloudTrail | Every `GetSecretValue`, `DescribeSecret`, `RotateSecret` call |
| Azure | Activity Log + Diagnostic Logs | Key Vault access events with caller identity and IP |
| GCP | Cloud Audit Logs | Secret Manager data-access events with principal and timestamp |
| Vault | Audit Backend | Full request/response logging (file, syslog, or socket) |

Alert on access from unknown IP ranges or unexpected service accounts; on bulk secret reads (more than N secrets in a window); on access outside deployment windows when no CI/CD pipeline is running. Feed audit logs into a SIEM for correlation, and review them quarterly as part of access recertification.