Secrets Hygiene

Secrets Hygiene

When to use

• Preparing a commit, PR, patch, or shareable log/snippet.
• Editing .env examples, CI configs, Dockerfiles, Terraform, or Helm values.
• The user pastes credentials or asks to "wire up" a third-party API.

When not to use

• Discussing secret-management architecture at a pure design level with no files touched.
• Working exclusively with already-public, non-sensitive sample data clearly marked as fake.

Assumptions

• Access to git diff / git status and the working tree.
• Ability to search the repo for high-entropy strings and known secret patterns.
• Secret stores (GitHub Actions secrets, Vault, cloud SM) may exist — prefer them over files.
• Do not push, force-push, or amend shared history to "hide" a leaked secret without an explicit incident plan (rotation first).
• Do not print full live secrets into chat, logs, or PR bodies.

Workflow

1. Before staging, scan the diff and any new config files for secret-shaped values.
2. Move real secrets to the environment or a secret manager; keep only placeholders in git.
3. Ensure .gitignore / example env files cannot accidentally track real values.
4. If a secret may already be in history or a remote, stop and plan rotation + scrub with the user.
5. Proceed with commit/PR only when the diff is clean of credentials.

Steps

1. Diff scan — Review git diff and untracked files for keys named *SECRET*, *TOKEN*, *PASSWORD*, *_KEY, Authorization, PEM blocks, and connection strings with credentials.
2. Pattern check — Flag JWTs, AWS-like keys, private key headers (BEGIN … PRIVATE KEY), and long high-entropy literals in source.
3. Separate concerns — Real values → env / secret manager. Docs and examples → obviously fake placeholders (sk_test_…, REPLACE_ME).
4. Ignore rules — Confirm .env, key files, and local overrides are ignored; commit .env.example without real values only.
5. Output hygiene — Redact secrets in logs, screenshots, and PR text. Never echo printenv wholesale.
6. Leak response — If exposure is plausible: revoke/rotate first, then discuss history rewrite. Do not assume "delete the file" is enough.

Success criteria

• No live credentials, private keys, or password-bearing URLs appear in the staged diff.
• Examples use placeholders; real secrets live outside version control.
• .gitignore (or equivalent) covers local secret files.
• Suspected leaks triggered a rotation plan before further pushes.
• Chat/PR output does not contain full secret values.

Out of scope

• Implementing a full company-wide secrets platform.
• Cryptographic key ceremony design beyond basic hygiene.
• Legal/compliance attestation (SOC2 evidence packs).