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.

Why secret-guard?

There are plenty of secret scanners. Here is where secret-guard sits among the popular ones:

What makes secret-guard different:

1. Zero dependencies, zero build step — a single pip install secret-guard-scan is all it takes, in CI or on a laptop. No Go toolchain, no Docker image, no giant dependency tree to audit.
2. Values are masked by default — including in .env files, where the key name is reported but the value is never printed, even with --show-value.
3. Git-index-aware --staged — scans the staged blob (git show :<path>), so a secret staged and then deleted from the worktree is still caught.
4. True false-positive controls — --skip-rule and --only-rule scope a scan to exactly the rules you care about, and unknown rule ids fail the scan instead of being silently ignored.

For teams that already run gitleaks in CI, secret-guard is a natural complement: a zero-install first line of defense in every pre-commit hook and every pip install-only CI job.

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
  --skip-rule RULE  Never run the given rule id (repeatable)
  --only-rule RULE  Run only the given rule id (repeatable)
  --list-rules      List every available rule id and exit

Taming false positives

Rule-based scanners are only useful when reviewers trust them. Use --skip-rule and --only-rule to scope a scan to exactly the rules you care about:

# Ignore a noisy rule entirely (e.g. GENERIC_SECRET_KEY on a test repo)
secret-guard scan . --skip-rule generic-secret-key

# Enforce only secrets that matter on a given path
secret-guard scan ./infra --only-rule aws-access-key-id --only-rule github-token

# See every rule id a scan can run
secret-guard scan --list-rules

Passing an unknown rule id fails the scan with exit code 2 — so a typo'd --skip-rule can never silently disable detection.

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. See our Contributors list for everyone who has helped. 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