SecretGuard

Secret detection and prevention system for Git repositories. Detects API keys, tokens, and passwords in staged commits using regex + Shannon entropy, blocks the commit, logs the detection to MongoDB, and shows everything on a Flask dashboard.

Stack: Python 3 · Flask · Jinja2 · Bootstrap · Chart.js · MongoDB (PyMongo) · Git hooks.

Install as a CLI (pip)

pip install secretguard-cli              # CLI + hook only (lightweight)
pip install "secretguard-cli[dashboard]" # + Flask dashboard deps
# or, from source:
pip install -e .
pip install -e ".[dashboard]"

Then use the secretguard command anywhere:

secretguard init              # install hooks into the current repo
secretguard scan              # scan staged diff
secretguard scan src/         # scan a file or directory tree
secretguard status            # show hook state + allowlist entries
secretguard ignore "tests/*"  # add an entry to .secretguardignore
secretguard uninstall         # remove hooks from the current repo

Exit codes: 0 = clean, 1 = secret found.

Setup (from source / dashboard development)

cd secret-guard
python -m venv venv
venv\Scripts\Activate.ps1
pip install -e ".[dashboard]"   # installs CLI deps + Flask/PyMongo/python-dotenv

Create a .env file in the project root with your MongoDB connection string (a local MongoDB instance or a free Atlas cluster both work):

MONGO_URI=mongodb://localhost:27017
MONGO_DB_NAME=secretguard

Run the dashboard + API

venv\Scripts\python.exe run.py

Then open:

• http://localhost:5000/ — dashboard (stat cards, severity/trend charts, recent activity)
• http://localhost:5000/history — searchable, filterable detection history

REST API: POST /api/scan, POST /api/detections, GET /api/detections, GET /api/detections/<id>, GET /api/stats/summary, GET /api/stats/trends, PATCH /api/detections/<id>.

From then on, any git commit that introduces a recognizable secret (AWS keys, GitHub tokens, OpenAI keys, Stripe keys, Google API keys, JWTs, DB connection strings, generic api_key=/secret=/token= assignments, or any high-entropy string) is blocked locally, with a message naming the file, line, and secret type. Detection runs in-process — no server required — and findings are best-effort logged to the Flask app at http://localhost:5000/api/detections if it happens to be running.

Run the tests

venv\Scripts\python.exe -m pytest

Covers detector/regex_rules.py, detector/entropy.py, detector/aggregator.py, and detector/scanner.py — the pure-Python detection engine, independent of Flask/MongoDB.

Project layout

secretguard/   pip-installable CLI package (cli.py, hook.py)
detector/      Detection engine: regex rules, entropy, aggregator, scanner (pure Python)
app/           Flask app: REST API (routes.py), dashboard (dashboard.py), models, MongoDB access
templates/     Jinja2 dashboard pages (Bootstrap + Chart.js)
static/        CSS + Chart.js setup
tests/         pytest suite for the detection engine
run.py         Flask entry point
pyproject.toml pip package definition (name: secretguard-cli, entry point: secretguard)

See IMPLEMENTATION.md for the full task-by-task build log.

Screenshots

Placeholder — add dashboard and history screenshots here.

Author

Built by Piyush Khari — piyushkhari159@gmail.com