Secret Scanning skill for Codex

The only safe assumption about a committed secret is that it is compromised the moment it lands in a repo — removing it from the latest commit does not help, because it lives in history and may already be cloned. A good response rotates first, then purges, then prevents the next one. Detection without rotation is theater.

Two jobs

1. Prevent new secrets from being committed (pre-commit + CI).
2. Find and remediate secrets already present (working tree + full history).

Detect

gitleaks is the fast default; trufflehog adds live credential verification.

# Scan the whole git history (not just the working tree)
gitleaks detect --source . --report-format json --report-path gitleaks.json

# Scan only staged changes (use in a hook)
gitleaks protect --staged

# trufflehog: scan history and verify which secrets are still live
trufflehog git file://. --only-verified

• gitleaks detect walks commits; gitleaks protect checks uncommitted/staged content.
• trufflehog --only-verified calls the provider to confirm a key still works — high signal, but it makes network requests, which Codex’s sandbox may block. Note when a step needs network.
• Scan history, not just HEAD. A secret removed in a later commit is still in the pack.

Triage: real vs false positive

Scanners flag entropy and patterns; many hits are test fixtures, examples, or already-dead keys. For each finding decide:

• Live and real → treat as an incident (rotate immediately, below).
• Real but confirmed dead/revoked → still remove from history; note it was rotated.
• False positive (example value, test fixture, public key) → suppress precisely with an allowlist entry or inline # gitleaks:allow, not by disabling the rule globally.

Keep a .gitleaks.toml allowlist for known-safe paths/patterns so the signal stays high.

Remediate a real leak — order matters

- [ ] 1. Rotate the secret at the provider NOW (invalidate the leaked value)
- [ ] 2. Confirm the old value no longer works
- [ ] 3. Replace the usage with an env var / secret manager reference
- [ ] 4. Purge it from git history
- [ ] 5. Force-push the rewritten history (coordinate — destructive)
- [ ] 6. Add prevention so it cannot recur

Rotate first. Generate a new credential at the provider and revoke the old one. This is the only step that actually stops the exposure; purging history is cleanup.

Purge history with git filter-repo (the supported tool; BFG is an alternative):

# Remove a file that contained the secret from all history
git filter-repo --invert-paths --path config/secrets.yml
# Or redact a specific string across history
git filter-repo --replace-text <(echo 'AKIAEXAMPLE==>REMOVED')

Rewriting history changes every commit hash. This is destructive and requires explicit user confirmation: everyone must re-clone, open PRs may need rebasing, and a force-push is required. Coordinate with the team before git push --force-with-lease. Note that forks and provider caches (and GitHub’s cached views) may retain the old blob — rotation is what protects you, not the purge.

Prevent new leaks

Pre-commit hook (via the pre-commit framework):

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.21.2
    hooks:
      - id: gitleaks

Then pre-commit install. For a husky + lint-staged repo, run gitleaks protect --staged in the pre-commit script instead.

CI gate: run gitleaks detect --redact on the diff/PR and fail on any new finding. Enable the platform’s push protection (GitHub secret scanning push protection) as a backstop so a secret is blocked even if the local hook is skipped.

Verification

• After remediation: re-run gitleaks detect over full history → the secret is gone.
• Confirm the rotated/old credential is rejected by the provider.
• Make a test commit containing a dummy key → the pre-commit hook blocks it.
• CI fails on a PR that introduces a fake secret, passes when clean.

Output contract

## Secret scan — <repo> (<date>)
Tools: gitleaks <ver>, trufflehog <ver>. Scope: working tree + full history.

### Findings
| Secret type | Location (file@commit) | Status | Verified live? | Action taken |
|-------------|------------------------|--------|----------------|--------------|
| AWS key | config/secrets.yml@a1b2 | real | yes | rotated, purged from history |
| Stripe test key | tests/fixtures.js@c3d4 | false positive | n/a | allowlisted |

### Prevention added
- pre-commit gitleaks hook; CI detect gate; push protection enabled

### Destructive actions taken (confirmed by user)
- git filter-repo + force-push on <branch> at <time>

Hard rules

• A committed secret is compromised — rotate before anything else. Do not just delete it.
• History rewrite and force-push are destructive: get explicit user confirmation and coordinate with the team first.
• Never paste discovered secret values into reports, logs, or chat — reference the location.
• Suppress false positives precisely (allowlist/inline), never by turning the scanner off.
• Dependency CVEs are a different task — hand off to dependency-scanning.