← All projects
TOOL + LIVE DEMO · SECRETS MANAGEMENT

Secret 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
  1. 01 / PREVENTPre-commit hook

    Scans the staged version of each file and blocks the commit

  2. 02 / DETECTHistory and directory scans

    Finds keys already committed, even if later deleted

  3. 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.

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.

StatusMeaningResponse
ACTIVEThe provider accepted the credentialIncident: revoke and rotate now
INACTIVEThe provider rejected itHygiene: remove from the tree, baseline the fingerprint
UNVERIFIABLECannot be tested safely (AWS key ID alone, private keys, unknown services) or the check was inconclusiveAssume live until the owner proves otherwise

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

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.

ObjectiveCapabilityNIST CSF 2.0ISO 27001:2022SOC 2 (2017 TSC)
Keep credentials out of source codePre-commit hook, CI scanPR.AA-01A.8.4, A.8.28CC6.1
Never expose vendor keys to clientsGateway with scoped, expiring tokensPR.AA-05A.5.15, A.5.17CC6.1, CC6.6
Detect exposed credentialsHistory scan, SARIF, evaluation harnessDE.CM-09A.8.16CC7.2
Contain and eradicate exposureLive verification, rotation runbookRS.MI-01, RS.MI-02A.5.26CC7.4

When a key leaks: the response targets

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.