secret-scanner

When to use

Trigger this skill on any of:

• "Scan this repo for secrets / leaked keys / API tokens."
• "We think a credential was committed — help us remediate."
• "Repo is going public next week."
• Pre-merge hook that needs to refuse commits with new secrets.

Do not use this skill for live runtime secret detection (key rotation monitoring, cloud config scanning). Use it for code-at-rest and git history only.

Inputs

• REPO_PATH (default: .) — path to the git repo.
• ALLOWLIST (default: .gitleaks.toml or .secret-scanner-allowlist.yaml at repo root) — known false positives.
• OUT_DIR (default: ./secret-scan-out).
• SCAN_REFLOG (default: 1) — also scan reflog + stash refs.
• Optional env:
  • TRUFFLEHOG_CONFIG — path to a custom trufflehog config.
  • REDACT (default: 1) — redact matched values in reports.

Outputs

• gitleaks-report.json — raw Gitleaks findings.
• trufflehog-report.json — raw TruffleHog findings.
• secrets.deduped.json — unified, allowlist-filtered, deduplicated result.
• secrets-report.md — human report with per-finding remediation steps.

Each unified record:

{
  "id": "sha256(commit|file|rule|match)[0:12]",
  "rule": "aws-access-key",
  "file": "src/infra/deploy.sh",
  "commit": "a1b2c3d",
  "author": "[email protected]",
  "date": "2024-06-12T09:14:22Z",
  "line": 42,
  "redacted_match": "AKIA****************",
  "verified": true,
  "severity": "critical",
  "allowlisted": false
}

Tool dependencies

• git >= 2.30.
• gitleaks >= 8.18 (https://github.com/gitleaks/gitleaks).
• trufflehog >= 3.63 (https://github.com/trufflesecurity/trufflehog).
• jq for merging.
• Optional: git-filter-repo (preferred over BFG) for rewriting history.

Procedure

1. Confirm $REPO_PATH is a git repo (git rev-parse --is-inside-work-tree).
2. Fetch all refs first: git fetch --all --tags --prune.
3. Run scripts/nuclear-scan.sh "$REPO_PATH" "$OUT_DIR" which executes Gitleaks (detect + protect), TruffleHog over the git file URI, and iterates branches, tags, reflog, and stash refs.
4. Merge the two JSON outputs. Key by (commit_sha, file_path, rule_id, match_sha256) and dedupe.
5. Apply allowlist: drop records whose (file_path, rule_id) pair matches a regex in the allowlist. Every drop keeps a skipped_by_allowlist counter that is logged.
6. Triage: for every remaining record,
   • Verify with TruffleHog's --only-verified style detector when possible (sets verified: true|false).
   • Classify severity: verified live credential -> Critical; historical credential known rotated -> High; placeholder or test -> Low.
7. Emit secrets-report.md containing:
   • Top-line counts by severity.
   • A "Remediation sequence" section (always this order):
     1. Rotate the credential at the issuer (AWS, GitHub, Stripe, ...). Never do history rewrite first — a rewritten commit doesn't revoke a live key.
     2. Invalidate any cached credential (CI secret store, deploy platform env vars, developer laptops).
     3. Rewrite history with git filter-repo (preferred) or BFG.
     4. Force-push (coordinate with team). Every collaborator re-clones.
     5. Update the allowlist with a post-rotation hash so the dead secret doesn't re-trigger alerts.
8. Provide exact commands tailored to each finding:
   • git filter-repo --invert-paths --path <file> when the file should go.
   • git filter-repo --replace-text replacements.txt when only the secret should be scrubbed, preserving surrounding content.
9. Return non-zero if any verified Critical remains.