Prepush-Guardian: Catch Secrets and Broken Tests Before They Reach Git History

You are about to push. There is a hardcoded API key buried in one of 30 changed files. Or you forgot to write a test for that new module. Or the test suite is silently failing. You will not know until it is already in git history.

Prepush-Guardian catches all of this before the push lands. It is a production-grade Git pre-push hook that scans staged files for secrets, auto-generates missing tests, runs your full test suite, and blocks the push if anything fails before it ever reaches the remote.

Why This Tool

Manual review - Misses things, does not scale, no enforcement
CI/CD only - Finds it after the push, already in history
prepush-guardian - Blocked at push time, before it ever reaches remote

• Scans every staged file for 20+ secret patterns: AWS, GitHub PATs, private keys, database URLs, bearer tokens, and more
• Shannon entropy scanner catches novel secrets not matched by patterns
• Auto-generates missing tests using OpenRouter AI, with a template fallback if no API key is set
• Runs your full test suite and blocks the push if coverage drops below threshold
• Writes a markdown report at .neo/prepush-report.md for every push

Quick Start

# Clone and install the hook into your repo
git clone https://github.com/neo-ai/prepush-guardian
cd your-target-repo

# Install the pre-push hook
python3 /path/to/prepush-guardian/install.py

# Optional: set API key for AI test generation
cp .env.example .env   # fill in OPENROUTER_API_KEY

The hook runs automatically on every git push. To run manually:

python3 prepush_guardian.py

Environment Variables

cp .env.example .env
# Required only for AI-based test generation
# Free key at: https://openrouter.ai/keys
OPENROUTER_API_KEY=your_openrouter_api_key_here

Without an API key, the tool falls back to template-based test generation.

Commands

Detection Patterns

The secret scanner covers 20+ patterns across four severity levels:

The Shannon entropy scanner runs alongside the pattern matcher. It catches novel secrets - API keys or tokens not yet covered by a named pattern by flagging high-entropy strings assigned to variables named KEY, TOKEN, or SECRET.

Scoring and Thresholds

Configuration

Create .neo/config.json to customize behavior. It is auto-created with defaults if absent:
coverage_warn_threshold - default 70. Warn if coverage drops below this percentage.
coverage_block_threshold - default 50. Block push if coverage drops below this percentage.
block_on_low_severity - default false. Also hard-block on LOW findings.
auto_fix_gitignore - default true. Add sensitive filenames to .gitignore automatically.
generate_missing_tests - default true. Auto-generate tests for untested source files.
skip_test_check_for - default ["migrations/", "scripts/", "docs/"]. Directories excluded from test generation.

Exit Codes

0 : All checks passed - push proceeding
1 : Push blocked - CRITICAL/HIGH findings or test failures

File Structure

prepush-guardian/
├── prepush_guardian.py      # Main orchestrator
├── leak_detector.py         # Phase 1: secret & entropy detection
├── test_generator.py        # Phase 2: AI test generation
├── test_runner.py           # Phase 2: test execution + coverage
├── reporter.py              # Phase 3: markdown report
├── install.py               # Hook installer
├── requirements.txt
├── .env.example
├── .gitignore
├── LICENSE
├── CONTRIBUTING.md
├── architecture.excalidraw
├── infographic.svg
└── tests/
    ├── test_leak_detector.py
    └── fixtures/
        ├── sample_with_secrets.py
        └── sample_clean.py

The three-phase structure maps cleanly to the file names - leak_detector.py handles Phase 1, test_generator.py and test_runner.py handle Phase 2, and reporter.py handles Phase 3. prepush_guardian.py orchestrates all three phases in sequence.

How I Built This Using NEO

This project was built using NEO. NEO is a fully autonomous AI engineering agent that can write code and build solutions for AI/ML tasks including AI model evals, prompt optimization and end to end AI pipeline development.

The requirement was a production-grade Git pre-push hook that catches secrets, validates test coverage, and auto-generates missing tests - blocking the push before anything problematic reaches the remote. NEO planned, wrote, tested, and verified every file in this repository without human intervention: the main orchestrator in prepush_guardian.py, the secret and entropy scanner in leak_detector.py covering 20+ patterns, the AI test generator in test_generator.py with OpenRouter integration and template fallback, the test runner and coverage checker in test_runner.py, the markdown report generator in reporter.py, the hook installer in install.py, and the test suite with fixtures.

How You Can Use and Extend This With NEO

Install it into every repo your team pushes from.
Run python3 install.py once in each repository. From that point, every git push runs the full three-phase check automatically, no CI changes, no developer workflow changes. Secrets and test failures are blocked before they reach the remote.

Tune the thresholds to match your team's standards.
The .neo/config.json file controls coverage warn and block thresholds, whether LOW-severity findings hard-block the push, and which directories are excluded from test generation. These can be committed to the repo so the same standards apply across the whole team.

Use the markdown report as a push audit trail.
Every push writes a report to .neo/prepush-report.md.This gives you a record of what was scanned, what was found, and what was blocked, useful for teams with compliance requirements or for debugging why a push was blocked.

Extend the detection patterns in leak_detector.py.
The secret scanner covers 20+ named patterns. Adding a new pattern for a domain-specific secret type means adding it to the pattern list in leak_detector.py. It is immediately active on the next push with no other changes needed.

Final Notes

The gap between "I think this is clean" and "I know this is clean" is where prepush-guardian lives. Secrets get committed because no one checked. Tests go missing because there was no enforcement. prepush-guardian closes both gaps at the moment they matter most before the push lands.
The code is at https://github.com/dakshjain-1616/prepush-guardian
You can also build with NEO in your IDE using the VS Code extension or Cursor.
You can use NEO MCP with Claude Code: https://heyneo.com/claude-code