dep-verify-guard

name

dep-verify-guard

description

Blocks hallucinated, typosquatted/slopsquatted, and unnecessary dependencies from being installed by verifying each new package against the real registry (npm/PyPI/crates) before it's added. Best used reactively before adding, importing, or installing any dependency. Use when the user says "install X", "add a package for", "npm/pip/cargo add", "import", or when a coding agent introduces a new third-party import. DO NOT USE for secret exposure (use no-secret-leak-guard) or general diff review (use clean-diff-guard); this guard is specifically about dependency existence, typosquatting, and necessity.

dep-verify-guard

Never install a package on faith. LLMs predictably hallucinate plausible-sounding package names, and attackers pre-register those exact names on public registries so the hallucination becomes a working, malicious install the moment an agent runs npm install <name>. This guard makes "does this package actually exist, and do we actually need it" a checked step, not an assumption.

Research on this failure mode (CSA, Unit42, and related slopsquatting studies) found that LLM code generation hallucinates non-existent package names in a meaningful fraction of dependency-adding requests, and that a large fraction recur (reported in 2025–2026 slopsquatting research) across repeated runs of the same prompt — stable enough for an attacker to pre-register the exact name and wait. react-codeshift is a plausible example of the pattern: a name an LLM could plausibly produce by conflating two real packages (jscodeshift + react-codemod), but it does not exist as a real published package. This guard exists to catch that pattern before npm install runs, not after.

When to use — three modes

• Guard-pass (default). Right before running npm install / pip install / cargo add / yarn add / pnpm add, or before writing an import/require statement for a package not already in the manifest/lockfile: verify the package per the Procedure below. This is the mode that fires on trigger phrases like "install X," "add a package for," "npm/pip/cargo add," or "import."
• Live. While actively writing code and reaching for a third-party helper mid-task (e.g., typing import { chunk } from 'lodash.chunk'): pause at the import line itself, not at a later review pass. Verify the name is real and actually needed before the line is finalized, the same way you'd check a function signature before calling it.
• Review. When asked to review a diff, PR, or lockfile change that adds dependencies: treat every new entry in package.json/requirements.txt/Cargo.toml and its corresponding lockfile as something to verify, not something to wave through because it's already there. A dependency added by a previous agent turn or a teammate gets the same scrutiny as one you're about to add yourself.

What this guard blocks

1. Unverified existence. For EVERY new import/package, verify it exists on the real registry (npm, PyPI, crates.io, etc.) using available tools — a registry lookup, the package manager's own search/info/view command, or a web fetch of the registry's public API. Never assume a plausible-sounding name is real because it "sounds like" a package that should exist. See references/registry-verification.md for the per-ecosystem commands.
2. Typosquat / conflation near a popular package. Check whether the requested name is a near-miss of, or a plausible mashup of, an established popular package. List the closest real ones by name when flagging this — e.g. react-codeshift → the real packages are jscodeshift and react-codemod; python-dateutil typo'd as python-datetuil → the real package is python-dateutil. See references/slopsquat-checklist.md for the common hallucinated-name shapes (conflation, pluralization drift, scope-dropping, version-suffix guessing).
3. Suspicious-new or low-signal packages. Flag packages that are brand-new (registered days to a few weeks ago), have zero or near-zero weekly downloads, have a single maintainer with no other published packages, or have had no release in years while claiming to solve an actively-maintained problem — for human confirmation before installing. A name existing on the registry is necessary but not sufficient; a squat is also "real" the moment it's registered.
4. Unnecessary additions. Before adding any package, check whether the standard library or an already-installed dependency already covers the need. Do not add a package the task didn't actually require — every added dependency is additional supply-chain surface, install-time code execution risk, and maintenance burden, regardless of how small it is.
5. Unpinned / unrecorded resolution. Once a package is verified and genuinely needed, record the exact resolved version (not a loose ^/* range invented from memory) in the manifest and confirm it lands correctly in the lockfile. Note explicitly that most package managers run arbitrary install-time scripts (postinstall, build hooks) for every transitive dependency — a verified top-level package can still pull in an unverified, unreviewed dependency tree.
6. Can't-verify means ask, not install. If the available tools cannot confirm a package's existence (no network access, registry lookup fails, ambiguous name with no single best match), say so explicitly and ask the user before installing. Do not fall back to "it's probably fine" — the entire point of this guard is that "probably fine" is exactly how slopsquats get installed.

Procedure — guard-pass steps

1. Enumerate the new dependencies. Diff the manifest (package.json dependencies/devDependencies, requirements.txt/pyproject.toml, Cargo.toml) and/or lockfile against what was there before this change. List every package that is new, not already present.
2. Verify each one exists, using the ecosystem's own tooling (npm view <name>, pip index versions <name> / PyPI JSON API, cargo search <name>) per references/registry-verification.md. Record what came back: exists / does not exist / ambiguous.
3. Check for typosquat/conflation against well-known packages solving the same stated problem, using references/slopsquat-checklist.md's heuristics. If the name is a near-miss or a mashup, name the real package(s) it's most likely confused with.
4. Check age, downloads, and maintenance signal for anything that exists but looks new or thin. Note the registered date, weekly download count (if available), and last-release date in the report.
5. Ask "did the task actually need this?" Check the standard library and the existing dependency tree first. If an existing capability covers it, recommend that instead and do not add the package.
6. Report per package: exists (Y/N) · age/downloads/maintenance signal (if thin, flagged) · typosquat risk (named alternatives if any) · necessity call (needed / stdlib-or-existing-dep-covers-it) · resolved version to pin.
7. If everything checks out, proceed with the install/import and record the resolved version. If anything is unverified, hallucinated, squatted, thin, or unnecessary, stop and surface it before installing — do not install first and mention concerns after.
8. Emit the guard footer (see Output) as the last line of the response.

Output

Emit this verbatim as the last line of any response where a dependency was added, considered, or reviewed:

proofguard:dep-verify-guard — <PASS | FIX-REQUIRED | WAIVED(reason)> · Triggered: <what fired it> · Fixed: <n> · Verified: <what was checked — registry lookup, typosquat check, necessity> · Remaining gap: <what's unchecked>

• PASS — every new dependency was confirmed to exist, isn't a typosquat/conflation of a real package, isn't suspiciously new/thin without disclosure, and is actually needed (stdlib/existing deps don't already cover it).
• FIX-REQUIRED — a hallucinated, typosquatted, unverifiable, or unnecessary package was about to be installed and has not yet been resolved (swapped for the real package, dropped in favor of stdlib, or held for human confirmation).
• WAIVED(reason) — the user, as the actual principal, explicitly accepted a flagged risk (e.g. "yes, install the brand-new package anyway, I trust the author") with a stated reason.

References

• references/slopsquat-checklist.md — the slopsquatting threat model, the react-codeshift case in detail, and the common shapes hallucinated package names take (conflation, pluralization drift, scope-dropping, plausible-suffix guessing).
• references/registry-verification.md — exact per-ecosystem commands for verifying existence, age, and download/maintenance signal (npm, PyPI, crates.io), plus the stdlib-first rule.

What this guard does NOT do

It is not a full SCA (software composition analysis) or vulnerability scanner — it does not check known-CVE databases, license compatibility, or dependency-tree-wide risk scoring. For that, recommend npm audit, osv-scanner, or Socket as a follow-up. This guard targets the failure mode vulnerability databases structurally cannot catch: a hallucinated or freshly-squatted package name has no CVE history yet, because nothing has been reported against it — the risk is entirely in whether the name is real, correctly typed, and actually needed, which is exactly the window before install where vuln scanners have nothing to say.