Hi, I'm [0xIkari on Github](https://github.com/0xIkari). Like a lot of people I watched the LiteLLM 1.82.8 attack land in March and got curious why no existing Python tooling actually inspects the startup-vector surface (`.pth` files, `sitecustomize.py`, `__init__.py` top-level, `setup.py`, console-script entry points). pip-audit, safety, and bandit all skip these vectors despite them being the exact exploit class catalogued as MITRE ATT&CK T1546.018. The `.pth` vector specifically has been acknowledged as a security gap in [CPython issue #113659](https://github.com/python/cpython/issues/113659) with no patch. So I built pydepgate.

# What it is

pydepgate is an adversarial-code static analyzer for the Python supply-chain startup-vector surface. It scans wheels, sdists, installed packages, or individual files. Apache 2.0, on PyPI as `pydepgate`.

Five analyzer modules walk parsed representations of the input and emit `Signal` objects describing the patterns they detect. A separate rules engine maps Signals into severity-rated `Finding` objects using a data-driven rule set calibrated against file kind: a high-entropy base64 literal in a `.pth` is CRITICAL; the same literal in `__init__.py` is MEDIUM; the same literal anywhere else is LOW. Reporters render Findings as human-readable terminal output, JSON, or SARIF 2.1.0.

Zero runtime dependencies. Standard library only. This was deliberate: every additional dependency is a supply-chain attack surface for a tool whose job is to defend against supply-chain attacks. It also means pydepgate drops into air-gapped systems, restricted-network CI, and high-assurance workloads without having to whitelist anything from pip.

# The LiteLLM 1.82.8 demo

The malicious `.pth` payload was a single line of the form `import base64; exec(base64.b64decode('<payload>'))`. pydepgate fires **five separate findings** on this one line from four independent analyzers:

* `ENC001` (encoding\_abuse): decode-then-execute pattern
* `DYN002` (dynamic\_execution): `exec()` with non-literal argument at module scope
* `DENS001` (code\_density): token-dense single line
* `DENS010` (code\_density): high-entropy string literal
* `DENS011` (code\_density): base64-alphabet string literal

The rule layer then promotes all five to CRITICAL because the file is a `.pth`. To evade pydepgate, an attacker has to defeat every analyzer simultaneously while still producing a working `.pth` payload. Each evasion narrows what's possible; the intersection of all evasions is the empty set for any shape that could realistically execute on Python startup.

End-to-end on the actual 15 MB LiteLLM 1.82.8 wheel (2,598 internal files), with `--deep --peek --decode-payload-depth 8 --decode-iocs=full --min-severity high`, on a 2-core/8 GB GitHub Codespace: 20 seconds, 9 findings. The recursive decoder pulled the inner `subprocess.Popen` exfiltration payload out through a base64 chain and produced a ZipCrypto-encrypted forensic archive with SHA256/SHA512 IOC records.

# What it can do

* Static analysis of `.whl`, sdists (`.tar.gz` and variants), installed packages by name, and individual loose files via `--single`
* Five analyzer modules covering 30+ signals: encoding abuse (decode- then-execute, nested encoded payloads), dynamic execution (`exec`, `eval`, `compile`, `__import__`, getattr-on-builtins evasions), string obfuscation (`chr()` chains, `[::-1]` reverses, `bytes.fromhex`, f-string assembly), suspicious stdlib usage (subprocess, network, ctypes), and code density (high-entropy literals, Unicode homoglyphs, Trojan-Source invisibles, base64-alphabet strings, large byte-range integer arrays)
* Recursive payload decoding via `--decode-payload-depth N` that re-scans decoded bytes through the same analyzer pipeline. Handles base64, hex, zlib, gzip, bzip2, lzma chains up to depth 8
* ZipCrypto-encrypted archive output for forensic IOC workflows (default password `infected`, the malware-research convention so AV doesn't quarantine during analysis)
* A rules engine with custom `.gate` files in TOML or JSON, predicate operators (`eq`/`gt`/`gte`/`lt`/`lte`/`in`/`not_in`/`contains`/ `startswith`/`endswith`), and `difflib`\-based typo suggestions for malformed rules
* SARIF 2.1.0 output that ingests into GitHub Code Scanning, with `codeFlows` encoding the multi-layer decode chain for "Show paths" UI. **Content-blind by construction**: messages describe what was called (`subprocess.run()`, `urllib.request.urlopen()`) without including arguments, URLs, or literal payload bytes, so a defender can publish a SARIF document without re-leaking attack content
* Docker image at `ghcr.io/nuclear-treestump/pydepgate`. Multi-stage Alpine, under 50 MB, non-root (uid 1000), multi-arch (amd64 + arm64)
* Pre-commit hooks for `.py` and `.pth` files
* Roughly 1,200 unit tests, full suite under 20 seconds, validated in CI against the Microsoft SARIF Multitool

# How it works

1. You point it at a wheel, sdist, installed package, or loose file
2. Parsers extract `.py` and `.pth` content (AST parse only, never `exec` or `compile`)
3. Five analyzers walk the parsed representations and emit `Signal` objects
4. The rules engine maps Signals into severity-rated `Finding` objects using the default rule set (32 density rules + per-analyzer rules) plus any user `.gate` file
5. Reporters render Findings as terminal output, JSON, or SARIF 2.1.0

# Where to get it

* `pip install pydepgate`
* [https://github.com/nuclear-treestump/pydepgate](https://github.com/nuclear-treestump/pydepgate)
* `docker pull ghcr.io/nuclear-treestump/pydepgate:latest`

# Why this exists

Existing Python security tooling treats source code as the analysis unit. Supply-chain attacks operate one layer down, in the auto-executing surface around the source. The `.pth`, `sitecustomize`, and `setup.py` vectors all run before user code does. LiteLLM 1.82.8 was the loudest recent reminder of this gap; it will not be the last. Building a stdlib-only tool that ships into restricted environments, integrates with formats security teams already use (SARIF + GitHub Code Scanning), and brings zero attack surface of its own felt like the right answer.

About me: security engineer by background, currently building radiators for a crane company. pydepgate is a side-project I work on in the evenings. Apache 2.0, open to issues and PRs, see CONTRIBUTING.md for scope.

Happy to answer questions or take feedback.

GitHub - nuclear-treestump/pydepgate: Stdlib only Python adversarial-code static analyzer