PushGuard 🛡️
An airbag for git push

One-time install protection that scans outgoing Git commits for leaked API keys, tokens, and secrets before they reach GitHub.

Why · Installation · Demo · Features · CLI · Security Model

Why PushGuard?

AI coding is fast. Leaking secrets is faster.

When beginners and vibe coders build with ChatGPT, Cursor, Claude, Codex, Gemini CLI, or copied snippets from the internet, it is very easy to accidentally commit something like:

const token = "123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghi"; // pushguard: allow docs example

Then one normal command sends it public:

git push

PushGuard protects that exact moment.

It installs Git push protection once, then every normal git push automatically scans the outgoing commits and blocks the push if a leaked token is detected.

Quick Demo

npm install -g @namaa03/pushguard

Check protection:

pushguard status

Expected output:

PushGuard global status: ACTIVE ✅
pre-push hook:        installed

Now use Git normally:

git add .
git commit -m "update"
git push

If a secret is found:

🚨 PushGuard blocked this push.

Possible Telegram bot token found in bot.js

Move it to .env before pushing.

Installation

Install globally with npm:

npm install -g @namaa03/pushguard

PushGuard sets up global Git push protection automatically.

Verify:

pushguard status

Repair/reinstall protection anytime:

pushguard install

What Makes PushGuard Different?

Most scanners scan your whole folder.

PushGuard is designed for the real Git workflow:

git push
   ↓
PushGuard reads outgoing commits
   ↓
Only files being pushed are scanned
   ↓
Push is blocked if secrets are detected

This means PushGuard does not waste time scanning your entire home directory, downloads folder, node_modules, .venv, or unrelated files.

It checks the code that is actually about to leave your machine.

Features

Git Push Protection

• 🛡️ One-time global install
• 🚦 Automatically checks every normal git push
• 🎯 Scans only outgoing pushed files
• 🧠 Designed for AI-coding and vibe-coding workflows
• ⚡ Fast enough for daily Git usage
• 🧩 Works with normal Git commands

Secret Detection

PushGuard detects known and unknown secret patterns:

• Telegram bot tokens
• GitHub tokens
• GitLab tokens
• AWS access keys
• AWS secret keys
• OpenAI API keys
• Gemini / Google AI keys
• Anthropic API keys
• NVIDIA API keys
• Hugging Face tokens
• Stripe keys
• Discord tokens
• Slack tokens
• SendGrid keys
• Mailgun keys
• Twilio keys
• JWTs
• Database URLs
• Private keys
• Bearer tokens
• Secret-looking variables
• High-entropy unknown tokens
• 1000+ provider/token fingerprints

AI-World Safety

PushGuard is useful when working with:

• ChatGPT
• Codex
• Cursor
• Claude Code
• Gemini CLI
• Windsurf
• Copilot
• OpenRouter
• NVIDIA NIM
• Telegram bots
• AWS projects
• .env based apps

Getting Started

1. Install

npm install -g @namaa03/pushguard

2. Confirm status

pushguard status

3. Use Git normally

git add .
git commit -m "my update"
git push

That is it.

PushGuard runs automatically before the push.

Manual Scanning

Scan current folder:

pushguard scan .

Run stronger paranoid scan:

pushguard scan . --paranoid

Scan staged files before commit:

pushguard scan . --staged --paranoid

Show provider detection stats:

pushguard providers

Show detection rules:

pushguard rules

Auto Fix

PushGuard can auto-fix simple hardcoded tokens in Python, JavaScript, and TypeScript files.

Example unsafe code:

const token = "123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghi"; // pushguard: allow docs example

Safer code:

const token = process.env.TELEGRAM_BOT_TOKEN;

Run:

pushguard fix --yes

Or install with auto-fix enabled:

pushguard install --both --auto-fix --paranoid

Auto-fix is intentionally conservative. It only edits simple standalone quoted string tokens.

Commands

pushguard scan [path] [--staged|--tracked|--pre-push] [--json] [--paranoid] [--max-size 5mb]

pushguard fix [path] [--yes] [--staged|--tracked|--push-files] [--paranoid] [--max-size 5mb]

pushguard install [--local] [--pre-commit|--both] [--auto-fix] [--paranoid]

pushguard status

pushguard uninstall [--local]

pushguard rules

pushguard providers

Aliases:

pushgaurd
git-airbag

Yes, the typo alias pushgaurd is supported on purpose.

Local Repo Mode

Install PushGuard only for the current repository:

pushguard install --local

Install both pre-push and pre-commit hooks locally:

pushguard install --local --both --paranoid

Uninstall local protection:

pushguard uninstall --local

Global Mode

Install global Git protection:

pushguard install

Check global status:

pushguard status

Uninstall global protection:

pushguard uninstall

Recommended .env Setup

Never commit real secrets.

Use local .env:

TELEGRAM_BOT_TOKEN=123456789:real_secret_here # pushguard: allow docs example
OPENAI_API_KEY=sk-real_secret_here # pushguard: allow docs example

Commit safe .env.example:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
OPENAI_API_KEY=your_openai_key_here

Add .env to .gitignore:

.env
.env.*
!.env.example

Security Model

PushGuard is a safety net, not magic.

It uses multiple detection layers:

1. Known token regex rules
2. Provider fingerprint matching
3. Secret-looking variable name detection
4. Entropy-based unknown token detection
5. Git pre-push scanning of outgoing commits

No scanner can detect every possible secret with 100% accuracy because providers create new token formats and some secrets look like normal strings.

For best protection:

• Keep secrets in .env
• Commit .env.example, not .env
• Add .env to .gitignore
• Rotate leaked keys immediately
• Use GitHub secret scanning too
• Review AI-generated code before pushing

Example: Blocked Push

🚨 PushGuard blocked this push.

Found 2 possible secrets:

bot.js
  Possible Telegram bot token

config.py
  Possible OpenAI API key

Fix:
  Move secrets to .env
  Add .env to .gitignore
  Commit .env.example instead

Works On

• Linux
• macOS
• Termux
• AWS EC2
• Most Unix-like Git environments

Windows support may work through Git Bash, WSL, or similar environments.

Development

Clone:

git clone https://github.com/krishn03id/pushguard.git
cd pushguard

Install locally:

npm install -g .

Run tests:

npm test

Try scanner:

pushguard scan . --paranoid

Package preview:

npm pack --dry-run

Roadmap

• Better Windows support
• More provider-specific patterns
• GitHub Actions integration
• JSON SARIF output
• More language-aware auto-fixes
• VS Code extension
• AI-agent safe mode
• Config file support

Disclaimer

[!CAUTION] PushGuard helps detect leaked secrets before Git push, but it is not a guarantee. Always rotate any secret that may have been exposed. The authors are not responsible for leaked credentials, misuse, false positives, or false negatives.

License

MIT