/secret-leak-preflight

name: secret-leak-preflight
description: Use when about to commit, push, or publish -- staged changes touch config or environment files, generated artifacts (relay sessions, logs, build output) are being added, or the session handled credentials even indirectly.

Purpose

Catch secrets before they enter git history or a published artifact. A leaked credential in a commit is a rotation incident even after the file is deleted — history retains it. The preflight is the last cheap moment to stop that.

When to Use

• Before committing config, environment, or infrastructure changes
• Before pushing or opening a PR that includes generated artifacts
• Before publishing a release or packaging files
• After any session that handled credentials, even indirectly

Inputs

• The staged diff and the untracked-file list
• Knowledge of which artifact directories the session wrote (relay sessions, logs, build output)

Workflow

1. **Scan the staged diff — not the worktree.** What gets committed is the staged content:

   git diff --cached | rg -n 'AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}|github_pat_|sk-[A-Za-z0-9]{20,}|xox[baprs]-|-----BEGIN [A-Z ]*PRIVATE KEY-----'
   git diff --cached | rg -in '(api[_-]?key|secret|token|password|bearer)\s*[:=]'

2. **Review untracked files before adding.** New environment or credential files are the classic leak:

   git status --short

Anything with env, credential, key, or pem in its name gets opened and inspected before any git add.

3. **Check generated artifact directories.** Relay turn artifacts and logs can embed tokens captured from tool output; confirm those directories are gitignored and excluded from what is being committed or published.

4. **Spot-check high-entropy strings.** Pattern lists miss rotated formats; a long random-looking constant in a diff deserves one deliberate look.

5. **On a hit: stop.** Unstage the file, remove the secret, and treat the value as compromised — recommend rotation. If it already exists in history, plan a history purge with the user; never rewrite or force-push history without explicit approval.

6. **State the verdict explicitly.** Silence is not a pass — say "no secrets found in staged changes" or list the findings.

Output

• A pass/fail verdict for the staged changes, stated explicitly
• On fail: the file and match, the unstage action taken, and the rotation recommendation
• Confirmation that artifact directories were checked, not assumed ignored

Verification

• [ ] The scan ran against the staged diff, not only the working tree
• [ ] Untracked files were listed and suspicious names opened
• [ ] Generated artifact locations were confirmed ignored or excluded
• [ ] Any hit led to unstage plus rotation guidance, not a quiet fix-up commit
• [ ] The verdict was stated explicitly, including the clean case

Failure Modes

• **Worktree-only scan** — the staged diff is what ships; scanning only files on disk misses staged-but-reverted edits and vice versa.
• **Pattern-list confidence** — regexes catch known formats; entropy and context still need a deliberate look.
• **Quiet fix-up** — committing a "removed secret" follow-up leaves the value in history; rotation is still required.
• **Publishing artifacts unscanned** — relay and log files can carry tokens captured from tool output.