depmirage 0.1.0

Spot AI-hallucinated and slopsquatting Python dependencies, typosquats, and hardcoded secrets.

depmirage

Catch AI-hallucinated and slopsquatting Python dependencies before they ship.

Why this exists

Large language models routinely invent Python packages that do not exist. In "We Have a Package for You!" (Spracklen et al., USENIX Security 2025), researchers found that 5.2%–21.7% of package references generated by popular code LLMs point at packages that were never published — a phenomenon now called slopsquatting: an attacker registers the hallucinated name, and the next developer who copies an LLM's pip install suggestion pulls hostile code. Because the same wrong name is hallucinated repeatedly, these become predictable, reservable attack surface. depmirage scans your project for exactly this class of risk — plus classic typosquats and hardcoded secrets — and fails your build if it finds any.

Paper: arXiv:2406.10279

Install

pip install depmirage

From source:

git clone https://github.com/AABurmov18/depmirage
cd depmirage
pip install .

Requires Python 3.10+. Only two runtime dependencies: requests and rich (both pure-install, no C toolchain — builds clean on Windows).

Usage

depmirage scan <path>          # scan a folder, requirements.txt, or .py file
depmirage scan                 # defaults to the current directory
depmirage scan . --offline     # cached fixtures, ZERO network calls
depmirage scan . --json        # machine-readable output

Exit codes make it a drop-in CI / pre-commit gate:

Exit	Meaning
0	No findings
1	At least one finding (hallucinated pkg, typosquat, or secret)
2	Bad invocation (path not found)

depmirage scan examples/demo || echo "findings present — failing the build"

What it checks

1. Package existence (the hero feature). Every dependency in requirements.txt is checked against PyPI. Non-existent names are flagged as hallucinated / slopsquatting risk.
2. Typosquat / lookalike. Names within edit-distance 1 of a bundled list of ~200 popular packages (or non-existent-and-close) are flagged as high typosquat risk. Levenshtein is implemented in pure Python — no C extensions.
3. Hardcoded secrets. .py files are scanned for OpenAI-style sk-… keys, AWS AKIA… keys, secret-looking assignments (KEY/TOKEN/SECRET/ PASSWORD/APIKEY), and generic high-entropy string literals (Shannon entropy). Findings show file + line; the value is always masked (first/last 4 characters only).
4. Output + exit code. A colored rich table — green [PASS], red [FAIL], yellow for "could not verify" — and a CI-friendly exit code.

Honest positioning

depmirage is not a replacement for gitleaks, trufflehog, Snyk, or pip-audit. Those tools are deeper at what they do, and you should keep using them.

The novel, defensible feature here is AI-hallucination + slopsquatting detection for the Python/PyPI ecosystem. The secret and (future) vulnerability checks are convenience layers built with well-known techniques so a single pre-commit hook covers the most common "LLM pasted something risky" cases.

Prior art. slopcheck and slop-scan-style tools exist, but they are npm-/markdown-focused. depmirage is Python/PyPI-first and scans both requirements.txt and .py source.

Pre-commit

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/AABurmov18/depmirage
    rev: v0.1.0
    hooks:
      - id: depmirage

CI (GitHub Actions)

name: depmirage
on: [push, pull_request]
jobs:
  slopsquat-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install depmirage
      - run: depmirage scan .

How it works

depmirage parses your requirements.txt (stripping version specifiers, extras, and environment markers), queries https://pypi.org/pypi/{name}/json for each name with a 5-second timeout, and caches results on disk (~/.depmirage_cache) so repeat runs are fast. Only package names ever leave your machine — never source code, never secrets. Network failures degrade gracefully to "could not verify" instead of crashing. --offline short-circuits all of this with bundled fixtures for a fully deterministic, air-gapped run.

Ethics

depmirage only reads public registries (PyPI, npm). It will never register, publish, or reserve any hallucinated package name it discovers — doing so would itself be the slopsquatting attack. It never transmits your scanned code or the secrets it finds; only bare package names are sent over the wire, and secret values are masked before they are ever displayed. Use it to defend your own supply chain, not to weaponize someone else's mistake.

Contributing

Issues and PRs welcome. Run the tests with:

pip install -e ".[dev]"
pytest

Good first contributions: extend the popular-package list, add ecosystems (npm/package.json existence is partially wired up), or add OSV.dev vulnerability lookups.

License

MIT.