_____      _        ____
| ____|_ __(_) ___  / ___| _ __   ___ _ __   ___ ___ _ __
|  _| | '__| |/ __| \___ \| '_ \ / _ \ '_ \ / __/ _ \ '__|
| |___| |  | | (__   ___) | |_) |  __/ | | | (_|  __/ |
|_____|_|  |_|\___| |____/| .__/ \___|_| |_|\___\___|_|
                          |_|                             

---

← back to index

Git Key Guardian

Protect sensitive keys from accidentally being uploaded to your git history at any point.

repo: https://github.com/EricSpencer00/git-key-guardian

---

Git Key Guardian is a pre-commit hook and helper toolkit. It scans staged changes for common secret patterns and for a user-supplied list of personal keys, so that API keys, tokens, and credentials are caught before they enter git history.

Why this project

Secrets get committed by accident. API keys, SSH keys, cloud credentials, and other sensitive strings can slip into commits or CI logs. Git Key Guardian is an opt-in check that runs locally as a shared hook and reports matches against a configurable set of regex patterns and a personal key list.

The tool is deliberately simple and conservative. It scans only staged changes, uses maintainable regex patterns, and supports exact-string matches for specific keys.

Features

• Scans only staged (cached) changes, which avoids noise from the working tree.
• Configurable regex patterns stored in patterns/common_patterns.txt, one per line, with inline comments allowed.
• Exact-string matching against a per-user personal key file at $HOME/.git-key-guardian/personal_keys.txt.
• An interactive prompt when matches are detected, with the option to abort or proceed with the commit.
• An installer script that wires the hook globally via core.hooksPath so it covers all local repositories.

How it works

On git commit, the pre-commit hook captures the staged diff with zero context and extracts newly added lines, meaning those starting with a single +. It then runs two checks:

1. Grep-style regex checks using the patterns in patterns/common_patterns.txt, with comments and blank lines ignored.
2. Fixed string checks against the personal keys file at $HOME/.git-key-guardian/personal_keys.txt.

If either check matches, the hook prints a sample of the matching lines and prompts for abort or continue.

Install

Clone the repository and run the installer script. The installer copies the pre-commit hook to a shared hooks directory and configures git to use it globally.

git clone https://github.com/EricSpencer00/git-key-guardian.git
cd git-key-guardian
chmod +x ./scripts/install.sh
./scripts/install.sh

Patterns are copied to $HOME/.git-key-guardian/patterns/common_patterns.txt and the hook is installed at $HOME/.git-key-guardian/hooks/pre-commit. The installer also creates an editable personal_keys.txt.

To uninstall, remove the shared hooks directory or run:

git config --global --unset core.hooksPath

Usage

• Stage changes as usual with git add.
• Run git commit. The hook scans staged changes automatically.
• When potential secrets are found, sample matches are printed along with a prompt to continue or abort.

Test locally without installing

To exercise the hook without changing the global git configuration, create a temporary repository and run a commit, as described in CONTRIBUTING.md:

mkdir /tmp/gkg-test && cd /tmp/gkg-test && git init -q
cat > test.txt <<'EOS'
ess kay _ live_1234567890abcdefghijklmn
not_a_key AKIAABCDEFGHIJKLMNOP
random text
EOS

git add test.txt
GIT_DIR=.git GIT_WORK_TREE=. git commit -m "test" || true

The hook reports any matches and prompts before the commit proceeds.

Patterns and personal keys

The shipped regex list lives at patterns/common_patterns.txt. Entries follow three rules: one regex per line, with no /.../ delimiters; inline comments after whitespace and a # are allowed; and patterns should avoid catastrophic backtracking, preferring anchored subpatterns and bounded repetition.

Patterns included by default:

• sk_live_[0-9a-zA-Z]{24} (Stripe live keys)
• sk-[A-Za-z0-9]{48} (older OpenAI key format)
• AKIA[0-9A-Z]{16} (AWS Access Key ID)
• ssh-rsa\s+[A-Za-z0-9+/=]+ (SSH public keys)

Exact personal secrets go in $HOME/.git-key-guardian/personal_keys.txt. Lines beginning with # are ignored.

Implementation notes

• The hook uses POSIX-compatible tools: bash, sed, grep, and awk.
• The patterns file is preprocessed to strip comments and blank lines before grep -En -f runs against staged additions.
• Personal keys are searched as fixed strings with grep -Fn -f, again after comment and blank lines are removed.
• Only added lines in the staged diff are inspected (git diff --cached --unified=0 plus an awk filter for ^+[^+]).

Caveats

• The tool is a helper, not a substitute for secret management. Keys still need rotation, environment variables or secret stores, and audits of logs and CI output.
• False positives are possible. The personal keys file reduces noise for known values.
• The hook runs locally and does not scan remote or CI logs, so server-side scanning in CI remains a separate concern.

Links

• Git repository: https://github.com/EricSpencer00/git-key-guardian
• Installer script: scripts/install.sh
• Hook file: hooks/pre-commit
• Default patterns: patterns/common_patterns.txt