zak-guard

A pre-commit secret scanner. Catches AWS keys, GitHub PATs, Stripe tokens, private keys, and other credentials before they land in your repo.

Works standalone as a CLI tool and as a hook in the pre-commit framework.

What it catches

Every finding shows file:line, the rule name, and a redacted match (AKIA...Y01). The full value is never printed.

Install

pip install zak-guard
# or
pipx install zak-guard

Use as a CLI

Scan staged changes (what you're about to commit):

zak-guard --staged

Scan everything in the current directory:

zak-guard --all

Scan a specific path:

zak-guard --all ./src

Suppress known false positives with an allowlist:

zak-guard --staged --allowlist .zak-guard-allowlist

Wire it as a git pre-commit hook:

zak-guard install

Use with the pre-commit framework

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/molloyzak13/zak-guard
    rev: v0.1.0
    hooks:
      - id: zak-guard

Then install:

pre-commit install

Allowlist

Create a text file with one entry per line. Any detected value that contains an allowlist entry is suppressed. Lines starting with # are comments.

# .zak-guard-allowlist
AKIAEXAMPLE         # known-fake key in test fixtures
sk_live_test_       # Stripe test mode prefix used in integration tests

Pass it with --allowlist <file> or set the ZAK_GUARD_ALLOWLIST environment variable.

How detectors work

Each rule combines a regex pattern with a Shannon entropy minimum. The entropy gate cuts false positives on placeholder values like YOUR_API_KEY_HERE or xxxxxxxxxxxx that match the pattern shape but are obviously not real credentials.

The staged scanner (--staged) parses git diff --cached and flags only added lines. It won't block you for secrets that were already in the repo before your change.

Exit codes

Development

git clone https://github.com/molloyzak13/zak-guard
cd zak-guard
pip install -e ".[dev]"
pytest -v

License

MIT