ghostpkg

Stops you installing packages that don't exist.

Language models invent library names. Attackers register those names in advance. ghostpkg checks the name against the real registry — before pip or npm downloads anything.

English · Українська

Contents

• The problem
• What ghostpkg does
• Install
• Usage
• Every signal it checks
• Why it doesn't block on "suspicious"
• Where it fits in your workflow
• How it works internally
• Comparison
• Honest limitations
• Prior art and credit

The problem

A study of ~200,000 code-generation prompts found 205,474 unique hallucinated package names. The dangerous part isn't the count — it's the consistency:

43% of those hallucinations reappeared in all ten reruns of the same prompt.

That makes them predictable. An attacker can work out in advance which name a model will invent, register it on PyPI or npm, and wait. By the time your agent confidently writes pip install fastapi-middleware, the package is already there.

The attack has a name: slopsquatting.

This isn't theoretical. Malicious packages exploiting exactly this pattern have been found with tens of thousands of downloads, and the Cloud Security Alliance published a formal research note on it in April 2026.

What ghostpkg does

It answers one question, precisely: does this package actually exist, and if so, does anything about it look wrong?

The exit code is 1 when anything is blocked, so it drops straight into CI or a pre-install hook with no glue code.

What it is: a fast, narrow, dependency-free gate you can put in front of every install.

What it is not: a code scanner, a malware detector, or a replacement for an SCA product. It does one job.

Install

pip install ghostpkg

Other ways:

uvx ghostpkg check requests      # run without installing
pipx install ghostpkg            # isolated, global command

[!NOTE] Zero dependencies. Python standard library only. A supply-chain security tool that drags in a dependency tree of its own is a questionable proposition. This one has none.

Requires Python 3.9+. Tested on Linux, macOS and Windows.

Usage

Check names directly

ghostpkg check fastapi-middleware pandas-utils
ghostpkg check react-router-dom-utils -e npm

Scan a manifest

ghostpkg scan requirements.txt
ghostpkg scan pyproject.toml
ghostpkg scan package.json

Anything else is refused with an error rather than guessed at. Guessing is what made an earlier version read pyproject.toml with the requirements parser and report TOML keys as package names.

Options

Exit codes

Caching

Lookups are cached on disk, so re-scanning a 150-package manifest takes 0.4s instead of 4.7s.

Time-to-live depends on the answer, and the negative case is the one that matters: "does not exist" is held for only an hour, because a free name can be registered at any moment and that is the entire attack. Young packages are held six hours, established ones a day.

ghostpkg scan requirements.txt --no-cache   # bypass it
ghostpkg clear-cache                        # delete it
GHOSTPKG_CACHE_DIR=/tmp/gp ghostpkg check x # move it

A corrupt, unreadable or unwritable cache degrades to no cache rather than breaking your run.

JSON output

$ ghostpkg check somepkgthatisnotreal9911 --json
[
  {
    "name": "somepkgthatisnotreal9911",
    "ecosystem": "pypi",
    "verdict": "BLOCK",
    "reasons": [
      "does not exist on pypi"
    ]
  }
]

Every signal it checks

Warnings are advisory by default. Nothing but non-existence blocks unless you pass --strict.

Why it doesn't block on "suspicious"

The obvious design is to score packages and block anything that looks shady. I built that version first, then measured it against the live feed of newly published PyPI packages.

It flagged 100% of legitimate packages published that day.

That is not a threshold-tuning problem — it's the shape of the data. A malicious slopsquat registered three days ago and an honest new library published three days ago are the same package from the outside. Both are young. Both have one release. Both often lack a repository link.

So ghostpkg blocks on exactly one signal — the package does not exist — because that signal is precise, and it's the one that actually corresponds to a hallucination. Everything softer is reported for a human to read.

$ ghostpkg check react-router-dom-utils -e npm

  WARNING  react-router-dom-utils
           - first published 176 days ago
           - only one release
           - no repository or homepage link

There is a second lesson baked into the code. A naive typosquat check using a flat edit-distance budget flagged flask, click and black as typos of each other — short popular names sit inherently close together. The budget now scales with name length, and only applies to packages young enough to plausibly be a squat.

Where it fits in your workflow

In CI

- name: Check dependencies exist
  run: |
    pip install ghostpkg
    ghostpkg scan requirements.txt

As a pre-commit hook

repos:
  - repo: local
    hooks:
      - id: ghostpkg
        name: ghostpkg
        entry: ghostpkg scan requirements.txt
        language: system
        files: requirements\.txt$
        pass_filenames: false

In front of a coding agent

Point your agent's shell hook at ghostpkg check before it is allowed to run an install command. The non-zero exit code stops the install, and --json gives the agent a structured reason it can act on.

How it works internally

  name ──▶ registry lookup ──▶ 404? ──yes──▶ BLOCK ("does not exist")
                                │
                                no
                                ▼
                      collect facts:
                      age · release count · repo link
                                │
                                ▼
                   young enough to be a squat?
                                │
                        yes ────┴──── no ──▶ OK
                         │
                         ▼
              typo distance to top 2,000 names
              (budget scales with name length)
                         │
                         ▼
                 reasons found? ──no──▶ OK
                         │yes
                         ▼
                  WARN  (BLOCK if --strict)

Lookups run concurrently across a small thread pool, so scanning a manifest costs roughly one round trip rather than one per dependency.

--deep: inspecting install scripts

The existence check cannot see the dangerous case — a name an attacker has already registered. That package exists, so it passes; and it is young, with one release and no repository link, which describes every honest new package too. Age cannot separate them.

Install-time behaviour can. A slopsquat has to run something when it is installed — that is the entire point of publishing it. An honest new library almost never does.

ghostpkg scan requirements.txt --deep

--deep downloads the archive only for recently published packages, reads only setup.py from it (or the install hooks out of package.json), and pattern-matches the text. Nothing is ever executed. Archive and member sizes are capped, so a decompression bomb cannot exhaust memory.

It was measured before it was allowed to block

The last signal adopted on intuition — score packages by age — flagged 100% of legitimate same-day publications. So this one was measured first:

That is why a young package with install-time signals is blocked, while age alone can only ever warn. An established package showing the same signals is warned about rather than blocked: old packages do sometimes build things at install time, and the sample behind that judgement is small.

Limits, stated plainly: a squat that waits until import time rather than install time will not be caught, obfuscation beyond the listed patterns will not be caught, and packages published without an sdist cannot be inspected at all.

Comparison

ghostpkg is deliberately narrow, and the last two rows are where a real SCA product earns its keep. Use both.

Honest limitations

[!WARNING] The hard case is partly addressed by --deep, not solved. A hallucinated name an attacker has already registered passes the existence check. --deep looks at install-time behaviour and catches the usual shapes, but an attacker who does nothing during install will still get through. Discussion in #1.

• Typo detection compares against the 2,000 most-downloaded projects in each ecosystem, so a squat on a less popular package won't be flagged as a lookalike.
• Names shorter than five characters are not compared at all: below that the name space is too dense for edit distance to mean anything.
• The cache lives on disk. ghostpkg clear-cache removes it and GHOSTPKG_CACHE_DIR moves it.
• Registry outages surface as exit code 2 rather than a silent pass — deliberately, but it does mean a flaky network fails your build.

Prior art and credit

The scale of the problem was established by Spracklen et al., "We Have a Package for You! A Comprehensive Analysis of Package Hallucinations by Code Generating LLMs" (USENIX Security 2025).

Those authors deliberately did not publish their list of hallucinated package names, because such a list is a ready-made target list for attackers. ghostpkg follows that decision and ships no corpus of hallucinated names — it checks names live instead.

Contributing

Issues and pull requests welcome — see CONTRIBUTING.md.

git clone https://github.com/M1rwana12/ghostpkg
cd ghostpkg
pip install -e ".[dev]"
pytest

The most valuable contribution is a false positive report. If ghostpkg flagged a real package, that's a bug — a tool that cries wolf on legitimate packages gets turned off, and then it protects nothing.

The threat model, and an explicit list of what this tool does not catch, is in SECURITY.md.

License

MIT