Usage¶

pipguard demo

Basic Usage¶

Install a single package¶

pipguard install requests

pipguard will download, scan, and — if clean — install the package. No output means no findings.

Install from requirements.txt¶

pipguard install -r requirements.txt

Scans all packages in the file. Blocks on first CRITICAL or HIGH finding.

CI Mode¶

In CI, you never want interactive prompts. Use --yes to suppress all confirmation prompts and have pipguard exit 1 automatically on CRITICAL or HIGH findings:

pipguard install --yes -r requirements.txt

GitHub Actions

$pipguard install --yes -r requirements.txt

✓ requests==2.31.0

✓ numpy==1.26.3

✗ litellm==1.82.8 CRITICAL — .pth autorun, reads ~/.ssh/id_rsa

Process exited with code 1

Allowing Known-Legitimate Packages¶

Some packages legitimately access credential stores (e.g. paramiko reads ~/.ssh). Use --allow to reduce their finding from HIGH to MEDIUM:

pipguard install --allow paramiko paramiko

CRITICAL findings are never reduced

--allow only reduces HIGH → MEDIUM. CRITICAL findings always block, regardless of flags.

Forcing a Package (Escape Hatch)¶

For known false-positives on fully-trusted internal packages:

pipguard install --force my-trusted-internal-pkg

Use with care

--force bypasses all checks and logs a warning. Never use in CI without code review.

Allowing sdist Packages¶

By default pipguard exits with code 2 if a package falls back to sdist (source distribution), because sdists execute build scripts. To opt in:

pipguard install --allow-sdist some-package

All Flags¶

Flag	Description
`-r FILE`	Install from requirements file
`--yes` / `-y`	CI mode — no prompts, exit 1 on CRITICAL/HIGH
`--allow PKG`	Add package to per-invocation allowlist (HIGH→MEDIUM)
`--force PKG`	Bypass all checks for a specific package
`--allow-sdist`	Allow sdist fallback (with warning)

Exit Codes¶

Code	Meaning
`0`	Clean — all packages installed
`1`	Blocked — CRITICAL or HIGH risk detected
`2`	Scan error — download failed or unsupported format