secret-guard

A file watcher that detects secret/credential files (.env, *.pem, id_rsa, etc.) the moment they're created or edited in a git repo. It automatically adds them to .gitignore, and if the file was already committed, untracks it (git rm --cached) and warns you to rotate/change any credentials it contained.

Why this exists

This was built after a real incident: someone pushed env vars/secrets as part of a regular push to a feature branch. It wasn't the first time — it had happened a few times before, always resolved manually by reaching out to security/webops to rotate credentials and confirm nothing was exposed. This tool aims to catch that class of mistake automatically, at the moment a secret file is created, rather than relying on someone noticing during review or after a push.

How it works

1. Watches a repo directory for file creation/changes (using chokidar).
2. Checks new/changed files against a list of known secret-file patterns (.env*, *.pem, *.key, id_rsa, credentials.json, etc.).
3. If a match isn't already covered by .gitignore, adds the right ignore pattern automatically.
4. Checks whether the file is currently tracked by git (git ls-files). If so, runs git rm --cached to untrack it.
5. Checks whether the file has ever existed in git history (git log --all -- <file>). If so, prints a warning — because .gitignore and git rm --cached don't remove anything from history, so any credential in that file should be treated as compromised and rotated.

Important: this tool does not rewrite git history and does not rotate credentials for you. If a secret file was ever committed, treat the secret as leaked — rotate it, and if needed, use git filter-repo to scrub history and coordinate a force-push with your team.

What it currently detects

Filename-pattern matching only, for now:

• .env and all .env.* variants
• *.pem, *.key, *.p12, *.pfx
• credentials.json, secrets.json, secrets.yml, secrets.yaml
• id_rsa, id_rsa.pub
• *.keystore, service-account*.json

Files that don't match these patterns are scanned for secret content using gitleaks (e.g. an AWS key hardcoded in config.js). Content-matched files are flagged with a warning but not auto-added to .gitignore, since they likely contain legitimate code alongside the secret — the secret needs to be removed manually.

Customizing detection with .secretguardrc

Drop a .secretguardrc file in your repo root to customize the default pattern list:

{
  "extend": ["terraform.tfstate", "*.tfvars"],
  "ignore": ["*.pem"]
}

• extend — additional filename patterns (glob syntax) to treat as secrets
• ignore — default patterns to stop flagging (e.g. if your repo legitimately keeps .pem files in version control)

If .secretguardrc is missing or invalid, secret-guard falls back to its built-in defaults and prints a warning if the file exists but couldn't be parsed.

Install

Prerequisite: gitleaks must be installed and on your PATH for content-based secret scanning. Without it, secret-guard still works but only catches secret-named files, not secrets pasted into normal files.

brew install gitleaks   # macOS
gitleaks version        # confirm it's on PATH

Then clone and link this tool locally:

git clone https://github.com/spragada4/secret-guard.git
cd secret-guard
npm install
npm link

This makes secret-guard available as a global command. If gitleaks isn't found, the tool will print a warning on startup and fall back to filename-pattern detection only.

Usage

Run inside any git repo you want to protect:

cd your-project
secret-guard

With no argument, it watches the current directory. You can also point it at a specific path:

secret-guard /path/to/repo

Git hooks (recommended)

The live watcher only protects you while it's running. To also catch secrets that arrive via git pull, git checkout, or cloning a repo that already has a leaked secret in history, install the git hooks:

secret-guard-install-hooks /path/to/repo

This installs post-checkout and post-merge hooks that run a one-time scan of all tracked files whenever you switch branches or pull changes.

You can also run a one-off scan manually at any time:

secret-guard scan /path/to/repo    

Example

$ secret-guard
[secret-guard] Watching /Users/you/your-project for secret files...
[secret-guard] Detected potential secret file: .env
[secret-guard] Added ".env*" to .gitignore
[secret-guard] WARNING: ".env" was tracked by git and has been untracked (git rm --cached).
[secret-guard] SECURITY WARNING: ".env" exists in git history. Assume any credentials in it are compromised — rotate them now.

Project structure

index.js            CLI entry point (commander)
src/patterns.js      list of secret-filename patterns + matcher
src/gitignore.js      .gitignore read/patch logic
src/git.js           tracked-file checks, untrack, history check
src/watcher.js        chokidar watcher, debouncing, orchestration
tests/                manual test scripts for each module

Roadmap

• [x] Content-based secret scanning (via gitleaks), to catch secrets in files that don't match a known filename pattern
• [x] Git hook fallback (post-checkout / post-merge) to catch secrets introduced via git pull, not just local file creation
• [ ] Publish to npm for install without cloning
• [x] Configurable pattern list (e.g. .secretguardrc)

Status

Early-stage, working proof of concept. Built and tested manually; no automated test suite yet.