pipsentinel 0.2.3

Hack-proof pip: supply chain security checks + import sandbox before every install

pipsentinel

Hack-proof pip. Supply chain security checks + import sandbox before every package install.

---

PyPI packages can be hijacked, tampered in transit, or silently backdoored through malicious wheels that pass every standard integrity check. pipsentinel intercepts the install flow, runs a full security suite before touching disk, and blocks anything suspicious.

---

What it catches

Check	What it detects
Git tag divergence	Version on PyPI with no matching GitHub tag
.pth file scan	Wheels with import in .pth files — auto-executes on every Python start
Obfuscated code	exec(base64.b64decode(...)), double encoding, AST-level dynamic exec
Multi-source hash consensus	PyPI JSON API + Simple API + direct download — all three SHA-256s must agree
RECORD manifest integrity	Every file in the wheel vs its declared SHA-256
Release timestamp delta	PyPI upload vs git tag creation time — under 1 min = suspicious
PyPI provenance	OIDC attestation — published from reproducible CI?
Lockfile verification	Wheel SHA-256 against ~/.pipsentinel/pipsentinel.lock — zero network on repeat installs
Import sandbox	import <pkg> in isolated subprocess — no credentials, audit hook on all syscalls
Honeypot bait	Fake AWS/SSH/Kube/GCP credentials in sandbox — read bait + network call = caught
Post-install RECORD diff	What pip wrote to disk vs what RECORD declared
Post-install .pth audit	Scans site-packages after install for suspicious .pth files

Zero third-party dependencies. pipsentinel uses only the Python standard library. It has no supply chain of its own to attack.

---

Install

pip install pipsentinel

Bootstrap trust note: The codebase is ~2,600 lines of stdlib-only Python — auditable in an afternoon. Read it before trusting it.

---

CLI

# Check AND install — blocks on any critical failure
pipsentinel install requests
pipsentinel install numpy==1.26.4

# Check only — no install
pipsentinel check somepackage==1.0.0
pipsentinel check requests --json

# Audit current environment for suspicious .pth files
pipsentinel audit

Clean package

🔍 pipsentinel: checking requests==2.31.0 ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  pipsentinel Security Report
  Package : requests==2.31.0
  Risk    : LOW
  Verdict : ✅ SAFE TO INSTALL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ PASSED CHECKS:
   • [git_tag_divergence] PyPI version 2.31.0 has a matching git tag 'v2.31.0' ✓
   • [pth_files_in_wheel] No suspicious .pth files found.
   • [wheel_record_integrity] RECORD integrity verified: all 23 declared files match.
   • [obfuscated_code] No obfuscation patterns detected.
   • [sandbox_import] Sandbox clean: import completed (0.30s) — no network calls,
                      file reads, or subprocess spawns.

🔒 Lock entry written: ~/.pipsentinel/pipsentinel.lock
📦 Installing: requests==2.31.0 --hash=sha256:58cd2187...
✅ requests==2.31.0 installed and verified.

Malicious package (blocked)

🔍 pipsentinel: checking badpkg==2.0.0 ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  pipsentinel Security Report
  Package : badpkg==2.0.0
  Risk    : CRITICAL
  Verdict : 🚨 DO NOT INSTALL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🚨 CRITICAL FAILURES:
   • [git_tag_divergence] No git tag found for 2.0.0 — pushed to PyPI
     without a corresponding source release.
   • [pth_files_in_wheel] MALICIOUS .pth FILE DETECTED: badpkg_init.pth
     contains 'import' statements — executes on every Python process start.
   • [obfuscated_code] exec(base64.b64decode(...)) in badpkg_init.pth.
     Double base64 encoding detected.
   • [sandbox_import] SUBPROCESS SPAWNED ON IMPORT: 1 child process spawned.
     Legitimate packages do not spawn processes at import time.

🚫 Installation BLOCKED.

---

User flow

flowchart TD
    START(["pipsentinel install pkg==ver"])
    META["Fetch PyPI metadata\n(name, version, wheel URLs)"]
    LOCK_HIT{"Lockfile\nhit?"}
    LOCK_VERIFY["Verify wheel SHA-256\nagainst local lock"]
    LOCK_FAIL(["BLOCKED\nlockfile mismatch"])
    FULL_SUITE["Run full check suite"]

    subgraph CHECKS ["Pre-install checks"]
        C1["① Multi-source hash consensus\nJSON API + Simple API + download"]
        C2["② RECORD manifest integrity\nevery file vs declared SHA-256"]
        C3["③ Obfuscated code\nregex + AST scan of .py / .pth"]
        C4["④ .pth file scan\nimport lines = auto-exec malware"]
        C5["⑤ Git tag divergence\nPyPI version exists on GitHub?"]
        C6["⑥ Timestamp delta\npublish before / <1 min after tag?"]
        C7["⑦ PyPI provenance\nOIDC attestation present?"]
    end

    REPORT["SecurityReport\nSAFE / MODERATE / CRITICAL"]
    GATE{"Critical\nfailures?"}
    BLOCKED(["BLOCKED\ninstallation aborted"])
    WRITE_LOCK["Write lockfile entry\nwheel SHA-256 + per-file RECORD"]
    PIP["pip install\n--require-hashes sha256:..."]

    subgraph POST ["Post-install audit"]
        P1["RECORD diff\ndisk vs declared files"]
        P2[".pth audit\nscan site-packages"]
    end

    DONE(["✅ Installed and verified"])
    ALERT(["🚨 POST-INSTALL ANOMALY\nRotate credentials"])

    START --> META
    META --> LOCK_HIT
    LOCK_HIT -- yes --> LOCK_VERIFY
    LOCK_VERIFY -- mismatch --> LOCK_FAIL
    LOCK_VERIFY -- ok --> PIP
    LOCK_HIT -- no --> FULL_SUITE
    FULL_SUITE --> C1 & C2 & C3 & C4 & C5 & C6 & C7
    C1 & C2 & C3 & C4 & C5 & C6 & C7 --> REPORT
    REPORT --> GATE
    GATE -- yes --> BLOCKED
    GATE -- no --> WRITE_LOCK
    WRITE_LOCK --> PIP
    PIP --> POST
    P1 & P2 --> DONE
    P1 & P2 -- anomaly --> ALERT

---

Python API

from pipsentinel import safe_install, SecurityReport

# Full check suite + install
report = safe_install("requests", version="2.31.0")
print(report.safe_to_install)  # True
print(report.risk_level)       # "LOW"
print(report.to_json())        # machine-readable for CI

# Check only — no install
from pipsentinel import (
    fetch_package_metadata,
    check_git_tag_divergence,
    check_pth_files_in_wheel,
    check_obfuscated_code,
    check_sandbox_import,
    SecurityReport,
)
import urllib.request

meta = fetch_package_metadata("somepackage", "1.0.0")
wheel = next(w for w in meta.wheel_urls if w["filename"].endswith(".whl"))
with urllib.request.urlopen(wheel["url"]) as r:
    wheel_bytes = r.read()

report = SecurityReport(meta.name, meta.version)
report.results = [
    check_git_tag_divergence(meta),
    check_pth_files_in_wheel(meta),
    check_obfuscated_code(wheel_bytes, wheel["filename"]),
    check_sandbox_import(wheel_bytes, meta.name, wheel["filename"]),
]
print(report.summary())

# Post-install audit
from pipsentinel import check_post_install_pth
result = check_post_install_pth()
if not result.passed:
    for f in result.detail["suspicious_files"]:
        print(f"🚨 Suspicious: {f['path']}")

CI/CD

# .github/workflows/deps.yml
- name: Secure install
  run: |
    pip install pipsentinel
    cat requirements.txt | xargs -n1 pipsentinel install
    pipsentinel audit
    # exits 1 on critical failure → blocks the workflow

---

How the checks work

Git tag divergence

Queries the GitHub Tags API and checks whether the PyPI version maps to any tag (1.2.3, v1.2.3, release-1.2.3). A version published to PyPI without a corresponding git tag is a strong signal of a credential-stolen push — no legitimate release process skips tagging.

.pth file scan

Downloads the wheel into memory, verifies its SHA-256, then inspects every .pth file for lines starting with import. Python's site module executes these on every interpreter startup — including pip, python -c, and IDE language servers. A .pth file with import has essentially no legitimate use.

Obfuscated code detection

Scans every .py and .pth file using both regex and Python's own ast module. Catches exec(base64.b64decode(...)), double-encoded blobs, eval(compile(...)), large embedded base64 payloads, subprocess self-spawning in .pth files, and exec() with computed non-literal arguments. Tuned to avoid false positives on legitimate patterns like __import__(package) in loops.

Multi-source hash consensus

Three independent paths to the same SHA-256 — PyPI's JSON API, PyPI's Simple API (PEP 503), and a direct download-and-hash. All must agree. A MITM or compromised CDN would serve a different hash via one path.

RECORD manifest integrity

Verifies the wheel's internal chain of custody: every file in <pkg>.dist-info/RECORD must match its declared SHA-256. No RECORD, or a mismatching one, indicates tampering.

Release timestamp delta

Compares git tag creation time against PyPI upload time. Upload before the tag = critical. Upload under 1 minute after tagging = warning (legitimate CI build+upload takes 2–5 min; under 1 min means the upload almost certainly happened before CI could start).

Import sandbox

Runs import <pkg> in a subprocess with stripped credentials, a fake home directory, and sys.addaudithook monitoring all socket and subprocess calls. Python is started with -S (skip automatic site processing), then site.addpackage() is called after the hook installs — so .pth payloads fire inside the hook's scope. Hard-kills after timeout (default 10s).

Packages with transitive dependencies that fail to import in the stripped environment are reported as info (not a warning) — the sandbox observed no suspicious behaviour, it simply couldn't complete the import due to missing deps.

Honeypot bait

Populates the sandbox's fake home with realistic-format credentials:

File	Content
~/.aws/credentials	AKIA + 16-char key ID, 40-char secret
~/.ssh/id_rsa	Valid PEM header/footer, random body
~/.kube/config	Real YAML structure, fake bearer token
~/.config/gcloud/application_default_credentials.json	Real JSON schema, fake refresh token
~/.env	OPENAI_API_KEY, ANTHROPIC_API_KEY, DATABASE_URL

Credentials are unique per run and cryptographically useless — they fail real authentication. If the package reads one of these files and then makes a network call within 5 seconds, pipsentinel flags the sequence as a credential stealer. This catches the env-var-conditional attack class — malware that checks os.environ.get('AWS_ACCESS_KEY_ID') before acting, which evades sandboxes with empty environments.

Lockfile

First install stores the wheel's SHA-256 and per-file RECORD in ~/.pipsentinel/pipsentinel.lock. Repeat installs verify locally — no network for hash checks. Wheel changed since locking = blocked.

---

Performance

Measured against live PyPI:

Scenario	Wall time
Single package (mean)	~487ms
10 packages, serial	~5s
10 packages, 4 threads	~4s
20 packages, serial	~9s
20 packages, 4 threads	~8s
Repeat install (lockfile hit)	~200ms

Phase breakdown per package: metadata 141ms · download 44ms · static checks 138ms · sandbox 164ms.

For a typical pip install of 10 packages (8–15s on a fast connection), pipsentinel adds ~30–60% overhead on first install. Repeat installs are negligible.

---

What pipsentinel does not catch

Threat	Reason
Logic bomb on hostname, date, or secret env var	Sandbox runs on the same machine
C-extension network calls via ctypes	Bypasses Python's socket audit hook
Perfectly clean-looking malicious logic	No static analysis can catch well-written backdoors
Nation-state quality attacks	Requires full VM sandboxing with OS-level syscall tracing

Use pipsentinel alongside pip-audit (known CVEs), dependency lockfiles, and reproducible builds.

---

Architecture

graph TD
    CLI["cli.py\ncli entry point\ninstall / check / audit"]
    INSTALLER["installer.py\nsafe_install()\norchestrator"]
    CHECKS["checks.py\nall check functions\n9 pre-install · 2 post-install"]
    SANDBOX["sandbox.py\nrun_import_sandbox()\nsubprocess isolation"]
    HONEYPOT["honeypot.py\npopulate_honeypot_home()\nfake credentials"]
    LOCKFILE["lockfile.py\nLockfileManager\n~/.pipsentinel/pipsentinel.lock"]
    REPORT["report.py\nSecurityReport\nhuman + JSON output"]
    PIP["pip subprocess\n--require-hashes"]
    PYPI["PyPI\nJSON API · Simple API\nwheel download"]
    GITHUB["GitHub API\ntags · commit timestamps"]

    CLI --> INSTALLER
    CLI --> CHECKS
    INSTALLER --> CHECKS
    INSTALLER --> LOCKFILE
    INSTALLER --> SANDBOX
    INSTALLER --> REPORT
    INSTALLER --> PIP
    SANDBOX --> HONEYPOT
    CHECKS --> PYPI
    CHECKS --> GITHUB
    LOCKFILE -. "fast path\n(repeat install)" .-> INSTALLER

Module responsibilities

pipsentinel/
├── checks.py     # all security checks: git tag, .pth scan, hash consensus,
│                 # RECORD integrity, obfuscation, timestamp delta, provenance,
│                 # post-install audit and RECORD diff
├── sandbox.py    # process-level import sandbox with audit hooks
├── honeypot.py   # fake credential generation + exfiltration sequence detection
├── lockfile.py   # ~/.pipsentinel/pipsentinel.lock management
├── installer.py  # orchestrates checks → pip install --require-hashes
├── report.py     # SecurityReport + human/JSON output
└── cli.py        # pipsentinel install / check / audit

Every check is a pure function returning CheckResult(name, passed, severity, message, detail). No global state. Each check can be imported and called independently.

---

Zero dependencies

pipsentinel uses only the Python standard library:

urllib.request   PyPI API + wheel downloads
hashlib          SHA-256 verification
zipfile          wheel inspection (wheels are zip files)
subprocess       sandbox subprocess + pip delegation
ast              AST-level obfuscation detection
site             .pth processing in sandbox
json, re, tempfile, pathlib, ...

This is intentional and non-negotiable. A security tool with dependencies has a supply chain. pipsentinel has none.

---

Testing

pip install pytest
python -m pytest -v                              # 66 tests, ~0.1s

pip install pytest-cov
python -m pytest --cov=pipsentinel --cov-report=term-missing

---

Future Plans

Transitive dependency scanning (top priority)

The current gap: pipsentinel checks the package you explicitly install, but not its transitive dependencies. If requests depends on certifi, and certifi is compromised, the attack still lands — pipsentinel never saw it.

Proposed fix:

1. Run pip install --dry-run <package> to enumerate the full dependency closure before installing anything
2. Run the full check suite on every package in the closure
3. Only proceed with installation if the entire graph passes

This closes the DSPy/LiteLLM-style attack: even if the target package is clean, a backdoored transitive dep (e.g. a compromised LLM client library pulled in silently) will be caught before it touches disk.

Other planned improvements

Feature	Description
pipsentinel update	Audits candidate upgrade versions before applying them
Typosquatting detection	Levenshtein distance check against top-5000 PyPI packages
SBOM export	Generate a signed software bill of materials after install
uv.lock full audit	Run the complete 8-check suite per package (not just 3 checks) during sync
CI mode	--fail-fast, machine-readable exit codes, and structured JSON output for pipeline integration
Malicious maintainer heuristics	Flag packages with recent maintainer changes or ownership transfers

---

License

MIT