Metadata-Version: 2.4
Name: depmirage
Version: 0.1.0
Summary: Spot AI-hallucinated and slopsquatting Python dependencies, typosquats, and hardcoded secrets.
Author: Atanas Burmov
License: MIT
Project-URL: Homepage, https://github.com/AABurmov18/depmirage
Project-URL: Repository, https://github.com/AABurmov18/depmirage
Project-URL: Issues, https://github.com/AABurmov18/depmirage/issues
Keywords: security,supply-chain,slopsquatting,typosquatting,hallucination,pypi,secrets,pre-commit,ci
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# depmirage

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

[![CI](https://github.com/AABurmov18/depmirage/actions/workflows/ci.yml/badge.svg)](https://github.com/AABurmov18/depmirage/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/depmirage)](https://pypi.org/project/depmirage/)
[![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)
[![os](https://img.shields.io/badge/os-Windows%20%7C%20macOS%20%7C%20Linux-brightgreen)](https://github.com/AABurmov18/depmirage)
[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)

![depmirage demo](https://raw.githubusercontent.com/AABurmov18/depmirage/main/docs/demo.gif)



## 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](https://arxiv.org/abs/2406.10279)

## Install

```bash
pip install depmirage
```

From source:

```bash
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

```bash
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) |

```bash
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](https://github.com/gitleaks/gitleaks),
[trufflehog](https://github.com/trufflesecurity/trufflehog),
[Snyk](https://snyk.io/), or [pip-audit](https://github.com/pypa/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`](https://github.com/) 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`:

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

## CI (GitHub Actions)

```yaml
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:

```bash
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](LICENSE).
