venvy — Offline Python Supply-Chain Security Audit for Every Virtual Environment

venvy knows where every Python virtual environment on your machine is — then it audits them for known-vulnerable and malicious packages (fully offline, deterministic, CI- and AI-agent-ready) and reclaims the disk space they waste by deduplicating identical files. It also doubles as a lightweight environment manager (registry, checkpoints, safe installs).

Keywords: python security audit · vulnerable package scanner · malicious PyPI package detection · offline CVE scanner · supply-chain security · typosquatting detection · pip-audit alternative · virtual environment manager · OSV database · CI dependency scanning · venv disk space · deduplicate virtual environments · hardlink dedup · reclaim disk space python.

Table of Contents

• Why venvy
• What venvy detects
• Reclaim disk space
• Installation
• Quick start
• Command reference
• Exit codes
• JSON output (for CI & AI agents)
• How it works
• venvy vs pip-audit vs safety
• Virtual-environment management
• FAQ
• Coverage & limitations
• Contributing
• License

Why venvy

Most Python security scanners audit one project at a time, need the network, and only look for CVEs. venvy fills the gap none of them cover at once:

Built for the AI-coding era. An LLM cannot be trusted to answer "is this package safe?" — it will hallucinate a CVE. venvy is a deterministic ground-truth lookup an agent can call (venvy audit --json) and rely on.

What venvy detects

Correctness-first by design: anything that cannot be confidently evaluated is reported as unknown, never as "safe." A false "you're clean" is treated as a critical bug.

Reclaim disk space

Every virtual environment stores its own byte-for-byte copy of the same wheels. Ten environments with numpy store numpy ten times. AI coding agents make this dramatically worse — every throwaway project spawns another environment full of the same libraries.

venvy dedup finds files that are provably identical across your environments and collapses them onto one inode using hardlinks. Nothing is deleted. Every environment keeps working.

venvy dedup            # read-only: show what could be reclaimed
venvy dedup --apply    # collapse duplicates into hardlinks
venvy dedup --json     # machine-readable

18.2 MB reclaimable across 3 environment(s) (659 duplicate group(s), 1879 files scanned)
reclaimable  size      copies  file
1.1 MB       226.6 KB  6       pyparsing.py
410.8 KB     136.9 KB  4       _emoji_codes.py
320.0 KB     64.0 KB   6       cli-32.exe

That's a real measurement on three small environments — roughly a quarter of their total size. It also catches intra-environment waste (pip and setuptools each vendor their own copy of pyparsing). Machines with several ML environments have far more to gain, since every copy of a large wheel collapses to one.

How it stays safe — a dedup tool that corrupts an environment is worse than no dedup tool:

Verified end-to-end on real environments: 8.9 MB reclaimed across 374 files, both environments still importing and running pip afterwards, with every unlinked file accounted for.

Installation

pip install venvy

Requires Python 3.8+. Works on Windows, macOS, and Linux — the full test suite runs on all three across Python 3.8–3.13 in CI on every commit. No compiler, no heavyweight dependencies.

Quick start

# Audit every known environment on your machine.
# On first run, venvy downloads a one-time advisory database (~30MB).
# Every scan after that is fully offline.
venvy audit

# Audit a single environment
venvy audit --env .venv

# Machine-readable output for CI or an AI agent
venvy audit --json

# Update the advisory database, then scan
venvy audit --refresh

# Never touch the network; fail if no local database exists (deterministic CI)
venvy audit --offline

Example output:

vulnerabilities found - 1 app package(s) affected across 2 env(s) (+4 toolchain)
scanned 17 packages (16 unique) in 61ms
advisory database: 0.1 days old

/path/to/project/.venv
   package  version  advisory             severity  fix
*  pytest   8.4.2    GHSA-6w46-j5rx-g56g  MODERATE  9.0.3

  + 19 toolchain finding(s) (pip/setuptools/wheel) - --include-toolchain to show

Command reference

Security audit

Toolchain handling: pip, setuptools, and wheel ship in nearly every venv and carry many advisories. They are always reported but excluded from the exit-code gate by default, so a stale bundled pip never buries a real application-dependency finding. Use --include-toolchain to gate on them too.

Disk-space reclamation

Environment management

Add --json to any command for structured output.

Exit codes

venvy returns semantic exit codes so scripts, CI gates, and agents can branch on the result without parsing text.

Precedence: malicious (21) > vulnerable (20) > stale/partial (22) > clean (0).

# Example CI gate: fail the build on vulnerable OR malicious findings
venvy audit --offline --json
code=$?
if [ "$code" = "20" ] || [ "$code" = "21" ]; then exit 1; fi

JSON output (for CI & AI agents)

venvy audit --json emits a stable, versioned schema. Key fields:

Unknowns and errors are first-class arrays — they are never omitted, so automation can distinguish "clean" from "could not determine."

How it works

1. Enumerate every environment from venvy's local registry (plus optional on-disk discovery).
2. Read each environment's installed packages directly from *.dist-info metadata — text only, no subprocess, and never importing the scanned package (importing a malicious package would run its code).
3. Match each name==version against a local, prebuilt advisory database using exact PEP 440 version-range evaluation. No network, no randomness, no model.
4. Report findings with the honest headline count, malicious-first, with fix versions.

Advisory data is compiled offline into a single SQLite index from:

The database ships as one snapshot; venvy audit --refresh rebuilds it. venvy never publishes an empty or corrupt database over a working one, and refuses to scan against an unusable database (fail-closed to exit 23) rather than reporting a false "clean."

venvy vs pip-audit vs safety

Comparison reflects the default, freely available behavior of each tool. pip-audit and safety are excellent CVE scanners; venvy's edge is the offline, machine-wide, malicious-aware, agent-native combination.

Virtual-environment management

venvy started as an agent-safe environment manager and still is one. It keeps a local SQLite registry of your environments and supports safe, idempotent workflows:

venvy ensure --python 3.11 --json          # create/verify an environment
venvy safe-install requests flask --json   # install with auto-rollback on failure
venvy checkpoint --name "before-refactor"  # snapshot before risky changes
venvy rollback --latest                     # restore if something breaks
venvy ls --json                             # list all environments

FAQ

Is venvy audit really offline? Yes. The scan itself never touches the network. The only online step is the one-time advisory-database download (or --refresh). Use --offline to hard-fail if no local database exists.

How is this different from pip-audit? pip-audit is a strong per-project, online CVE scanner. venvy adds three things it does not do by default: it scans every environment at once, it works offline, and it detects malicious/typosquat packages — not just CVEs.

Does it run any code from the packages it scans? No. venvy reads *.dist-info metadata as text. It never imports a scanned package or runs pip inside the target environment.

Can my AI agent use it? Yes — that is a primary design goal. venvy audit --json returns a deterministic, versioned report with semantic exit codes, so an agent gets ground truth instead of a hallucinated answer.

Which Python versions and OSes are supported? Python 3.8+ on Windows, macOS, and Linux.

Does it audit Conda environments? It audits the pip-installed packages inside any environment (including Conda envs). Conda-channel packages are out of scope for now.

Coverage & limitations

venvy is deliberately honest about what it does not cover. Each known gap is tracked as an open issue — contributions welcome, see all open issues.

Also worth knowing:

• No scanner catches a novel supply-chain 0-day. venvy matches against known advisories. Pair it with dependency cooldowns and least-privilege dev environments.
• Advisory data ages between refreshes. venvy prints the database age on every run and degrades the exit code when it is stale, rather than silently presenting old data as current.
• Brand-new or already-yanked malicious packages may not appear in the feeds yet.

Contributing

git clone https://github.com/pranavkumaarofficial/venvy
cd venvy
pip install -e ".[dev]"
pytest            # run the test suite
venvy audit       # try it locally

Issues and pull requests are welcome. If you find a false positive or a false negative in the matcher, please open an issue with the package, version, and advisory ID — those become permanent regression tests.

Looking for something to work on? The known gaps in Coverage & limitations are filed as issues tagged help wanted — each one includes the context, the proposed approach, and exactly which files to start in:

• #3 Expand malicious-package coverage — highest impact
• #4 Speed up --scan discovery
• #5 Audit Conda-channel packages
• #6 Benchmark at 50–100 environments

CI runs the full suite on Windows, macOS, and Linux across Python 3.8–3.13 for every push and PR.

License

MIT © Pranav Kumaar