secret-detection

Secret Detection

Rules (for AI agents)

ALWAYS

• On finding a committed credential, rotate or revoke it at the provider first. Deleting the line does not remediate it, and neither does git rm, an amended commit, or a history rewrite: the value reached a remote, a clone, a fork, a CI log and a backup, and it is compromised from the moment it was pushed. Rotate, then clean the history, then add the guard that stops it recurring — in that order, because only the first one is time-critical.
• Run a scanner; do not scan by eye. scan_secrets and check_secret_pattern carry the full pattern set with per-pattern entropy floors and hotword proximity, and a person reading a diff matches none of that reliably. A working-tree scan and a history scan answer different questions — the first says what you are about to commit, the second says what is already public.
• Read the credential from the environment or a secret manager at the point of use — os.environ, process.env, os.Getenv, a Vault / AWS Secrets Manager / GCP Secret Manager / 1Password client. Nothing about the value should be reconstructible from the repository.
• Ship a .env.example that is committed and contains every key with an empty or obviously-fake value, alongside a .env that is ignored and never committed. The example file is documentation, so it must never be produced by copying a working .env and editing it — that is how a real value survives into the template.
• Ignore the file classes that carry key material, in one list: .env, .env.* (but not .env.example), *.pem, *.key, *.p12, *.pfx, *.ppk, id_rsa*, id_dsa*, id_ecdsa*, id_ed25519*, *credentials*, *secret*. A .gitignore entry is a guard against habit, not a control — it does nothing for a file already tracked, and git add -f overrides it.
• Treat every client-reachable config value as public: a shipped bundle, a /config endpoint, Firebase Remote Config, a feature-flag payload, a mobile app's build-time constants. A client may hold public identifiers and nothing else.
• Prefer credentials that expire and are scoped. A short-lived, narrowly-scoped token bounds what a leak costs, and it is the only control that still helps after every other one has failed — which, given the rule above about rotation, is the case worth designing for.