holtzman 0.1.0

Defensive, local-first secret-leak scanner for AI/LLM API keys — finds your own leaks; never validates, pools, or stores a key.

Holtzman

A local-first secret-leak scanner that finds your own leaked AI/LLM API keys — and never validates, pools, uses, or stores them.

Holtzman scans your own code and repositories for exposed API keys (OpenAI, Anthropic, Google AI, AWS, Groq, and more), reports masked findings with their locations, and hands you a per-provider revoke + rotate playbook. It is deliberately the ethical inverse of credential-harvesting tools: no key validation, no pooling, no stealth/evasion, and it never writes a secret to disk in cleartext.

In Dune, the Holtzman effect generates the defensive shield. Same idea.

Why Holtzman is different

"Find the secret" power can point two ways. Holtzman only points inward:

Holtzman does	Holtzman never does
Scan your own repos + local code	Search the world for other people's keys
Store a masked fragment + SHA-256 hash	Store key cleartext
Print revoke + rotate guidance	Validate, use, or pool a key
Read-only own-asset enumeration	Tor / proxy / evasion

These are enforced as safety invariants — tests fail the build if any is violated.

Features

• Curated AI-key pack — 12 providers / 15 prefix-anchored patterns (OpenAI, Anthropic, OpenRouter, Perplexity, xAI, Groq, Google AI, AWS, Hugging Face, Replicate, NVIDIA, Fireworks), with sk- prefix disambiguation and context scoring. Broad prefix-less formats are deliberately excluded to keep precision high.
• Own-asset GitHub scanning — your repositories' current code and commit history (deleted lines, where rotated-out keys hide).
• Local path scanning — files or directories, with sensible skip dirs.
• Disclosure reports — Markdown, JSON, and SARIF. Masked fragments only.
• Remediation playbooks — per-provider revoke + rotate steps, git-history purge, and monitoring guidance. Prints; touches nothing.
• Baseline allowlist + --ci — accept known findings, fail CI only on new leaks.
• Pre-commit hook + GitHub Actions — ready-to-use integrations (SARIF upload included).
• Hybrid detection — the precise pattern engine by default, with an optional gitleaks engine for full-spectrum breadth.

Install

pip install holtzman          # once published to PyPI
# or, from source:
git clone https://github.com/r3b3Lli0uskID/holtzman-p
cd holtzman && pip install -e .

Requires Python 3.12+.

Quickstart

# Scan local code (own-asset)
holtzman scan .

# Scan your own GitHub repos, including commit history
export HOLTZMAN_GITHUB_TOKEN=...        # a read-only token for your repos
holtzman github --owner <your-login> --include-history

# Reports & remediation
holtzman report --format md             # or json | sarif
holtzman disclose --out disclosure.md   # responsible-disclosure report
holtzman rotate --provider openai       # print the revoke+rotate playbook

# Baseline + CI gating
holtzman baseline --out .holtzman-baseline.json
holtzman scan . --baseline .holtzman-baseline.json --ci   # non-zero exit on NEW findings

Configuration

Settings load from the environment or a local .env (prefix HOLTZMAN_):

Variable	Purpose
HOLTZMAN_GITHUB_TOKEN	Read-only token to enumerate your own repos. Only ever sent to the GitHub API; never carries a found secret.
HOLTZMAN_GITHUB_OWNER	Default account/org for holtzman github (or pass --owner).
HOLTZMAN_DB_PATH	SQLite findings DB (default holtzman.db).

Safety invariants

These hold in code review and are covered by tests:

1. No key cleartext is ever stored — findings keep a masked fragment + SHA-256 hash only; the DB has no cleartext column.
2. No outbound call carries a found secret — GitHub enumeration is read-only and sends only your own token.
3. No evasion dependencies — no Tor/SOCKS/proxy stack; no stealth config.
4. Zero live validations — there is no validate/rotate/keypool/pool/stealth module. Holtzman tells you a key is exposed; it never checks whether it works.

CI & pre-commit

# .pre-commit-config.yaml
- repo: https://github.com/r3b3Lli0uskID/holtzman-p
  rev: v0.1.0
  hooks:
    - id: holtzman

A ready-made GitHub Actions workflow (scan + SARIF upload) lives in .github/workflows/secret-scan.yml.

Responsible use

Holtzman is for scanning assets you own or are explicitly authorized to assess, and for responsible disclosure of exposures you find. It never validates or uses a discovered key — when you find one, revoke and rotate it (the rotate command tells you how). Do not point it at third parties' assets without authorization. See SECURITY.md.

Development

pip install -e ".[dev]"
ruff check holtzman tests
pytest --cov=holtzman

License

MIT.