jacob-balslev Secrets Management
Concept of the skill
A secret is any value that grants access or trust: an API key, a database password, an OAuth client secret, a session-signing key, a TLS private key, an encryption key, a webhook signing secret. Secrets management is the discipline of governing each secret's entire lifecycle — generation, storage, distribution, use, rotation, revocation, and audit — so the value never lands anywhere it can be read by the wrong party.
The single hardest truth: a secret in source code is compromised the moment it is pushed. Even if you delete it in the next commit, it lives in the repository's history, in every clone, in CI caches, and possibly in a fork. Treat a committed credential as already leaked — rotate it, do not just remove it.
Coverage
- What is a secret vs ordinary config — the line is "does this value grant access or trust?"
- The lifecycle: generation (strong, random) → storage (encrypted, centralized) → distribution (scoped, just-in-time) → use → rotation → revocation → audit.
- Never hardcode — secrets do not belong in source, config files in the repo, container images, or front-end bundles.
- Externalize the value into a dedicated secrets manager / vault / KMS; the code holds a reference, not the value.
- Encryption at rest and in transit; envelope encryption with a KMS-held master key.
- Least privilege — each consumer holds only the secrets it needs, scoped as narrowly as possible.
- Short-lived over long-lived — prefer dynamically-issued, auto-expiring credentials to static ones.
- Workload identity — OIDC token exchange, SPIFFE/SVID, cloud instance identity — to eliminate standing credentials entirely.
- Rotation on a schedule and revocation on compromise.
- Environment-variable and .env pitfalls — process/log/crash-dump leakage; plaintext-in-git-history.
- Secret scanning in commits and CI; leak detection.
- Leak response — blast-radius containment and the rotate-everything playbook.
- Audit logging — who accessed which secret, when.
Philosophy of the skill
Assume every secret will eventually leak, and design so that leak is survivable. This single assumption drives every practice: short lifetimes mean a leaked credential is near-expiry; least privilege means a leaked credential is narrow; rotation means a leaked credential is soon-invalid; audit logging means you can tell what a leaked credential touched. A secrets program is not judged by whether a leak ever happens — it is judged by how contained and detectable a leak is when it does.
The best secret is one that does not exist as a standing value. A long-lived static API key is the worst case: broad, durable, and hard to rotate. A short-lived credential minted on demand for a specific workload via OIDC/SPIFFE is the best case: there is no standing secret to steal. Move toward "no standing credentials" wherever the platform allows it.
The secret lifecycle
generate ─► store (encrypted, central) ─► distribute (scoped, JIT) ─► use
│
audit ◄── revoke (on compromise) ◄── rotate (scheduled)
Each stage has a failure mode: weak generation (guessable), plaintext storage (readable), over-broad distribution (one leak compromises everything), no rotation (a stolen credential is valid forever), no revocation (you can't stop a known-compromised credential), no audit (you can't tell what a leaked credential accessed).
Never hardcode — and what "externalize" really means
Externalizing a secret means the value moves out of code into a managed store; the code holds only a reference (a key name the runtime resolves against the vault). Putting the value in a .env file is a half-measure that is acceptable only for local development with non-production credentials — and .env must be git-ignored. A production secret belongs in a secrets manager the runtime reads via a scoped, audited request, ideally exchanging a workload identity for a short-lived lease.
Least privilege and scoping
Do not mint one admin credential and share it everywhere. Each service, job, or environment gets its own credential scoped to exactly what it needs (this database, read-only; this bucket, this prefix). When a narrowly-scoped credential leaks, the blast radius is one capability, not the whole estate.
Short-lived over long-lived
A static secret that never changes is a permanent liability. Prefer credentials that are dynamically issued and auto-expiring: a vault mints a database credential valid for an hour and revokes it automatically; a CI job exchanges an OIDC token for a cloud session that lasts only the run. Short lifetimes turn "rotate everything" from a crisis into the normal steady state.
Rotation and revocation
Rotation replaces a secret on a schedule (or after a suspected exposure) so no credential is valid indefinitely; rotation must be possible without downtime (overlapping validity windows). Revocation is the emergency lever — invalidate a known-compromised credential immediately. A secrets program without a tested rotation and revocation path is not production-ready: you will not be able to respond to a leak.
The environment-variable trap
Environment variables are not a security boundary. They are visible to the whole process and inherited by child processes, they leak into logs and crash/error reports, and a process listing or debug dump can expose them. They are a reasonable transport for a secret a managed runtime injects just-in-time — but treating "it's in an env var" as "it's secure" is the most common misconception in this domain.
Detection: secret scanning
Scan commits and CI for accidentally-committed secrets (high-entropy strings, known key formats). Catching a leak at commit time is vastly cheaper than after it ships. Pair pre-commit scanning with provider-side push protection and periodic history scans.
Leak response
When a secret leaks (committed, logged, screenshotted), the response is rotate, do not just delete:
- Rotate the leaked credential immediately — the old value is compromised regardless of whether you remove it from the repo.
- Revoke the old value so it cannot be used.
- Audit what the leaked credential could and did access (blast radius).
- Contain — if it was broadly scoped, assume everything it could reach is suspect.
- Prevent recurrence — add scanning, narrow the scope, shorten the lifetime.
Removing the secret from the latest commit does nothing: it is still in history and already copied.
Verification
A secrets posture is sound when you can answer yes to:
- Are there zero secrets in source, repo config, images, or front-end bundles? (run a scan to prove it)
- Is every production secret stored encrypted in a managed store, referenced — not embedded — by code?
- Is each credential scoped to least privilege, not a shared admin key?
- Are credentials short-lived (dynamic/auto-expiring) wherever the platform allows, or at least on a tested rotation schedule?
- Is there a tested revocation path for an emergency?
- Is secret access audited?
- Is there a written leak-response playbook that starts with "rotate," not "delete"?
If any answer is no, name the gap before calling the system secure.
Do NOT Use When
- The task is designing the authentication protocol (session/token/OAuth flow) — that is an auth-patterns concern, not the credential lifecycle.
- The task is the authorization model (RBAC/ABAC/RLS — what an identity may do) — out of scope; this skill governs the secret value, not the permission policy.
- The task is cryptographic-primitive design (which cipher, mode, or KDF to implement) — that is a cryptography concern; here we use KMS/encryption, we don't design the algorithm.
- The task is the CI pipeline orchestration itself — that is
ci-cd-pipelines; this skill owns only the secret/credential slice it consumes. - The value is ordinary non-sensitive configuration — that is general config management, not secrets.
References
- OWASP Secrets Management Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
- CWE-798 Use of Hard-coded Credentials: https://cwe.mitre.org/data/definitions/798.html
- Twelve-Factor — Config: https://12factor.net/config
- NIST SP 800-57 Part 1 (Key Management): https://csrc.nist.gov/pubs/sp/800/57/pt1/r5/final
- HashiCorp Vault — Dynamic Secrets: https://developer.hashicorp.com/vault/docs/concepts/dynamic-secrets
- SPIFFE — Workload Identity: https://spiffe.io/docs/latest/spiffe-about/overview/
- OWASP Top 10 A07 (Identification & Authentication Failures): https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures/