Metadata-Version: 2.4
Name: holtzman
Version: 0.1.0
Summary: Defensive, local-first secret-leak scanner for AI/LLM API keys — finds your own leaks; never validates, pools, or stores a key.
Author: r3b3Lli0uskID
License-Expression: MIT
Project-URL: Homepage, https://github.com/r3b3Lli0uskID/holtzman-p
Project-URL: Repository, https://github.com/r3b3Lli0uskID/holtzman-p
Project-URL: Issues, https://github.com/r3b3Lli0uskID/holtzman-p/issues
Project-URL: Changelog, https://github.com/r3b3Lli0uskID/holtzman-p/blob/main/CHANGELOG.md
Keywords: security,secret-scanning,secrets,api-keys,credentials,llm,ai,devsecops,sarif,gitleaks
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: httpx>=0.27
Requires-Dist: aiosqlite>=0.20
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Dynamic: license-file

# 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**](#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`](https://github.com/gitleaks/gitleaks) engine for full-spectrum breadth.

## Install

```bash
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

```bash
# 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

```yaml
# .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`](.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](SECURITY.md).

## Development

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

## License

[MIT](LICENSE).
