# litellm-detector

`litellm-detector` is a globally installable CLI for fast, safe triage of Python environments. It finds installed `litellm` packages **via filesystem inspection only**—it does not import them.

As supply-chain risk grows (malware can run on import or interpreter startup), this tool helps security teams and developers locate and flag risky installs without executing the package under test.

## The March 24, 2026 PyPI supply chain incident

On **March 24, 2026**, compromised LiteLLM SDK builds were published to PyPI. LiteLLM attributed the breach to an unpinned Trivy dependency in CI/CD, which led to exfiltration of PyPI publishing credentials.

The affected releases were **`1.82.7`** and **`1.82.8`**, available for roughly eight hours before takedown (reported at 8:00 AM PST).

Those builds reportedly included credential-harvesting behavior (cloud keys, Kubernetes tokens, `.env` files). **`1.82.8`** also dropped a `litellm_init.pth` file, so malicious code could run whenever Python started in that environment—even if `litellm` was never imported.

Tools that import `litellm` or run untrusted code in the same environment can make remediation harder. Static inspection of install trees is the safer default for triage.

### Official impact and remediation (summary)

Per LiteLLM’s public incident communication (including work with Mandiant):

- **Lower risk:** Official LiteLLM Proxy Docker paths that pin SDK versions were called out as not impacted by these PyPI drops.
- **Higher risk:** Machines that `pip install`’d LiteLLM from PyPI during the window, especially `1.82.7` or `1.82.8`. Follow vendor guidance for exposure assessment.
- **Vendor response:** Packages removed from PyPI, credential rotation (e.g. GitHub, CircleCI, PyPI), hardened test environments, and release pipeline review before resuming publishes.
- **Tracking:** [LiteLLM incident thread](https://lnkd.in/grT9-Ms5) (LinkedIn).

### CVE-2025-11203 (older issue)

The tool also warns on versions affected by **CVE-2025-11203** (health-endpoint handling of `API_KEY`), addressed in **`v1.63.14-stable`**. See [ZDI-25-929](https://www.zerodayinitiative.com/advisories/ZDI-25-929/) and [LiteLLM v1.63.14-stable release notes](https://docs.litellm.ai/release_notes/v1.63.14-stable).

More detail: [docs/security-research.md](docs/security-research.md).

## What it checks

- **Discovery:** `litellm` distributions under `site-packages`, `dist-packages`, or custom roots.
- **Artifacts:** Heuristic scan of the package directory for risky co-located files (e.g. shell scripts, some executable suffixes, certain env-style filenames such as `.env`). Review anything unusual yourself—reports from incidents like March 2026 mention `.pth` drops; extend local policy if you need to hunt those by name.
- **Version / layout:** Metadata path, import package path, and console entry points where present.
- **Advisories:** Built-in rules today include **CVE-2025-11203** for versions **below `1.63.14`**. The March 2026 PyPI incident versions (`1.82.7` / `1.82.8`) are not yet encoded as separate rules in this package; treat installs from that window as high risk per vendor guidance regardless.

## Install

```bash
pip install litellm-detector
```

With [pipx](https://pypa.github.io/pipx/) (isolated CLI):

```bash
pipx install litellm-detector
```

## Usage

Scan the active environment:

```bash
litellm-detector
```

Scan specific roots (e.g. other venvs without activating them):

```bash
litellm-detector --root /opt/venvs/service-a/lib/python3.11/site-packages --root ~/.pyenv/versions
```

Crawl recursively for Python package directories under a root, or the whole disk:

```bash
litellm-detector --crawl --root /Users
litellm-detector --crawal
```

List suspicious files:

```bash
litellm-detector --show-files
```

CI / automation:

```bash
litellm-detector --json
litellm-detector --no-animation
```

### Example output (advisory hit)

The CLI prints Rich panels; roughly:

```text
Environment Scan Complete
Detected distributions: 1
Warnings: 1
OK: 0

Finding
  Status            warning
  Package           litellm
  Version           1.62.0
  Package Path      /Users/you/.venv/lib/python3.11/site-packages/litellm
  Notes             - Version 1.62.0 matches CVE-2025-11203; upgrade to >= 1.63.14.
                    - Defensive heuristic: versions lower than 1.63.14 ...
  Advisories        CVE-2025-11203 (...): ... | fixed >= 1.63.14
```

Exit code is **non-zero** when any finding has status `warning`.

## Local development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pytest
```

Non-editable install:

```bash
pip install .
litellm-detector --help
```

## Publishing to PyPI

Manual steps:

```bash
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*
```

Full checklist: [docs/pypi-release.md](docs/pypi-release.md).

Workflows: [.github/workflows/ci.yml](.github/workflows/ci.yml), [.github/workflows/publish-testpypi.yml](.github/workflows/publish-testpypi.yml), [.github/workflows/publish-pypi.yml](.github/workflows/publish-pypi.yml).

## Sources

- **Inspiration:** [lucubrator/litellm-check](https://github.com/lucubrator/litellm-check) — prefer filesystem inspection over executing a possibly compromised package.
- **March 2026 incident:** LiteLLM public advisory on the PyPI compromise (`1.82.7` / `1.82.8`) and CI/CD root cause.
- **CVE-2025-11203:** [ZDI-25-929](https://www.zerodayinitiative.com/advisories/ZDI-25-929/), [v1.63.14-stable notes](https://docs.litellm.ai/release_notes/v1.63.14-stable).
- **Notes in-repo:** [docs/security-research.md](docs/security-research.md).

## Credits

Built by Abhiyan Timilsina — [LinkedIn](https://www.linkedin.com/in/abhiyan-timilsina-6b679b142/). Open to new opportunities.
