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 requests          # downloads, scans, then installs

pipguard would have blocked the March 2026 litellm .pth attack before install (that release has since been pulled from PyPI — see The Problem).

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.

How is this different from pip-audit?

They answer different questions — and pipguard is a superset:

pip-audit checks whether your versions have a published advisory — reactive, and blind to a brand-new attack. pipguard checks what the code actually does (reads ~/.ssh, phones home from setup.py) — catching the zero-day — and folds in the CVE check too. In a head-to-head on a credential-stealing setup.py, pip-audit reports "No known vulnerabilities found" while pipguard blocks it. Reproduce it: python benchmark/compare_pip_audit.py. See the full comparison.

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.3.0
  with:
    requirements: requirements.txt
    check-vulns: true        # also query OSV.dev for known CVEs (optional)

Or scan explicit packages:

- uses: shenxianpeng/pipguard@v0.3.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.3.0
    hooks:
      - id: pipguard
        # scans requirements.txt by default; override for a different file:
        # args: ['-r', 'requirements/prod.txt']

License

MIT