secretscreen

Detect and redact secrets in key-value pairs, dicts, and environment variables.

Best-effort defense-in-depth. Not a security boundary.

Install

As a library:

pip install secretscreen

As a command-line tool — pipx or uv keep it in its own environment and put secretscreen on your PATH everywhere, rather than only in whichever venv is active:

pipx install secretscreen
uv tool install secretscreen

Zero dependencies, Python 3.11+.

Quick start

from secretscreen import redact_pair, redact_dict, audit_dict, Mode

# Single pair
redact_pair("DB_PASSWORD", "hunter2")  # → "[REDACTED]"
redact_pair("APP_NAME", "myapp")  # → "myapp"

# Dict with recursion
redact_dict({"db": {"password": "x", "host": "localhost"}})
# → {"db": {"password": "[REDACTED]", "host": "localhost"}}

# Aggressive mode (adds entropy detection)
redact_dict(env, mode=Mode.AGGRESSIVE)

# Audit mode (structured findings, no mutation)
findings = audit_dict(env)
# → [Finding(key="DB_PASSWORD", reason="key_pattern:password", ...)]

# Custom safe suffixes (keys ending with these are never redacted)
redact_dict(env, safe_suffixes=("_config", "_enabled"))

Command line

The library only helps Python callers. The CLI covers the shell side — docker exec, Makefiles, CI logs, anything you are about to paste somewhere.

secretscreen tandoor.env                    # redact and print, cat-like
docker exec app env | secretscreen          # scrub a stream before it hits your terminal
secretscreen --audit config.json            # findings only, no values, exit 1 if any

secretscreen [FILE...]              reads stdin when FILE is omitted or '-'
  --audit                           report findings without values; exit 1 if any
  --format env|json|ini|dsn|auto    default: auto-detect from extension, then content
  --aggressive                      add entropy detection; more false positives
  --replacement TEXT                default: [REDACTED]

Redaction is structural, not line-based: it parses the format, so it catches DB_PASSWORD=hunter2 on the key name and rewrites postgres://admin:s3cr3t@host/db to postgres://admin:[REDACTED]@host/db without destroying the rest of the line. Comments, blank lines, quoting, export prefixes, INI sections and : separators all survive the round trip.

What the exit code means:

That third case is the one that matters. This is best-effort defense-in-depth, and a cat-replacement is exactly the tool people stop thinking about, so the CLI never prints unparsed content verbatim: a line it cannot structure is replaced with the redaction token, named on stderr, and turns the exit code non-zero. The same applies to values above the 64 KB detection cap — they are reported as unscanned rather than passed off as clean.

If you are scanning a git repository rather than config-shaped data, use gitleaks instead. That is a different job.

Detection layers

1. Key-name denylist — substring match against ~30 known secret key patterns
2. Structured value parsing — JSON, Python literals, DSN, INI, URL query params
3. Value-format detection — 222 known formats via vendored gitleaks patterns (MIT)
4. URL credential detection — partial redaction of user:pass@host URLs
5. Entropy detection — Shannon entropy for machine-generated strings (aggressive mode only)

Contributing

Bug reports and pull requests welcome. See CONTRIBUTING.md.

Support

If you find secretscreen useful, consider buying us a coffee.

License

MIT. Gitleaks patterns are also MIT-licensed.