Secrets Manager

Secrets Manager

Overview

This skill governs the full lifecycle of secrets: keeping them out of source code, storing them in the right backend, injecting them at runtime, rotating them on schedule, and remediating leaks fast and completely. A leaked credential is an active incident — assume it is compromised the moment it touches a public surface.

Keywords: secret, credential, API key, token, password, .env, environment variable, vault, HashiCorp Vault, KMS, envelope encryption, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, SOPS, sealed-secrets, rotation, key rotation, git-secrets, gitleaks, trufflehog, pre-commit hook, scrub, BFG, git filter-repo, hardcoded credentials, dotenv, OIDC, workload identity, leaked key.

Workflow

1. Classify the request into one of four modes (see Decision Framework):

   • PREVENT — keep new secrets out of code.
   • STORE/INJECT — choose a backend and runtime delivery.
   • ROTATE — establish rotation cadence and automation.
   • REMEDIATE — a secret has already leaked.

2. If a secret may already be exposed, treat it as REMEDIATE first. Rotation/revocation precedes cleanup. Removing the secret from git does NOT un-leak it. Follow references/leak-remediation.md step by step.

3. Scan before you advise. Run scripts/scan_secrets.py over the repo (or recommend gitleaks/trufflehog for git history). Never assume the codebase is clean. Report findings with file, line, and a redacted match — never echo full secret values into logs, chat, or commits.

4. Pick a storage backend using the matrix in references/storage-backends.md. Match to the runtime (local dev, CI, Kubernetes, serverless, VM) and the org's existing cloud. Prefer short-lived, dynamically-issued credentials and OIDC/workload identity over long-lived static keys wherever possible.

5. Define injection. Secrets reach the process via environment variables, mounted files (tmpfs), or a fetch-at-startup SDK call — never baked into images, never committed. Use templates/dotenv-template.md for local dev and document .env in .gitignore.

6. Establish rotation. Set a cadence per secret class (see references/rotation-runbook.md), automate it where the backend supports it (Vault dynamic secrets, AWS Secrets Manager rotation Lambdas), and verify zero-downtime cutover with overlapping validity windows.

7. Add guardrails. Install a pre-commit hook (scripts/install_precommit.sh) and CI scanning so the next secret never lands. Verify .gitignore covers .env, *.pem, *.key, credential files.

8. Verify and document. Confirm no secret remains in working tree or history, rotation is scheduled, and access is least-privilege. Produce a short summary of what changed and what the human must still do (e.g., update the secret in the vault console).

Decision Framework

Backend selection quick guide

• Local dev: .env file (gitignored) loaded by dotenv, OR a developer vault like direnv + 1Password CLI / vault agent. Never commit .env.
• CI/CD: native masked secrets (GitHub Actions secrets/OIDC, GitLab CI variables) — prefer OIDC federation to a cloud role over storing static cloud keys.
• Cloud runtime (AWS/GCP/Azure): the cloud-native secret store + IAM/workload identity. Fetch at startup; cache in memory only.
• Kubernetes: External Secrets Operator or sealed-secrets/SOPS — avoid plain Secret objects checked into git (they are only base64, not encrypted).
• High-compliance / multi-cloud: HashiCorp Vault with dynamic secrets and short TTLs.

Worked Examples

See examples/remediate-leaked-aws-key.md for an end-to-end leak response: detection, revocation, history rewrite, and prevention.

Inline example — converting a hardcoded secret:

# BEFORE — hardcoded, will be flagged
STRIPE_KEY = "sk_live_PLACEHOLDER_EXAMPLE_KEY"

# AFTER — read from environment, fail loudly if absent
import os
STRIPE_KEY = os.environ["STRIPE_KEY"]  # set via vault/CI, never committed

Best Practices

• Treat any exposed secret as compromised. Rotate first; clean up second. Attackers scrape public repos within seconds.
• Prefer short-lived dynamic credentials (Vault dynamic secrets, STS, OIDC tokens) over long-lived static keys.
• Least privilege per secret. Scope tokens to the minimum API, resource, and TTL. One secret per service per environment.
• Never log or print secret values. Redact in logs, error messages, and tracebacks. The scanner output shows partial matches only.
• Encrypt at rest with KMS envelope encryption — the data key encrypts the secret, the KMS master key encrypts the data key; rotate the master key independently.
• Keep .env, *.pem, *.key, *.p12, credentials* out of git via .gitignore and enforce with a pre-commit hook.
• Automate rotation and alert on rotation failures; manual rotation drifts and gets skipped.
• Audit access. Enable access logging on the vault/KMS and review who/what read each secret.

Common Pitfalls

• Deleting the file but not rewriting history. The secret still lives in every prior commit and every clone/fork. Use git filter-repo or BFG, then force-push, then have collaborators re-clone.
• Rotating without revoking the old value. The leaked key keeps working until you revoke it at the provider.
• Committing Kubernetes Secret manifests. Base64 is encoding, not encryption — anyone can decode it. Use sealed-secrets/SOPS/External Secrets.
• Storing secrets in CI environment variable definitions in code (e.g., plaintext in a YAML pipeline). Use the platform's masked secret store.
• Baking secrets into Docker image layers via ENV or COPY .env. They persist in the image history. Inject at runtime instead.
• Using one shared key everywhere. A single leak then forces a fleet-wide rotation. Scope per service/environment.
• Trusting .gitignore alone. It does not untrack already-committed files and does not stop a git add -f. Pair it with scanning.
• Echoing the secret into chat or a summary while "helping." Redact always.