Metadata-Version: 2.4
Name: secretguard-cli
Version: 0.1.0
Summary: Secret detection and prevention for Git repositories
Author-email: Piyush Khari <piyushkhari159@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Khari-Piyush/secret-guard
Project-URL: Repository, https://github.com/Khari-Piyush/secret-guard
Project-URL: Issues, https://github.com/Khari-Piyush/secret-guard/issues
Keywords: security,git,secrets,pre-commit,devsecops,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: dashboard
Requires-Dist: flask>=3.0; extra == "dashboard"
Requires-Dist: pymongo>=4.0; extra == "dashboard"
Requires-Dist: python-dotenv>=1.0; extra == "dashboard"
Dynamic: license-file

# SecretGuard

[![GitHub](https://img.shields.io/badge/github-Khari--Piyush%2Fsecret--guard-blue)](https://github.com/Khari-Piyush/secret-guard)

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)

```bash
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)

```powershell
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

```powershell
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

```powershell
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
