auditing-repo-for-leaks

name

auditing-repo-for-leaks

description

Audits a git repo's full commit history for anything that makes it unsafe to publish — leaked secrets/credentials, PII, work identity, machine-local paths, and accidentally-committed binaries, DB dumps, or key material. Produces a safe-to-publish / not verdict with per-finding severity. Use when asked whether a repo is safe to open-source or make public, to check history for leaked secrets or sensitive data before publishing, or to audit a repo for leaks. This is a leakage audit, NOT a vulnerability scan of the code — for exploitable code flaws use the code-review or verification skill instead.

Repo Leak Audit

Answers one question: is this repo's history safe to be public? It sweeps every commit (not just the current tree) for disclosed sensitive data, then gives a verdict. It does not judge whether the code is exploitable — that is a different skill.

Process

Audit checklist:
- [ ] Run the sweep script over the full history
- [ ] Confirm the scanner self-test PASSED (else the clean result is meaningless)
- [ ] Triage findings: hard blockers vs cosmetic advisories
- [ ] Write the verdict + remediation note

1. Run the sweep

scripts/scan-history.sh [repo-dir]

It locates or fetches gitleaks, self-tests it against a planted key (a clean result is only trustworthy if the scanner demonstrably fires on a known secret — never skip this), then reports six passes over git rev-list --all: secrets, machine-local paths, private keys, committed binaries/dumps/env files, commit-author identities, and other emails in file contents. Exit 0 clean, 1 hard findings, 2 self-test failed (untrusted).

2. Triage what it finds

Judgment the script can't make — decide per finding:

• Hard blockers (must fix before publishing): live secrets/tokens/passwords, any BEGIN … PRIVATE KEY, committed .env/DB dumps/keystores, real customer or personal PII.
• Cosmetic advisories (usually fine, mention them): machine-local paths like /home/<user>/… (leaks a username already implied by the repo owner), the commit author email — it is in every commit by design; flag only if it's a work address the author didn't mean to expose.
• Verify, don't assume: confirm a flagged string is a real secret (a live key, not a placeholder/test fixture) before calling it a blocker.

3. Report

# Repo Exposure Audit — <repo> @ <commit>

Scanner self-test: PASS/FAIL   Commits scanned: <n>

## Verdict: SAFE TO PUBLISH | NOT YET
## Hard findings   (Fn — blocker: what, which commit/file)
## Advisories      (An — cosmetic: what, why it's acceptable)
## Clean           (what was checked and came back empty)

Tag each finding with a stable id (F1, A1) so it can be referenced in follow-up.

Remediation — and when NOT to rewrite

If a hard finding exists, the fix is to purge it from history (git filter-repo --replace-text, then force-push) and rotate the exposed credential — rotation is the part that actually protects you.

Rewriting public history has sharp caveats — weigh them before proposing it:

• A rewrite does not un-publish. Once a repo is public, old commits are already cloned, cached by SHA, and possibly forked/archived. Rewriting cleans the canonical history, not every copy. For an already-leaked secret, rotation is mandatory; the rewrite is cosmetic cleanup on top.
• Tags and releases hold their own copy. Force-pushing main does not move release tags — they still point at the original commits, so the leaked data survives there. Fully purging means rewriting the tags too, which re-points every release tag to a commit its binaries were never built from (broken provenance) and, because pushing an existing tag is a ref update, re-triggers the release CI for every tag (a wall of failed runs if the workflow does gh release create on an existing release).
• So for a low-value, already-public disclosure (e.g. a local path, a username the owner already reveals), the honest recommendation is often leave it — the rewrite's disruption outweighs scrubbing a cosmetic string. Reserve rewrites for genuine secrets, and pair them with rotation.

Always take a full backup first (git clone --mirror) and confirm the tree is byte-identical afterward except for the intended change.