Secrets Scan

Purpose

Find committed secrets that SonarQube misses. SonarQube only matches a few regex rules against the current HEAD and never confirms whether a secret is real. This skill combines two complementary engines:

• Gitleaks — a broad, fast net over the entire git history with large, tunable rulesets, entropy detection and baselining.
• TruffleHog — live verification: it calls the provider API to confirm whether a found secret is still active (--results=verified), so "zero" means zero real, live secrets — not zero regex matches.

They overlap on detection but TruffleHog adds verification and Gitleaks adds history breadth, so both are justified (this is "similar but more", not duplication). Trivy's secret scanner is shallower and stays in the Trivy skill.

Core Workflow (drive to zero)

1. Scan:

   ~/.claude/skills/secrets-scan/scripts/scan.sh [TARGET_DIR]

2. For every finding:
   • Rotate/revoke it first — a secret that was ever committed is compromised, even after deletion. Then remove it from current code and load it from an environment variable or secret manager.
   • Historical-only hits (the secret is no longer in HEAD, only in past commits): once rotated, mark them reviewed/allowlisted. Do NOT rewrite git history (git filter-repo, force-push) autonomously — it is destructive and breaks shared history; only on explicit human decision.
   • Mark a confirmed false positive in a .gitleaksignore file (by fingerprint) with a justification — do not weaken rules.
3. Re-run until RESULT: PASS.

Notes

• The script always scans exactly the target dir (no scope expansion) and prints the chosen mode. It uses git mode (full history) only when <target>/.git is a real directory — i.e. the target is a repo root with the object database present. A .git file (a linked worktree or git submodule) has its objects in the main repository, not at the target, so the script honestly falls back to working-tree-only mode (no history) and says so — run the scan on the main repo root for full history. With no .git at all it also scans the working tree only. This avoids the false-clean a "0 commits scanned" repo would otherwise produce.
• TruffleHog runs with --results=verified so the report focuses on actually live secrets; change it (edit the script) for an exhaustive, noisier pass.
• --fail makes TruffleHog exit 183 when verified secrets are found; the script treats only that as a finding (other non-zero = operational ERROR).
• A live secret is cleared only by rotation — a .gitleaksignore allowlist silences Gitleaks but TruffleHog re-verifies and keeps failing until revoked.

Resources

• scripts/scan.sh — runs Gitleaks then TruffleHog against a directory, history-aware, exit 1 if any secret is found.