← All projectsTOOL + LIVE DEMO · SECRETS MANAGEMENTSecret Scanner &
Pre-Commit Guard
A dependency-free Python scanner that finds leaked API keys in files, staged changes, and full git history, blocks the commit, and can confirm whether a found key is still live. It ships with a CI gate, SARIF output, a measured accuracy harness, a reference gateway that keeps keys off the client, and a rotation runbook. A browser demo runs the same rules on pasted code.
- Python standard library
- Fictional keys only
- Redacted output
- Verification opt-in
Secrets detectionGit hooksShannon entropyPythonJavaScriptSARIF / CIGRC mapping
Open the scanner demo ↗Detection is regex plus entropy: expect false positives and misses. A leaked key is only fixed by rotating it; deleting the line does not remove it from history. Source: scripts/secret_scan.py and scripts/install_hooks.py.
DEFENSE IN LAYERS
- 01 / PREVENTPre-commit hook
Scans the staged version of each file and blocks the commit
- 02 / DETECTHistory and directory scans
Finds keys already committed, even if later deleted
- 03 / RESPONDRedacted reports and rotation steps
Per-provider remediation; full secrets are never printed
The commit that never happens
The pre-commit hook scans the staged version of every file, so a key you deleted from your editor but still staged is caught. Keys below are fictional.
$ git add config.py
$ git commit -m "add deploy config"
secret_scan: scanning 1 staged file
HIGH config.py:2 AWS access key ID AKIA******ZD [UNVERIFIABLE]
HIGH config.py:3 GitHub token ghp_******uQ [ACTIVE]
2 potential secret(s). Commit blocked. Rotate real keys.
$ # revoke the token, move both values to the environment, retry
$ git commit -m "add deploy config"
No secrets detected. [main 3f2a9c1] add deploy config
Measured, not claimed
An evaluation harness (scripts/eval_scanner.py) generates keys in each provider's format, embeds them in realistic code, and also scans look-alikes and real source files. Its accuracy floor is part of the test suite, so accuracy cannot silently regress.
- 10detection rules across provider formats and generic secrets
- 300 / 300seeded synthetic keys detected (100% recall)
- 0false positives in 20 hard look-alikes (hashes, UUIDs, placeholders, env lookups)
- ~480k linesof real code (Python standard library and this site) scanned with 0 false positives
Honest limits: the synthetic keys follow public format specs, so recall on real keys in the wild will be lower, especially for keys with no fixed prefix. The first evaluation run found 8 false positives (hyphenated identifiers such as Proxy-Authorization, and the word author matching auth) and one missed Google key ending in a hyphen. All were fixed and are now pinned by tests. Precision is only as good as the negative corpus.
From “possible leak” to “confirmed incident”
With the opt-in --verify flag, each finding is checked against its own provider using a read-only endpoint, so triage starts with the keys that are actually live.
Safeguards: verification is off by default, each key is sent only to its issuer's host (enforced in code and tested), only read-only calls are made, and secrets are held in memory and never written to reports. Verification is tested against mocked providers; I have not run it against live accounts. Use it only on credentials you are authorised to test. The browser demo makes no network calls.
Prevention: keep the key off the client entirely
The best leaked key is one the browser never had. The reference gateway (scripts/key_proxy.py) holds the vendor key server-side and gives clients short-lived, scoped tokens.
BrowserHolds a signed token that expires in minutes and is valid for specific paths only
→
GatewayChecks origin, signature, expiry, path scope, body size, and per-client rate limit, then attaches the key
→
Vendor APISees only the gateway. Rotate by setting a second key; clients are unaffected
Teaching reference, not a hardened product: no TLS termination, no persistent revocation list, in-memory rate limiting. Eight tests cover forged and expired tokens, scope traversal, rate-limit refill, and rotation fallback.
Built for a real workflow
- BaselinesAccept legacy findings by fingerprint (a truncated hash, never the secret) so the build only fails on new leaks.
- SARIF 2.1.0Findings can upload to GitHub code scanning alongside other security tools.
- CI gateA GitHub Actions workflow runs tests, the tree scan, and a full-history scan on every pull request.
- Redaction everywhereConsole, JSON, SARIF, and reports show
ghp_******uQ, never the full value.
Control mapping
How each capability supports common framework requirements. This is my interpretation for a portfolio project, not an audit assertion or a compliance claim.
When a key leaks: the response targets
- Within 1 hour: containRevoke or disable the key at the provider.
- Same working day: replaceIssue a narrowly scoped replacement, deployed through the secret store, not source.
- Within 2 working days: reviewAudit provider logs for the exposure window; escalate if anything is unexplained.
- Then: preventHook, CI gate, and moving the credential to a secret manager. Deleting the commit does not un-leak a key.
The full seven-step runbook with per-provider revocation pointers is in docs/key-rotation-runbook.md. The targets are illustrative defaults; real ones belong in an organisation's incident policy.