chaincanary

Stop supply-chain attacks before they execute. The only scanner with semantic .pth analysis.

Caught LiteLLM 1.82.8 as MALICIOUS at publish time — before any advisory existed. No cloud. No account. Nothing leaves your machine.

Try it now — zero install:

pipx run chaincanary check requests==2.28.0

Or scan the real LiteLLM attack (uses local mock wheel — no network):

git clone https://github.com/AetherCore-Dev/chaincanary && cd chaincanary
pip install -e .
chaincanary check litellm==1.82.8 --local tests/fixtures/litellm-1.82.8-py3-none-any.whl

Why developers use chaincanary:

• Catches what others miss — semantic .pth classifier detects attacks that run on every Python startup, not just at install time
• Zero config — pip install chaincanary && chaincanary check <package>, done
• Nothing leaves your machine — pure offline static analysis, no cloud, no account, no proxy
• CI-ready — GitHub Action blocks malicious packages on every push
• Audit entire projects — scan all dependencies in requirements.txt or pyproject.toml in one command
• Version diffing — see exactly what changed between releases
• Works in China — no proxy needed, unlike socket.dev / Safety

Install

pip install chaincanary

Or try without installing: pipx run chaincanary check <package>

Usage

Scan a single package

chaincanary check requests==2.28.0
chaincanary check litellm==1.82.8

# Scan a local .whl file (no network needed)
chaincanary check litellm==1.82.8 --local ./litellm-1.82.8-py3-none-any.whl

Audit your entire project

chaincanary audit requirements.txt
chaincanary audit pyproject.toml --fail-on HIGH_RISK

Compare two versions

chaincanary diff litellm 1.82.6 1.82.8

Safe install (scan before installing)

chaincanary install requests==2.32.0
chaincanary install litellm==1.82.8   # blocked — MALICIOUS

JSON output (for pipelines)

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

SARIF output (for GitHub Code Scanning)

# Single package → SARIF
chaincanary check litellm==1.82.8 --local ./litellm-1.82.8-py3-none-any.whl --sarif-output > results.sarif

# Audit lockfile → SARIF
chaincanary audit requirements.txt --sarif-output > chaincanary.sarif

Upload to GitHub Security tab in your CI workflow:

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: chaincanary.sarif

Offline mode (air-gapped / CI cache)

# Download wheels first (standard pip)
pip download -r requirements.txt -d ./wheels/

# Scan without any network calls
chaincanary audit requirements.txt --offline --wheel-dir ./wheels/

# Single package offline
chaincanary check mypackage==1.0.0 --offline --local ./mypackage-1.0.0-py3-none-any.whl

GitHub Action — drop-in CI protection

# .github/workflows/security.yml
name: Supply Chain Security
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: AetherCore-Dev/chaincanary@v0.1.0
        with:
          requirements: requirements.txt
          fail-on: MALICIOUS   # or HIGH_RISK for stricter mode
          sarif-output: chaincanary.sarif  # optional: upload to GitHub Security tab
      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: chaincanary.sarif

Fails your build if any dependency matches a known attack pattern. Zero config.

Why chaincanary catches what others miss

A .pth file in Python's site-packages runs on every Python startup — not just at install time. Other scanners only check setup.py install hooks and miss this entirely.

chaincanary has a semantic .pth classifier with 4 categories:

LiteLLM 1.82.8 was flagged MALICIOUS by chaincanary at publish time. Other tools missed it entirely, or flagged it only after manual rule updates.

What chaincanary detects

Comparison

chaincanary is not a CVE scanner — use it alongside pip-audit for vulnerability advisory coverage.

The LiteLLM attack — what happened

# litellm_init.pth — executes on every Python startup, silently, forever
import os, subprocess, sys
subprocess.Popen([sys.executable, "-c", "import base64; exec(base64.b64decode('...'))"])

How it works

chaincanary check <package>
        |
        v
Download wheel (no install, no execute)
        |
        v
Static analysis:
  - Zip safety (path traversal, zip bomb)
  - .pth semantic classifier (4 categories)
  - AST analysis of setup.py / install hooks
  - Obfuscation detection (base64, eval, exec)
  - __init__.py delayed-trigger scan
  - DNS exfiltration patterns
  - SHA256 malicious hash database
  - Typosquatting distance check
        |
        v
Score 0-10 -> Verdict: SAFE / LOW_RISK / HIGH_RISK / MALICIOUS
        |
        v
Block or proceed

No sandboxing. No Docker. No kernel modules. Pure Python static analysis in seconds.

Add chaincanary badge to your project

Show that your project is scanned for supply-chain attacks:

[![chaincanary](https://img.shields.io/badge/scanned%20by-chaincanary-blue)](https://github.com/AetherCore-Dev/chaincanary)

Known Limitations

chaincanary is a static behavioral scanner, not a magic bullet:

Roadmap

Full plan: ROADMAP.md

Contributing

git clone https://github.com/AetherCore-Dev/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

License

Apache 2.0. See LICENSE.

Built after the LiteLLM supply chain attack, March 2026.