Vet every dependency before your AI agent installs it.
An agent skill that catches typosquats, slopsquats, dangerous install scripts
and dead packages — before npm install runs, not after.
Your coding agent adds packages without reading them. That is the exact path of every big supply-chain failure of the last decade:
crossenv(2017) — one character away fromcross-env. Stole npm credentials on install. It is still live on npm today, still collecting typo traffic (depvet catches it — see the real run below).- Sep 2025 npm compromise — one phished maintainer; malware in packages with billions of weekly downloads; self-propagating.
- Shai-Hulud worm (Nov 2025) — 100+ packages (Zapier, PostHog, AsyncAPI,
ENS…) infected via lifecycle scripts and stolen tokens; exfiltrated through
webhook.siteand GitHub Actions; Shai-Hulud 2.0 shipped stagedsetup_bun.jsdroppers. @acitons/artifact(Nov 2025) — typosquatted the scope of GitHub's own Actions package, collected CI tokens from ~47k installs through a postinstall payload with a time bomb. Nobody reads the org prefix.- WEL1DROPPER (Aug 2026) — 1,000+ npm packages under AI-slop typo names delivering a remote-access trojan: slopsquatting went industrial.
- Slopsquatting (OWASP-documented) — attackers publish malicious packages under the hallucinated names that AI assistants invent. Your agent is the attack surface.
Postinstall-script malware grew another 61% in H1 2026 alone. npm audit
scans after you depend on something — and the community consensus is that
it is broken-by-design anyway (Dan Abramov's writeup; Reddit: "npm audit
passes clean on packages that are actively compromised — these tools check a
database of known issues"). Snyk and Socket watch repos and registries
continuously. Nobody gates the moment the agent decides to install.
depvet is that gate.
Before any install, depvet runs a read-only check against the registry and returns a verdict:
| Verdict | Meaning |
|---|---|
| PASS | No red flags — install, mention it in one line |
| WARN | Risk signals (single maintainer, abandoned, license gap…) — user confirms |
| BLOCK | Typosquat / confusable name / nonexistent name / dangerous install scripts / fresh-drop — do not install, propose the real alternative |
Checks performed on every candidate: confusable identity (separator/case
variants of famous names), edit-distance ≤ 2 from top packages, scoped
near-misses of well-known scopes (@acitons vs @actions), registry
existence (slopsquat path), lifecycle-script payloads (curl|sh, base64,
eval, credential paths, webhook exfil endpoints, CI-token harvesting,
Shai-Hulud bun droppers…), package age, weekly downloads, maintainer count,
repository presence, abandonment, npm deprecation notices, PyPI yanked
releases, provenance attestations, and license.
It also scans whole manifests — package-lock.json (v1/v2/v3),
yarn.lock (v1 + Berry, incl. npm: aliases), pnpm-lock.yaml (v6/v9,
peer-suffixed snapshots) and requirements.txt — because event-stream and
eslint-scope both arrived through the dependency tree, not through a direct
add. --production skips dev-only dependencies so you can vet just the
deploy surface.
python3 scripts/depvet_check.py react axios crossenv react-fast-carousel-pro
PACKAGE VERDICT AGE DOWNLOADS MAINT SCRIPTS LICENSE
crossenv BLOCK 3400d 2,325/wk 1 no NONE
[BLOCK] CONFUSABLE IDENTITY: 'crossenv' differs from popular package 'cross-env'
only by separators/case (the crossenv-vs-cross-env typosquat pattern).
Did you mean 'cross-env'?
react-fast-carousel-pro BLOCK ? - - no NONE
axios WARN 4454d 144,374,997/wk 1 yes MIT
[WARN] single maintainer (bus factor / account-takeover blast radius)
react PASS 5492d 252,579,442/wk 2 no MIT
BLOCKED: crossenv, react-fast-carousel-pro - do NOT install. Ask the user how to proceed.
WARNINGS: axios - surface to the user before installing.
That crossenv row is the actual 2017 credential-stealing typosquat, still
sitting on the registry — caught by the confusable-identity check, live, with
zero configuration.
Most compromises arrive as transitive dependencies. One command vets
every package in the locked tree — npm (package-lock.json v1/v2/v3),
yarn (yarn.lock v1 + Berry), pnpm (pnpm-lock.yaml v6/v9) — or a
requirements file:
python3 scripts/depvet_check.py --lockfile package-lock.json
python3 scripts/depvet_check.py --lockfile yarn.lock --production
python3 scripts/depvet_check.py --lockfile pnpm-lock.yaml --production
Real run — a demo lockfile containing express, lodash, the deprecated
event-stream, and the crossenv typosquat hiding as a nested dep:
PACKAGE VERDICT AGE DOWNLOADS MAINT SCRIPTS LICENSE
crossenv BLOCK 3401d 2,545/wk 1 no NONE
[BLOCK] CONFUSABLE IDENTITY: 'crossenv' differs from popular package 'cross-env'
only by separators/case (the crossenv-vs-cross-env typosquat pattern).
Did you mean 'cross-env'?
event-stream WARN 5559d 8,030,026/wk 1 yes MIT
lodash WARN 5314d 202,301,867/wk 1 yes MIT
express PASS 5794d 195,493,804/wk 5 yes MIT
scanned 4 packages (4 deps from demo-package-lock.json)
BLOCKED: crossenv - do NOT install. Ask the user how to proceed.
--requirements requirements.txt does the same for PyPI, with the same
verdicts (reqests typosquat inside a requirements file gets BLOCKed).
Deprecated packages get called out by name — the real output for request
(14M downloads/week, still installed everywhere):
request WARN 5771d 13,964,396/wk 4 yes Apache-2.0
[WARN] deprecated on npm: request has been deprecated,
see https://github.com/request/request/issues/3142
[WARN] latest version published 6+ year(s) ago (possibly abandoned)
Grounded in what developers actually report about these tools:
| Tool | Gates the install? | Novel malware? | Noise profile | Cost |
|---|---|---|---|---|
| depvet | yes — the moment of install / PR | yes (name + behavior signals, no advisory DB needed) | BLOCK needs strong evidence; WARN is explainable; allowlist for reviewed packages | free, zero-dep |
npm audit |
no — audits what you already installed | no (advisory DB only) | 99%+ false-positive rate documented (dev-dep noise, duplicate paths) — "broken by design" (Dan Abramov) | free |
| Snyk | no | advisory DB + own research | commercial SCA; needs account/agent | paid tiers |
| Socket | no — continuous monitoring | yes (behavioral) | low | commercial; free tier for OSS |
| Phylum | — | was behavioral | — | acquired by Veracode (Jan 2025), folded into a commercial SCA suite |
depvet is not trying to replace continuous monitors — see What depvet is not. It closes the specific gap everyone else leaves open: the gate at the moment a package is chosen, which is exactly where agents operate.
depvet ships as a reusable GitHub Action. Add this to the repo you want
gated — the job goes red if a BLOCK verdict appears (with strict: true,
on any WARN too):
name: depvet
on:
pull_request:
paths: ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'requirements*.txt']
jobs:
vet:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: TusharB-07/depvet@v1
with:
lockfile: package-lock.json
production: true
strict: trueTeams keep shipping axios (single maintainer) or request (deprecated but
still needed). Record the review once and stop re-litigating it — create
.depvetrc.json next to where you run depvet:
{
"allow": {
"axios": "single maintainer accepted, reviewed 2026-11"
}
}Allowlisted packages have WARN downgraded to PASS with the reason recorded in the output. BLOCK is never downgraded by an allowlist — trust annotations do not override typosquat evidence.
Works with any agent that reads Agent Skills: Claude Code, Codex, Gemini CLI, Antigravity, OpenCode, and friends.
Claude Code — global:
git clone https://github.com/TusharB-07/depvet.git
mkdir -p ~/.claude/skills && cp -r depvet/skills/depvet ~/.claude/skills/…or per project: copy into .claude/skills/ inside the repo.
Codex / OpenCode:
mkdir -p ~/.agents/skills && cp -r depvet/skills/depvet ~/.agents/skills/Gemini CLI / Antigravity:
mkdir -p ~/.gemini/antigravity/skills && cp -r depvet/skills/depvet ~/.gemini/antigravity/skills/No config, no API keys, no network setup beyond registry access the agent already has.
Say it, or just install something — the skill triggers on dependency work:
> add zod and axios to this project
> depvet lodash-es is-odd event-stream
Or use the checker standalone (it is a normal CLI):
python3 scripts/depvet_check.py express koa fastify # npm
python3 scripts/depvet_check.py --registry pypi requests # PyPI
python3 scripts/depvet_check.py --lockfile package-lock.json # whole tree (npm)
python3 scripts/depvet_check.py --lockfile yarn.lock # whole tree (yarn v1/Berry)
python3 scripts/depvet_check.py --lockfile pnpm-lock.yaml # whole tree (pnpm v6/v9)
python3 scripts/depvet_check.py --production --lockfile package-lock.json # skip dev-only deps
python3 scripts/depvet_check.py --requirements requirements.txt
python3 scripts/depvet_check.py --json react # machine-readable
python3 scripts/depvet_check.py --no-cache react # bypass the 24h verdict cache
python3 scripts/depvet_check.py --workers 1 express koa # sequential, paced lookupsExit codes: 0 no red flags · 1 WARN present with --strict ·
2 BLOCK present (always fails) — so CI gates work out of the box.
JSON output includes one object per package with verdict, flags,
warnings, notes, and registry, ready for your own tooling.
Same 88-dependency package-lock.json, same machine, same network, fresh
registry data both times (Nov 2026):
| Run | Wall time |
|---|---|
| v1.1 — sequential, one package at a time | 85.8 s |
| v1.2 — cold (network, no cache) | 2.9 s |
| v1.2 — warm (24 h verdict cache) | 0.08 s |
All three runs return identical verdicts for all 88 packages — the diff against the old engine is empty. What changed:
- Concurrent by default — batches run on 8 worker threads (
--workers N;--workers 1restores the old sequential, paced behavior). - Keep-alive + gzip — per-thread pooled connections to the registry CDNs, compressed responses, and one automatic retry when a server silently closes an idle socket.
- Bulk download counts — one request answers up to 128 npm names, so an 88-package lockfile needs 1 downloads request instead of 88 (scoped names and failed bulk calls fall back to per-name queries).
- Disk cache — verdicts are reused for 24 h (
~/.depvet-cache; override the location withDEPVET_CACHE_DIR). ERROR rows are never cached; use--no-cachefor the freshest data,--cache-ttl SECONDSto tune. - Mirrors / self-hosted registries —
DEPVET_NPM_REGISTRY,DEPVET_NPM_DOWNLOADS,DEPVET_PYPI_REGISTRYpoint depvet at an Artifactory/Nexus mirror; proxied environments fall back to urllib soHTTP(S)_PROXYkeeps working.
Why not Rust? We evaluated a Rust port for this release and rejected it: the wall time is network-bound — waiting on registry CDNs, not computing — so threads + connection reuse + caching recover essentially all of it, while the zero-dependency, single-file, runs-on-any-Python-3.8 property is exactly what makes depvet installable by an agent in seconds. A compiled binary would add a build toolchain and distribution matrix for no measurable win. If a genuinely CPU-bound use case appears (bulk name screening offline at millions of names), a Rust core becomes interesting — see the roadmap.
- Not a malware sandbox — it reads registry metadata, it does not execute package code (that is the point).
- Not a continuous monitor — it gates the moment of install (or a PR's lockfile). It does not watch registries over time; run it per change, and use Socket or Snyk for continuous scanning.
- Not a deep behavioral scanner — lockfile mode vets every pinned package,
but it cannot see what a fresh
npm installwould resolve tomorrow. Pin your deps, run depvet on the lockfile, and keepnpm auditfor advisory data. - Not a blocker of private packages — scoped internal names (
@company/*on your own registry) are explicitly out of scope.
Does it phone anywhere besides the package registry? No. Two GET endpoints per package (registry metadata + download counts), read-only, no auth, no telemetry.
Will it slow my agent down?
No — that was v1.2's whole point: lookups run 8-way concurrent over keep-alive
connections, download counts come from npm's bulk endpoint, and verdicts are
cached on disk for 24 h. A 90-package lockfile scans in ~3 s cold and ~0.1 s
warm. Run --no-cache when you explicitly want the freshest registry data.
Why does a 144M-downloads/week package WARN?
Because axios is factually single-maintainer — the exact profile that made
the Sep 2025 phishing compromise possible. WARN means surface and confirm,
not refuse. Reviewed it? Put it in .depvetrc.json and move on.
Does the allowlist weaken the gate? No. It only silences already-surfaced WARNs, records who/why, and cannot touch BLOCK verdicts (confusable names, dangerous scripts, nonexistent packages, fresh drops).
npm 12 stopped running lifecycle scripts by default — is this obsolete? No, for four reasons: scripts still run on npm < 12, scripted CI installs, yarn/pnpm/bun defaults and every package that opts in; the 2025-26 incident wave (Shai-Hulud, s1ngularity, @acitons) was entirely script-driven; half of depvet's checks don't involve scripts at all (identity, distance, scope, 404/slopsquat, age, maintainers, license); and a package that runs its own scripts still deserves a look before you hand it your machine.
Why check scopes like @acitons against popular scopes?
Because @acitons/artifact (a real Nov 2025 typosquat of
@actions/artifact, used in GitHub Actions workflows) collected ~47k
installs and CI tokens before anyone noticed. depvet warns when a young,
low-adoption package sits under a scope that is 1-2 edits from a famous one.
Can the agent override a BLOCK? No. Only the user can, explicitly. If the user overrides two lookalike-name blocks in one session, the skill stops and re-verifies — that pattern is how typosquat disasters start.
-
--lockfile package-lock.json+--requirements requirements.txtbatch mode (v1.1) - GitHub Action for PR-level dependency gating (v1.1)
- Allowlist for reviewed packages (
.depvetrc.json) (v1.1) - Deprecation / provenance / yanked signals (v1.1)
- Performance pass: concurrent lookups, bulk downloads API, keep-alive + gzip, disk cache — 88-dep lockfile 85.8 s → 2.9 s cold, 0.08 s warm (v1.2)
-
yarn.lock(v1 + Berry) andpnpm-lock.yaml(v6/v9) batch mode,--productiondev-only filtering (v1.3) - 2025-26 IOC wave in install-script checks: webhook exfil endpoints, Discord webhooks, CI/publish token harvesting, Shai-Hulud bun droppers, cloud credential paths (v1.3)
- Scoped typosquat detection (
@acitonsvs@actionspattern) (v1.3) - Go module proxy + crates.io adapters
- MCP server mode (for Claude Desktop and MCP-capable agents)
- Optional Rust core for offline bulk-name screening (only if a CPU-bound use case shows up — measured rationale in Performance)
-
depvet approvecommand to manage.depvetrc.jsoninteractively
PRs welcome — see CONTRIBUTING.
Pattern and structure inspired by the great agent skills (unslop, anatomy). Incident research drawn from OWASP's NPM cheat sheet, FortiGuard, Microsoft Security, Snyk, and Socket research — full list in references/incidents.md.
MIT © 2026 TusharB-07