io.github.CloudCorpRecords/depguard

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

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

depguard check [path] [--json] [--offline] [--online] [--content] [--base <ref>] [--base-path <dir>]
depguard package <name> [version] [--json] [--online] [--content]
depguard history <name> [--json]
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.

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

npm install
npm run build
npm test

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