pipguard 0.3.4

Scan Python packages for supply chain attacks before installing them

pipguard

Python supply chain security tool. Scan packages before installing them.

pip install pipguard
pipguard install litellm==1.82.8   # Blocks the March 2026 attack. Exits 1.

Zero configuration. Zero external dependencies. Pure stdlib.

---

The Problem

The March 2026 litellm attack (97M downloads/month) embedded Python code in a .pth file — executed automatically at interpreter startup, exfiltrating SSH keys, AWS credentials, and Kubernetes configs from a single pip install.

Classical tools (pip-audit, GuardDog) are blind to zero-day attacks. They check known signatures. pipguard asks a different question:

Should any pip install be allowed to read ~/.ssh/id_rsa?

The answer is no. And that question doesn't require a database.

Installation

Install pipguard outside your project's virtualenv — this prevents untrusted package code from tampering with the scanner itself.

# Recommended: isolated, persistent install
pipx install pipguard

# CI / one-off use (no pre-install needed)
uvx pipguard install -r requirements.txt

# Standard
pip install pipguard

Usage

# Install a single package
pipguard install requests

# Install from requirements.txt
pipguard install -r requirements.txt

# CI mode: never prompts, exits 1 on CRITICAL/HIGH
pipguard install --yes -r requirements.txt

# Allow a known-legitimate package that accesses credentials
pipguard install --allow paramiko -r requirements.txt

# Override for known false-positives (use with care)
pipguard install --force my-trusted-internal-pkg

# Show full LOW/CLEAN scan details
pipguard install --verbose requests

# Show raw pip install output
pipguard install --show-pip-output requests

By default, pipguard prints a risk summary, expands CRITICAL / HIGH / MEDIUM, collapses LOW to package-level counts, and keeps successful pip install logs quiet. Use --verbose for full scan details and --show-pip-output to restore raw pip logs.

For the full reference — risk levels, exit codes, allowlist, and CI integration — see the documentation.

License

MIT