secret-scan

name	secret-scan
description	Hunt committed secrets with gitleaks and drive safe rotation

Find committed credentials and get them rotated and removed — without ever exposing them further yourself.

ABSOLUTE RULE: never print a secret's value — not in output, notes, todo items, commits, or PRs. Refer to every hit as " in : (commit )".

1. Check the tool: gitleaks version. If it's missing, do NOT skip this scan and do not stop the review — ask for it with request_tool("gitleaks", …). If the user declines, or no pinned build exists for their platform, fall back to step 2b and say in your report that the sweep was manual.
2. Scan working tree AND history — history matters most: a secret deleted in HEAD is still live in every clone, and it is the hit users are most surprised by. a. With gitleaks: gitleaks detect --source . --report-format json --report-path /tmp/gitleaks.json b. Without it, do the same job by hand, and say so:
   • working tree: git grep -nIE '(api[_-]?key|secret|token|password|BEGIN [A-Z ]*PRIVATE KEY|AKIA[0-9A-Z]{16}|sk_(live|test)_[0-9a-zA-Z]{16,}|xox[baprs]-)'
   • history, including files deleted since: git log -p --all -S 'AKIA' --pickaxe-all and git log --diff-filter=D --name-only --pretty=format:%h -- '*.env*' '*credential*' '*secret*', then read the removed contents with git show <sha>^:<path>.
   • Pipe anything you read through a redactor rather than into your transcript, e.g. sed -E "s/[A-Za-z0-9_\\-]{16,}/[REDACTED]/g" — the no-printing rule still applies.
3. Triage each hit by reading its context:
   • Real credential, test fixture, or example placeholder? Say which and why.
   • For real ones: what does it grant access to, and is it plausibly still valid?
4. For every real secret, in this order: a. ROTATE first — tell the user exactly where to revoke/rotate it (the provider's console page or CLI command). Rotation beats removal: history rewrite without rotation is false comfort. b. Remove it from the code: move to env vars or the project's secret store, matching how this codebase already handles configuration. c. Prevent recurrence: add/extend .gitignore for local secret files and offer a .gitleaks.toml baseline plus a pre-commit hook. d. History purge (git filter-repo/BFG) is DESTRUCTIVE and rewrites shared history — describe the trade-off and only proceed if the user explicitly asks.
5. Deliver: a hit list (kind · location · verdict · rotation status), the cleanup branch/PR, and the prevention setup you added or recommend.