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 requests==99.99.99          # pins are checked too
ghostpkg check react-router-dom-utils -e npm

Scan a manifest

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

Why prose matters: the hallucination arrives before the manifest does. A model writes pip install foo-bar into a README or an agent instruction file, somebody copies the line and runs it — the install has already happened by the time that name reaches requirements.txt.

Extraction is deliberately narrow, because a README is full of words that look like package names. Measured across thirteen real READMEs, it finds the genuine names with a 0% false-positive rate; pip install -r requirements.txt, npm run build, pip is a package manager and npx create-react-app my-app (where my-app is an argument) all yield nothing.

Lockfiles are worth scanning even when you already scan the manifest: CI installs from the lockfile, so it holds the names that actually get fetched -- including transitive ones the manifest never mentions -- and every entry is version-pinned, so all of them are checkable.

Several files can be scanned in one run, and they may be different ecosystems:

ghostpkg scan requirements.txt package.json pnpm-lock.yaml

Or point it at a directory -- or at nothing, which means the current one:

ghostpkg scan          # searches the current directory
ghostpkg scan ../other-project

The search skips node_modules, .venv, .git, dist and other vendored or generated trees, and a lockfile supersedes the manifest beside it: a lockfile is that manifest resolved, so reading both prints most packages twice and checks nothing extra. Alongside manifests it picks up agent instruction files -- AGENTS.md, CLAUDE.md, .cursorrules -- and the README at the root, since that is where an install command is most likely to be copied from.

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.

Suppressing a finding you have decided about

One false positive is enough for a team to remove a security check from CI, so there is a way to say "we know about this one".

{
  "ignore": [
    { "package": "acme-*", "rule": "GP001",
      "reason": "internal, lives on our own index" },
    { "package": "some-lib", "rule": "GP003",
      "reason": "vendor published it last week, reviewed",
      "expires": "2026-12-31" }
  ]
}

ghostpkg scan requirements.txt --config ~/ghostpkg-ignore.json
export GHOSTPKG_CONFIG=~/ghostpkg-ignore.json

The file is never read from the project directory. ghostpkg is meant to sit in front of a coding agent, and an agent with shell access can edit files in the repository it is working on -- a suppression list next to the code would be one the guarded thing can rewrite. It is read from --config, from GHOSTPKG_CONFIG, or from your config directory (%APPDATA%\ghostpkg, ~/Library/Application Support/ghostpkg, $XDG_CONFIG_HOME/ghostpkg).

A reason is required, an expires date is optional but recommended, and a malformed file stops the run rather than quietly leaving you unprotected.

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

- uses: M1rwana12/ghostpkg@v0.18.0

That is the whole step. It searches the checkout, skips node_modules and friends, and annotates the pull request diff on the offending line rather than leaving the answer in a job log:

::error file=requirements.txt,line=12,title=ghostpkg GP001::fastapi-auth-helper: does not exist on pypi

A blocking finding is an error and a soft signal is a warning, so the annotations and the exit code agree about severity.

Optional inputs -- paths, strict, deep, version, python-version, fail-on-error. Pin version if you want the run to be reproducible.

Or without the action, if you prefer:

- run: pip install ghostpkg && ghostpkg scan --format github

As a pre-commit hook

repos:
  - repo: https://github.com/M1rwana12/ghostpkg
    rev: v0.18.0
    hooks:
      - id: ghostpkg

The hook receives only the staged files that match, so it costs one registry lookup per changed dependency rather than a full scan on every commit. Vendored trees are excluded.

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, plus any script those hooks name), and pattern-matches the text. npm hooks are matched against shell-command patterns rather than source-code ones, because that is what they are. If a package cannot be inspected — no source archive, or an archive over the size limit — it says so rather than passing quietly. 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