# Secrets Lifecycle

> Secrets are born (generated), distributed (delivered to consumers), rotated (replaced on
> schedule), and die (revoked and destroyed) -- manage every phase or the secret manages you

## When to Use

- Designing how an application retrieves database credentials, API keys, or encryption keys
- Establishing a secret rotation policy for a production system
- Responding to a secret exposure (leaked in logs, committed to Git, visible in error
  messages)
- Choosing between static secrets, dynamic secrets, and short-lived tokens
- Auditing an existing system for secret management gaps
- Evaluating secrets managers (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager)

## Threat Context

Exposed secrets are the most common initial access vector in cloud breaches. The attack
surface is vast and the consequences are immediate:

- **GitHub secret exposure scale**: GitHub's 2023 secret scanning report found 12+ million
  secrets exposed in public repositories in a single year. Automated bots scan every public
  commit within seconds of push -- the median time from commit to attacker exploitation of
  an exposed AWS key is under 1 minute.
- **Uber breach (2022)**: Began with hardcoded credentials discovered in a PowerShell script
  on an internal network share. The attacker used these credentials to access Uber's AWS,
  GCP, and internal Slack environments.
- **CircleCI breach (2023)**: Attackers compromised CircleCI's secrets management
  infrastructure itself, exposing customer secrets stored in the platform. This demonstrates
  that even the secrets manager is a high-value target.
- **Codecov supply chain attack (2021)**: Attackers modified a bash uploader script to
  exfiltrate environment variables (containing secrets) from CI/CD environments to an
  attacker-controlled server.

Secrets have a lifecycle -- generation, distribution, usage, rotation, and revocation -- and
failure at any single phase is a breach waiting to happen. A secret that is generated
securely but never rotated accumulates exposure risk over time. A secret that is rotated
regularly but distributed through insecure channels is exposed at every rotation.

## Instructions

1. **Generate secrets with sufficient entropy.** API keys, tokens, and passwords must
   contain minimum 256 bits of randomness from a cryptographically secure pseudorandom
   number generator (CSPRNG). Use `crypto.randomBytes(32)` in Node.js,
   `secrets.token_hex(32)` in Python, `SecureRandom` in Java, or `/dev/urandom` on Unix.
   Database passwords should be 32+ random characters (letters, digits, symbols). Encryption
   keys must be generated using the crypto library's dedicated key generation function, not
   by hashing a passphrase (unless using a proper KDF like Argon2id with appropriate
   parameters -- see `security-credential-storage`).

2. **Distribute secrets through a secrets manager, never through code or config files.** Use
   HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, or Kubernetes
   Secrets (with envelope encryption via a KMS). Applications retrieve secrets at startup or
   on-demand via authenticated API calls to the secrets manager. The application
   authenticates to the secrets manager using platform identity (IAM roles, Kubernetes
   service accounts, Vault AppRole) -- not with another static secret. Secrets must never be
   committed to version control, embedded in Docker images, passed as build arguments, or
   included in deployment manifests.

3. **Use dynamic secrets when possible.** Instead of a static database password that lives
   forever, use Vault's database secrets engine (or equivalent) to generate short-lived
   credentials with a TTL of 1 hour per application instance. When the TTL expires, the
   credential is automatically revoked at the database level. This eliminates long-lived
   secrets entirely -- there is nothing to rotate because every credential is born with a
   death date. Dynamic secrets are available for databases (PostgreSQL, MySQL, MongoDB),
   cloud providers (AWS STS, GCP service account keys), and PKI certificates.

4. **Rotate static secrets on a mandatory schedule.** When dynamic secrets are not feasible,
   static secrets must be rotated periodically: 90 days maximum for high-sensitivity secrets
   (database root credentials, encryption keys, signing keys), 365 days for low-sensitivity
   secrets (monitoring API keys). Implement dual-read rotation to avoid downtime:
   (a) generate new secret B while secret A is still active, (b) configure all consumers to
   accept both A and B, (c) switch producers to emit B, (d) verify via audit logs that no
   traffic uses A, (e) revoke A. Automate this process -- manual rotation is forgotten
   rotation.

5. **Revoke secrets immediately upon any exposure.** If a secret appears in a log file,
   error message, Git commit, Slack message, support ticket, or any unintended location,
   treat it as compromised. Do not assess whether "anyone noticed" -- assume the worst.
   Revocation procedure: (a) revoke the secret at the source (delete the API key, change the
   password, rotate the certificate), (b) generate a new secret and distribute it through
   the secrets manager, (c) audit access logs from the moment of exposure to determine if
   the secret was exploited, (d) investigate and fix the root cause of the exposure, (e) add
   detection to prevent recurrence (pre-commit hooks, log scrubbing).

6. **Audit all secret access.** The secrets manager must log every access event: who
   requested the secret, when, from which IP/service, and whether the request was granted or
   denied. Configure alerts for anomalies: access from unknown IP ranges, access frequency
   spikes, access to secrets outside the caller's normal pattern, and any access to
   high-sensitivity secrets (root credentials, encryption keys). Audit logs from the secrets
   manager are themselves sensitive and must be stored in a tamper-evident,
   access-controlled location (see `security-audit-log-design`).

7. **Scope secrets to minimum blast radius.** Each service or application instance should
   have its own credentials. Do not share a single database password across 10
   microservices -- if one service is compromised, the attacker has access to the database
   with the privileges of all 10 services. Service-specific credentials enable targeted
   revocation: revoke the compromised service's credentials without disrupting the other 9.
   Apply the principle of least privilege to secret scope: a service that only reads from the
   database should have read-only credentials, not read-write.

## Details

- **The secret exposure cascade**: A leaked AWS access key committed to a public GitHub
  repository triggers a predictable cascade. Automated bots (scanning every public commit
  via GitHub's Events API) detect the key within seconds. The attacker uses the key to call
  `sts:GetCallerIdentity` to identify the account, then `iam:ListUsers`,
  `s3:ListBuckets`, and `ec2:DescribeInstances` to enumerate resources. Data is exfiltrated
  from S3 buckets. EC2 instances are launched for cryptomining. The entire cascade can
  complete within 10 minutes of the commit. Response must be: (1) revoke the key immediately
  via `aws iam delete-access-key`, (2) audit CloudTrail for all API calls made with the key
  since the commit timestamp, (3) rotate all credentials the leaked key could access,
  (4) check for persistence mechanisms the attacker may have installed (new IAM users,
  Lambda functions, EC2 instances), (5) add pre-commit hooks (truffleHog, git-secrets,
  gitleaks) and enable GitHub push protection to prevent recurrence.

- **Dual-read rotation pattern in practice**: Step 1: Generate new database password B.
  Step 2: Execute `ALTER USER app_user SET PASSWORD = B` but also keep A valid (PostgreSQL
  allows this via connection pooler configuration or multiple valid passwords in some
  setups; alternatively, create a new database user with B and grant identical permissions).
  Step 3: Update the secrets manager to serve B. Step 4: Applications pick up B on their
  next secret refresh (within the refresh interval, typically 5-15 minutes). Step 5: Monitor
  audit logs to confirm no connections use A. Step 6: Revoke A (drop the old user or change
  the password). The critical principle: there must never be a moment when neither A nor B
  is valid.

- **Short-lived tokens vs static secrets -- a hierarchy of preference**: Prefer (from best
  to worst): (1) Dynamic secrets with automatic TTL and revocation (Vault database secrets
  engine, AWS STS temporary credentials), (2) OAuth2 access tokens with 1-hour TTL and
  refresh tokens, (3) Platform-managed rotating credentials (AWS RDS IAM authentication,
  GCP Cloud SQL IAM authentication), (4) Static secrets with automated rotation on a 90-day
  schedule, (5) Static secrets with manual rotation (worst case, requires process
  discipline). Each level down the hierarchy increases the window of opportunity for a
  compromised credential.

- **Pre-commit secret scanning**: Tools: truffleHog (entropy-based and regex-based
  detection), git-secrets (AWS-focused patterns), gitleaks (broad pattern library), GitHub's
  built-in push protection (blocks pushes containing known secret formats for supported
  providers). Configure as both a local pre-commit hook (catches secrets before they reach
  the remote) and a CI check (catches secrets that bypass local hooks). Block commits
  containing high-entropy strings matching known secret patterns: AWS keys (prefix `AKIA`),
  GitHub tokens (`ghp_`, `gho_`, `ghs_`), Slack tokens (`xoxb-`, `xoxp-`), private keys
  (`-----BEGIN RSA PRIVATE KEY-----`). Maintain an allowlist for false positives (test
  fixtures, documentation examples with dummy values).

## Anti-Patterns

1. **Secrets in source code or version control.** Once committed, a secret persists in Git
   history even after deletion from HEAD. Every clone of the repository contains the secret
   in its history. Removing it requires `git filter-repo` or BFG Repo Cleaner to rewrite
   history, followed by force-pushing -- and even then, any existing clone or fork retains
   the secret. Always treat a committed secret as compromised regardless of how quickly it
   was removed.

2. **Shared credentials across services and environments.** Production and staging sharing
   the same database password. Multiple microservices using the same API key. A single
   "admin" password for all team members. Compromise of any one consumer compromises all
   consumers. Incident response requires rotating the shared credential and redeploying
   every consumer simultaneously -- an operational nightmare that delays response.

3. **Never-rotated secrets.** A database password created in 2019 and never rotated has had
   5+ years of potential exposure windows: developer laptops, CI/CD logs, backup tapes,
   departed employees' password managers. The longer a secret lives, the more opportunities
   for undetected exposure. Establish rotation schedules, automate them, and alert on
   overdue rotations.

4. **Secrets in environment variables without a secrets manager.** Environment variables are
   visible in process listings (`/proc/PID/environ` on Linux), crash dumps, debugging tools
   (`docker inspect`), container orchestration dashboards, and CI/CD build logs. They are
   better than hardcoding in source but far worse than a proper secrets manager. Use a
   secrets manager to inject secrets directly into the application's memory at startup,
   bypassing the environment entirely.

5. **Logging secrets accidentally.** Application logs that include full HTTP request/response
   bodies (containing Authorization headers or API keys), error messages that dump
   configuration objects (containing database connection strings), and debug logging that
   prints environment variables. Implement structured logging with explicit field selection
   (log only what you intend), add log scrubbing for known secret patterns, and never log
   request bodies containing authentication credentials.

6. **Secrets in CI/CD pipeline definitions.** Storing secrets as plaintext variables in
   GitHub Actions workflow files, Jenkins pipeline scripts, or GitLab CI YAML. Use the CI
   platform's encrypted secrets feature (GitHub Actions secrets, GitLab CI/CD variables
   marked as "masked" and "protected") and ensure secrets are not echoed in build logs.

7. **Using the same secret for authentication and encryption.** An API key used for both
   authenticating to a service and encrypting data at rest. If the authentication use case
   exposes the key (via logs, network capture), the encryption is also compromised. Use
   separate secrets for separate purposes -- key separation is a fundamental cryptographic
   principle.