pipguard

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

AST-based static analysis + known CVE lookup via osv.dev.

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.

CI Integration

GitHub Actions

Use the bundled composite action to gate installs in a workflow — it fails the job on CRITICAL/HIGH findings:

- uses: shenxianpeng/pipguard@v0.2.0
  with:
    requirements: requirements.txt
    check-vulns: true        # also query OSV.dev for known CVEs (optional)

Or scan explicit packages:

- uses: shenxianpeng/pipguard@v0.2.0
  with:
    packages: "requests numpy==1.26.3"

pre-commit

Add pipguard to .pre-commit-config.yaml to scan your requirements file before every commit that changes it:

repos:
  - repo: https://github.com/shenxianpeng/pipguard
    rev: v0.2.0
    hooks:
      - id: pipguard
        # scans requirements.txt by default; override for a different file:
        # args: ['-r', 'requirements/prod.txt']

License

MIT