piitools

Developer workstation PII and secret scrubbing toolkit.

Gitleaks, TruffleHog, and detect-secrets cover your git repos. piitools covers everything else on your local machine — shell history, config files, clipboard history — the surfaces where credentials leak but nobody's scanning.

Installation

# With uv (recommended)
uv tool install piitools

# With pipx
pipx install piitools

# From source
git clone https://github.com/laplaque/piitools.git
cd piitools
uv sync

Quick start

# Dry run — see what would be scrubbed
piitools scrub-history

# Actually scrub
piitools scrub-history --apply

# Scrub bash history instead of zsh
piitools scrub-history --format bash --apply

# Use a custom patterns file
piitools scrub-history --config ~/my-patterns.toml

What it detects

The bundled pattern set covers:

Category	Examples
API keys & tokens	Bearer tokens, API keys, passwords in env vars
AWS	Access keys (AKIA...), secret keys
GCP	OAuth tokens (ya29.), API keys (AIza...)
GitHub / GitLab	ghp_/ghs_ tokens, glpat- PATs
SSH / TLS	Private keys, certificates
OAuth / CI/CD	Client IDs/secrets, OAuth2 credentials
CLI tools	glab config set key-value pairs
URLs	Credentials embedded in URLs (://user:pass@)
Hex strings	Long hex strings (48+ chars) that may be tokens

Configuration

Custom patterns

Create ~/.config/piitools/patterns.toml to add your own patterns. These extend the bundled defaults — they don't replace them.

[[patterns]]
regex = 'MY_INTERNAL_TOKEN_[A-Za-z0-9]{32}'
label = "internal service token"

[[patterns]]
regex = 'JIRA_API_KEY\s*[=:]\s*\S+'
label = "Jira API key"

Automated scrubbing (macOS)

Copy the launchd plist to run every 15 minutes:

cp contrib/com.piitools.scrub-history.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.piitools.scrub-history.plist

In-memory history reload (zsh)

Scrubbing the file doesn't clear your shell's in-memory history. Add this to your .zshrc:

source /path/to/piitools/zsh/piitools-reload.zsh

This installs a precmd hook that detects when the history file has been scrubbed and reloads it automatically. Each shell session tracks its own reload state.

Development

uv sync
uv run pytest tests/ -v
uv run mypy src/ --strict
uv run ruff check src/ tests/

Roadmap

• Config file auditor (piitools audit-config)
• Git pre-commit hook (piitools scan-staged)
• Clipboard history scrubber
• PyPI publish

License

MIT