🔐 PyGuard

Secure environment variable & secrets manager for Python projects

Never accidentally commit your secrets again.

---

The Problem

Every Python developer has been there — you push to GitHub, then realize .env is in the commit history. Or you clone a project and spend 20 minutes figuring out which env vars are needed and where to get them.

PyGuard fixes that.

What It Does

PyGuard is a lightweight CLI tool that:

• Audits your project for exposed secrets and hardcoded credentials
• Validates that all required env vars are present before running your app
• Generates .env.example from your actual .env (values stripped, keys kept)
• Encrypts sensitive .env files for safe sharing with teammates
• Checks your git history for accidentally committed secrets

Installation

pip install pyguard-cli

Or install from source:

git clone https://github.com/Alice699/pyguard.git
cd pyguard
pip install -e .

Quick Start

# Audit your current project for exposed secrets
pyguard audit

# Validate all required env vars are set
pyguard validate --schema .env.schema

# Generate a safe .env.example from your .env
pyguard export

# Encrypt your .env for sharing
pyguard encrypt .env --output .env.encrypted

# Decrypt
pyguard decrypt .env.encrypted --output .env

# Scan git history for committed secrets
pyguard history-scan

Commands

Command	Description
pyguard audit	Scan project files for hardcoded secrets
pyguard validate	Check all required env vars are present
pyguard export	Generate .env.example from .env
pyguard encrypt <file>	AES-256 encrypt an env file
pyguard decrypt <file>	Decrypt an encrypted env file
pyguard history-scan	Scan git log for leaked secrets
pyguard init	Create .env.schema from existing .env

Schema File

Define which env vars are required vs optional:

# .env.schema
DATABASE_URL:
  required: true
  description: "PostgreSQL connection string"

SECRET_KEY:
  required: true
  description: "App secret key, min 32 chars"
  min_length: 32

DEBUG:
  required: false
  default: "false"
  description: "Enable debug mode"

REDIS_URL:
  required: false
  description: "Redis connection string for caching"

Run pyguard validate and get clear output:

✅  DATABASE_URL     — present
✅  SECRET_KEY       — present (length: 64)
✅  DEBUG            — using default: false
⚠️  REDIS_URL        — missing (optional, caching disabled)

All required variables are set.

Audit Output Example

$ pyguard audit

🔍 Scanning project files...

⚠️  Potential secrets found:

  config/settings.py:14
    API_KEY = "sk-proj-abc123..."   ← hardcoded string

  utils/db.py:8
    password="admin123"             ← hardcoded credential

📋 Summary: 2 issues found in 2 files.
Run `pyguard audit --fix` to replace with env var references.

Project Structure

pyguard/
├── pyguard/
│   ├── cli.py          # CLI entry point (Click)
│   ├── audit.py        # Secret scanning logic
│   ├── validator.py    # Schema validation
│   ├── crypto.py       # AES encryption/decryption
│   ├── exporter.py     # .env.example generator
│   └── scanner.py      # Git history scanner
├── tests/
├── pyproject.toml
└── README.md

Contributing

Issues and PRs welcome. Please run tests before submitting:

pytest tests/ -v

License

MIT © Robbian Saputra Gumay