What it does

secret-guard scans source files for hardcoded credentials using 13 pattern rules plus Shannon-entropy detection, and reports each finding with a severity and a masked value. By default it never prints the secret itself.

On top of pattern matching, secret-guard catches .env files with secret-looking variable names (.env, .env.local, prod.env, …). It reports the key name and severity but never the value.

Features

• Zero runtime dependencies — pure Python, no network calls.
• Masked by default — secret values are redacted in console and JSON output; --show-value is an explicit opt-in for recovery/rotation work.
• Git-aware --staged: scans the git index blob, not the working tree, so it catches secrets that are staged but already deleted from disk.
• gitignore-aware: skips .git, node_modules, venv, and whatever your .gitignore already covers; repeatable --exclude for anything else.
• Entropy detection: flags high-entropy strings even when no rule matches.
• Fast, single-file install: works in CI in one line.

Install

pip install secret-guard-scan

The CLI is secret-guard. You can also run the repo without installing (Python ≥ 3.8):

python -m secretguard

Quick start

# Scan the current directory
secret-guard scan

# Scan a specific path
secret-guard scan ./src

# JSON output for CI / tooling
secret-guard scan --json

# Only files staged for commit (reads the git index)
secret-guard scan --staged

# Guard every future commit with a git pre-commit hook
secret-guard install-hook

Example output

config.py:12 [HIGH    ] GitHub Token: ghp_**************
.env:4    [CRITICAL] Private Key: -----BEGIN [REDACTED]-----
app.py:40 [MEDIUM  ] Credential Assignment: password = 'hunter 2'

1 critical, 1 high, 1 medium, 0 low — 3 total

Values are masked by default. Use --show-value only when you actually need the full string — for example, to rotate the key you just found.

Usage

secret-guard scan [path] [options]

positional arguments:
  path              Path to scan (default: .)

options:
  --exclude DIR     Skip additional directory names (repeatable)
  --no-entropy      Disable high-entropy string detection
  --json            Output findings as JSON
  --show-value      Print full secret values (default masks them)
  --staged          Scan only files staged in git

Exit codes

• 0 — no secrets found, or --help/--version
• 1 — at least one secret detected (or an error occurred)

Use this in CI — the job fails the moment a secret shows up:

- name: Scan for secrets
  run: |
    pip install secret-guard-scan
    secret-guard scan . \
      --json \
      --exclude tests \
      --exclude .venv

Staged scanning

secret-guard scan --staged

reads each staged file directly from the git index (git show :<path>). This matters when a secret was added, staged, and then deleted from the working tree: a worktree-only scan would miss it, but the staged version caught by secret-guard is exactly what would otherwise be committed.

Local development

python -m unittest discover -s tests
python -m ruff check secretguard tests
python -m secretguard scan . --exclude tests --no-entropy

The repository enforces these in CI (tests on Python 3.9 / 3.11 / 3.13, lint, and a self-scan job) and runs GitGuardian on every pull request.

Contributing

Contributions of any size are welcome — new detection rules, false-positive reports, docs, editor integrations. Start with CONTRIBUTING. Please read our Code of Conduct and report security issues per our Security Policy.

Roadmap

• Rule-based detection (cloud keys, tokens, private keys)
• Entropy-based heuristics
• .env support (.env, .env.*, *.env, *.env.*)
• Masked output by default
• Git-index-aware --staged scanning
• git hook + pre-commit integration
• OIDC trusted publishing to PyPI
• Git history scanning
• Baseline / allowlist support
• SARIF output for GitHub code scanning
• Custom rule manifests

License

MIT