pip-cve-gate 0.1.0

Pre-install CVE gate for pip — blocks vulnerable and freshly published packages before install

pip-cve-gate

Pre-install CVE gate for pip. Blocks vulnerable and freshly published packages before any code runs on your machine.

safe-pip install flask requests django
# [pip-cve-gate] Scanning 3 package(s)…
# [pip-cve-gate] Resolved 27 package(s) (incl. transitive deps)
# [pip-cve-gate] All clear — delegating to pip

If a package is blocked:

safe-pip install somelib
# [pip-cve-gate] BLOCKED — install aborted
#   [CVE] 'somelib==1.2.3' has known vulnerabilities: GHSA-xxxx-yyyy-zzzz
#   [FRESH_HOLD] 'dep==0.0.1' was published 1d ago (hold: 3d). Use --skip-fresh-hold to override.

Exit code 0 = clean, 1 = blocked, 2 = error.

---

Why

Post-install tools (pip-audit, safety) run after pip has already downloaded and potentially executed install scripts. By then it's too late for zero-hour supply chain attacks.

pip has no native plugin hook for pre-install scanning. pip-cve-gate fills that gap with a wrapper that resolves the full dependency tree, scans every package against three independent feeds, and only delegates to real pip when everything is clean.

The closest prior art — pipask — checks PyPI advisories but lacks freshness hold and OSSF malicious package coverage. pip-cve-gate covers all three.

---

What it checks

Signal	Source	Fail behaviour
Known CVEs / advisories	OSV.dev + PyPI Advisory DB	Block
OSSF malicious packages	ossf/malicious-packages	Block
Freshness hold (default 3d)	PyPI upload timestamp	Block (overridable)

Network failures fail open — a broken feed never blocks your CI.

---

Install

pip install pip-cve-gate

Or run directly from the repo without installing:

git clone https://github.com/sharkyger/pip-cve-gate
cd pip-cve-gate
python bin/safe-pip install flask

---

Usage

safe-pip accepts the same arguments as pip install:

safe-pip install flask
safe-pip install "django>=4.2" "celery==5.3.6"
safe-pip install flask --skip-fresh-hold   # bypass freshness hold

Non-install subcommands are passed through unchanged:

safe-pip list
safe-pip show flask
safe-pip uninstall flask

Configuration

Variable	Default	Description
PIP_CVE_GATE_FRESH_HOLD_DAYS	3	Days a new release must age before install
PIP_CVE_GATE_TIMEOUT	10	HTTP timeout in seconds
PIP_CVE_GATE_MAX_DEPTH	5	Max transitive dependency depth
PIP_CVE_GATE_PIP_BIN	pip	Path to real pip binary

---

Part of the safe-install fleet

pip-cve-gate is part of a pre-install CVE gate fleet for different package ecosystems:

Ecosystem	Tool
Homebrew	homebrew-safe-upgrade
Composer (PHP)	composer-cve-gate
pip (Python)	pip-cve-gate ← you are here

---

Development

git clone https://github.com/sharkyger/pip-cve-gate
cd pip-cve-gate
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -v
ruff check src/ tests/

---

License

MIT — see LICENSE.