Depguard

io.github.CloudCorpRecordsPublished by GitHub account CloudCorpRecordsv0.4.0Updated Nov 2, 2026

PR dependency early warning: install scripts, typosquats, downgrades, and lockfile drift.

VerifiedSTDIODesktop onlyDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

Depguard grades npm dependency changes in a repo diff — install scripts, typosquats, downgrades, lockfile drift — and returns CLEAR/REVIEW/HIGH-RISK verdicts.

What you can do
  • Diff a repo's manifests and lockfiles against a git ref or base directory and grade every added, removed or changed dependency
  • Grade a single package name and version for typosquat shape and version-pattern anomalies
  • Analyze a package's registry publish history for staged worm patterns, maintainer and repository changes, and provenance drops
  • Optionally add registry checks (version age, publisher change, provenance, deprecation) or static tarball content diffs when online or content mode is enabled
When to use it
Useful when reviewing pull requests or dependency bumps in npm (and partly PyPI) projects and you want an automated early warning before a change merges. It suits supply-chain review of new or changed packages rather than general code review.
Requirements
Runs locally over stdio, via npx or the Docker image; Node.js 20 or newer for the npm package. No accounts, API keys or environment variables are declared. The offline core needs no network; online registry checks and content mode require network access to the npm or PyPI registry.
Before you install
Verdicts are advisory heuristics: typosquat detection is name-shape only, provenance means an attestation entry exists rather than being verified, and nested workspace manifests are not inventoried. Content mode downloads tarballs from the registry (extracted in memory, never executed), so package names and versions are sent to the registry. Findings are not proof of malicious code.

Installation

In SourceWeft

  1. Open Depguard in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

depguard

PR-time and dependency-change early warning for npm repos. The Shai-Hulud / ChainDrop worm family backdoored 500+ npm packages in 2026, executing at install time through preinstall dropper scripts and propagating through the dependency graph. depguard is the diff-time check: given a repo and a base (a git ref or a second manifest set), it diffs package.json and the lockfiles, and grades every added, removed, and changed dependency with evidence, before the change merges.

The base verdict is fully offline and deterministic. Registry checks (version age, publisher change, provenance, deprecation) run only behind an explicit --online flag or the matching MCP parameter, and a failed lookup never changes the local verdict.

What it checks

SignalSourceRule ids
New install scripts in the repo's own package.json, escalated when the content fetches remote code, reads credentials, or runs the documented setup.mjs dropper namelocalINSTALL-SCRIPT-ADDED, INSTALL-SCRIPT-CHANGED
A changed dependency newly marked as having an install script in the lockfile; install scripts present on added dependencieslocalINSTALL-SCRIPT-ADDED, INSTALL-SCRIPT-PRESENT
Typosquat-shaped added names: edit distance 1 (or 2, longer names) against the repo's own existing dependency set and a bundled popular-names list (about 380 names, shipped in the package)localTYPOSQUAT-SUSPECT, TYPOSQUAT-POSSIBLE
Version anomalies: silent downgrades, stable-to-prerelease jumps, non-semver versions, ranges widened (to * or latest is high), newly added unpinned rangeslocalDOWNGRADE, PRERELEASE-JUMP, VERSION-PATTERN, RANGE-WIDENED, RANGE-UNPINNED
Lockfile drift: manifests changed but the lockfile is identical; lockfile changed with no manifest change; resolved URL host changes for the same version; integrity hash removed or changed at the same versionlocalLOCKFILE-DRIFT, LOCKFILE-ONLY-DRIFT, RESOLVED-HOST-CHANGE, INTEGRITY-REMOVED, INTEGRITY-CHANGED
Manifest dependencies with no lockfile entry (single-snapshot mode)localLOCK-MISSING
Version published under 7 days ago; publisher or maintainer change versus the previous version; missing provenance attestation; deprecation marking; version absent from the registryonline onlyVERSION-AGE, MAINTAINER-CHANGE, NO-PROVENANCE, DEPRECATED, VERSION-NOT-FOUND
Content diff of the two versions' tarballs: a version bump that adds an install script, or adds credential-path strings, network endpoints, binaries, or obfuscation-shaped code in install-reachable files (the script targets plus their relative imports). A quiet bump that adds a preinstall loading credential paths grades HIGH-RISK and names the added signals; a benign build postinstall with no such signals does not grade highcontent mode only (--content)CONTENT-INSTALL-SCRIPT-ADDED, CONTENT-INSTALL-SCRIPT-CHANGED, CONTENT-CRED-SIGNAL-ADDED, CONTENT-NETWORK-ENDPOINT-ADDED, CONTENT-BINARY-ADDED, CONTENT-OBFUSCATED-ADDED
Registry publish history: the staged worm pattern (a 0.0.0-stage stub, a decoy-looking release, then a rapid regressed patch holding dist-tags.latest), stage stubs, latest-version regression, rapid regressed clusters, publisher and maintainer changes, repository slug changes, provenance dropshistory mode (depguard history <name>)HISTORY-STAGED-PATTERN, HISTORY-STAGE-STUB, HISTORY-LATEST-REGRESSION, HISTORY-RAPID-REGRESSION, HISTORY-MAINTAINER-CHANGE, HISTORY-REPO-CHANGE, HISTORY-PROVENANCE-DROP, HISTORY-PACKAGE-NOT-FOUND

Lockfiles: package-lock.json is parsed fully (v1 legacy tree and v2/v3 packages map). yarn.lock and pnpm-lock.yaml are parsed best-effort for resolved entries and versions.

Verdicts: per dependency and overall, CLEAR / REVIEW / HIGH-RISK, with one evidence line per finding naming the dep, the change, the rule id, the severity, and whether the signal is local or online. Exit code is 0 for CLEAR and 1 for REVIEW or HIGH-RISK.

CLI

bash
depguard check [path] [--json] [--offline] [--online] [--content] [--base <ref>] [--base-path <dir>]depguard package <name> [version] [--json] [--online] [--content]depguard history <name> [--json] [--registry npm|pypi]depguard mcp

history (v0.3.0, ledger P-159) analyzes one package's registry publish history for the staged worm pattern and related signals. It reads registry metadata only and downloads no tarballs. Since v0.4.0, --registry pypi (or the registry parameter on check_history) reads PyPI history through its JSON API instead: the same timeline checks (staged pattern, stage stub, latest regression, rapid regression) run on per-version upload times, plus a PyPI-specific HISTORY-YANKED-VERSION finding for releases whose files are all yanked. PyPI publishes no per-version publisher, maintainer, repository, or provenance data through that API, so those npm checks do not fire on PyPI histories.

check defaults to the offline core against the current directory, as a single snapshot (every manifest dependency graded on what is here now). Pass --base HEAD~1 (any git ref) or --base-path <dir> to diff against a base. package grades one name without a repo. There are no timestamps in the JSON report, so identical inputs produce byte-identical output.

--content adds content-based update vetting (v0.2.0, ledger P-158): for every changed or added dependency, and for snapshot pins with a prior published version, depguard fetches both versions' tarballs from the npm registry and diffs the install-time surface statically. Tarballs are extracted in memory only: depguard never installs or executes anything from a tarball. In package mode with --content, the named version is diffed against the greatest lower published version.

MCP

One bin serves the CLI and a stdio MCP server (depguard mcp). Tools:

  • guard_path(path, base?, base_path?, online?, content?): the full diff report as JSON.
  • check_package(name, version?, online?, content?): grade a single package name and version.
  • check_history(name): analyze a package's registry publish history for staged-pattern and related signals.

Limits

  • Root manifests only: nested workspace package.json files and nested lockfiles are not inventoried in v0.1.0. (Ledger P-132, documented limit.)
  • pnpm-lock.yaml parsing is key-based and best-effort: resolved tarball URLs are captured only where the lockfile layout exposes them inline, so resolved-host drift detection is strongest on package-lock.json, then yarn.lock, then pnpm-lock.yaml.
  • Install scripts of dependencies themselves are known only where the lockfile records them (package-lock hasInstallScript) or, online, where registry metadata declares them. Content mode (--content, v0.2.0) goes one step further and downloads the two versions' tarballs to diff their install-time surface, but the inspection is static only: tarballs are extracted in memory, nothing is installed, and no tarball code is ever executed. Offline and online modes download nothing.
  • Content mode follows install script targets and their relative imports to depth 3; signals buried deeper in a dependency's own internal graph, or generated at install time, are out of reach of this signal.
  • Typosquat detection is name-shape only. A name that is itself a bundled popular name is never flagged (ledger P-130), and a well-chosen name at edit distance 3 or more is out of reach of this signal by design.
  • Online signals are only as good as the registry packument: publisher comparison uses the recorded publisher of the greatest lower version, and provenance means an attestation entry exists in registry metadata, not that it was verified.
  • Caps are explicit, never silent: lockfile parsing stops at 50,000 entries and any manifest file over 64 MiB is skipped, both reported in the output (caps in JSON, a cap line in human output, plus warnings).

Development

bash
npm installnpm run buildnpm test

TypeScript, Node >= 20, tests with tsx --test, no network in unit tests (registry responses are injected fixtures).

Source: README.md at commit e1d357f

Tools

3

guard_path

Diff a repo's dependency manifests and lockfiles against a base (git ref or directory) and grade every added, removed, and changed dependency: install scripts, typosquat-shaped names, downgrades, prerelease jumps, widened ranges, and lockfile drift. Fully offline unless online is true, which adds npm registry checks (version age, publisher change, provenance, deprecation).

Parametersbasepathrequiredonlinecontentbase_path

check_package

Grade a single package name (and optional version): typosquat distance against a bundled popular-names list and version pattern checks offline; with online true, registry checks for version age under 7 days, publisher change versus the previous version, provenance attestation, and deprecation.

Parametersnamerequiredonlinecontentversion

check_history

Analyze a package's registry publish history for the staged worm pattern (a 0.0.0-stage stub, a decoy release, then a rapid regressed patch holding dist-tags.latest), plus publisher and maintainer changes, repository slug changes, and provenance drops between consecutive versions. The registry defaults to npm; with registry pypi it reads PyPI history instead (the same timeline checks, plus yanked-version findings, since PyPI publishes no per-version publisher data). Registry metadata only; no tarballs are downloaded.

Parametersnamerequiredregistry

Version history

3
  1. v0.4.0LatestOct 26, 2026
  2. v0.3.0Oct 23, 2026
  3. v0.1.0Oct 22, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts