https://github.com/shenxianpeng/pipguard

Block the attack before it lands.
https://github.com/shenxianpeng/pipguard

guard pip pip-audit pipguard vulnerabilities

Last synced: 26 days ago
JSON representation

Block the attack before it lands.

• Host: GitHub
• URL: https://github.com/shenxianpeng/pipguard
• Owner: shenxianpeng
• License: mit
• Created: 2026-03-25T07:52:41.000Z (3 months ago)
• Default Branch: main
• Last Pushed: 2026-05-13T11:13:21.000Z (about 1 month ago)
• Last Synced: 2026-05-13T13:18:23.235Z (about 1 month ago)
• Topics: guard, pip, pip-audit, pipguard, vulnerabilities
• Language: Python
• Homepage: https://shenxianpeng.github.io/pipguard/
• Size: 1.09 MB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE
  • Security: docs/security-gap-assessment.md

Awesome Lists containing this project

README

          


  



# pipguard

[![PyPI - Version](https://img.shields.io/pypi/v/pipguard)](https://pypi.org/project/pipguard/)

[![codecov](https://codecov.io/gh/shenxianpeng/pipguard/graph/badge.svg)](https://codecov.io/gh/shenxianpeng/pipguard)

[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://shenxianpeng.github.io/pipguard/)

[![Python Version](https://img.shields.io/pypi/pyversions/pipguard)](https://pypi.org/project/pipguard/)

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

```bash

pip install pipguard

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

```

Zero configuration. Zero external dependencies. Pure stdlib.

![pipguard demo](https://raw.githubusercontent.com/shenxianpeng/pipguard/main/docs/assets/demo.gif)

---

## 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.

```bash

# 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

```bash

# 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](https://shenxianpeng.github.io/pipguard/)**.

## License

MIT