secret-management

name	secret-management
description	Secret management — env vars, vaults, rotation, no secrets in code.

Never-Do Table

Anti-pattern	Why it's dangerous
Hardcode secrets in source code	Committed to git history; visible to anyone with repo access
Commit .env files with real values	Permanent exposure even after deletion (git history)
Log secrets (even partially)	Log aggregators, third-party services, and crash reports may store them
Use the same secret across environments	Dev breach compromises production
Pass secrets as CLI arguments	Visible in process list (ps aux), shell history
Store in environment variables of public CI runs	Forked PR pipelines can exfiltrate them

---

Detecting Secrets Already in Git History

# Scan full history for common secret patterns
git log --all -S "sk-" --oneline          # OpenAI keys
git log --all -S "AKIA" --oneline         # AWS access keys
git log --all -S "ghp_" --oneline         # GitHub tokens
git log --all -S "password" --oneline     # Generic passwords

# Use trufflehog for deeper scanning
trufflehog git file://. --only-verified

# Use gitleaks
gitleaks detect --source . --log-level warn

If a secret is found in history: rotate it immediately, then use git filter-repo or BFG to purge — but assume the secret is already compromised.

---

Vault Options

Tool	When to use
HashiCorp Vault	Self-hosted; complex access policies; dynamic secrets; multi-cloud
AWS Secrets Manager	AWS-native workloads; built-in rotation for RDS/Redshift/DocumentDB
GCP Secret Manager	GCP-native workloads; IAM-controlled access; regional replication
Azure Key Vault	Azure-native workloads; HSM-backed secrets; certificate management
Doppler / Infisical	SaaS option; easy local dev sync; team-friendly; multi-cloud
1Password Secrets Automation	Teams already using 1Password; low operational overhead

Prefer managed services (AWS/GCP/Azure) when already in that cloud — less infra to maintain and automatic audit trails.

---

Rotation Policy

Secret Type	Rotation Frequency	Rotate Immediately If
Application secrets (JWT, API keys)	Every 90 days	Suspected exposure or team member offboarding
Database credentials	Every 90 days	Developer leaves or breach suspected
Infrastructure credentials (cloud IAM)	Every 30 days	Any security incident
Service-to-service tokens	Every 30 days	Service is decommissioned
Human user passwords	Every 180 days	Phishing, breach notification, or MFA reset

Rotate immediately on any confirmed or suspected exposure — do not wait for the scheduled cycle.

---

Environment Variable Rules

• .env — real values, never committed; add to .gitignore
• .env.example — template with placeholder values, always committed
• .env.test — test-only values (no production secrets); can be committed if values are non-sensitive stubs
• CI/CD — use the platform secret store (GitHub Actions secrets, GitLab CI variables, Doppler integration)

.gitignore minimum:

.env
.env.local
.env.*.local
*.pem
*.key
secrets/

Loading pattern (12-factor):

import os
from dotenv import load_dotenv  # dev only

load_dotenv()  # no-op in production where env vars come from the platform

DATABASE_URL = os.environ["DATABASE_URL"]  # fail fast if missing

---

Checklist

• No secrets in source code, config files, or SQL migrations
• .env is in .gitignore; .env.example is committed with placeholders
• CI/CD secrets stored in platform secret store, not in workflow files
• Rotation schedule documented and assigned
• Secret scanning (trufflehog/gitleaks) runs in pre-commit or CI