secrets-management

Secrets Management

Detect, rotate, and store secrets. A leaked secret is an incident: revoke first, clean history second, prevent third.

When to Use

• Suspected or confirmed leaked API key, token, or credential
• Choosing where a secret lives (env, manager, vault, CI secrets)
• Rotating keys on schedule or offboarding
• Reviewing code that handles secrets

Steps

1. Detect — scan with gitleaks; treat any hit as live until proven otherwise. Check history too (git log -S), not just HEAD.
2. Revoke first — rotate at the provider before cleaning the repo. A cleaned repo with a live leaked key is still an incident.
3. Clean — purge from history if needed; confirm with a rescan.
4. Store correctly — env vars or a secret manager; CI secrets for pipelines; never hardcoded, never in docs or chat logs.
5. Prevent — pre-commit hooks (gitleaks), least-privilege scopes, short TTLs, and rotation reminders.

Rules

• Never print a secret, even redacted-partially, into logs or PR comments.
• Never echo a secret value back, even if the user pasted it into the conversation or asks for a copy "for debugging". Offer the reference name (STRIPE_SECRET_KEY) or the command to fetch it instead.
• Never commit a "test" secret that resembles a real one.
• Separate secret values from secret references in every example.

Filenames Are Not the Boundary

A tool that reads or writes paths supplied by an agent needs one real control: containment. Resolve the path, then assert it is still inside the allowed base.

base = base.resolve()
candidate = (base / raw).resolve()
candidate.relative_to(base)   # raises => escapes the base => reject

That is default-deny and holds for every file format that exists tomorrow.

A credential-filename denylist (.pem, .tfvars, .sops.yml, .age, …) is a name policy layered on top of it. It only ever decides "which in-base names to also refuse", so it cannot be complete: each new keystore, VPN bundle, or secret-manager file format is another bypass nobody listed. Track such a list's history before trusting it — this template grew one over 36 separate commits and it is still appending.