Depguard

depguard-cli

Find out in seconds whether an npm supply-chain attack reached your machine. When a worm or a hijacked maintainer account ships malicious versions, npx depguard-cli exposure checks every project, global install and the npm download cache on your machine against 100,000+ known-malicious npm packages. It tells you exactly where a bad version is, whether it was installed, and what to rotate. depguard also audits packages before you install them and repositories before you open them. Zero runtime dependencies. Runs in the terminal or as an MCP server for Claude, Cursor, Windsurf and any MCP client.

Was I hit?

npx depguard-cli exposure

depguard exposure scan
  Scanned:     143 lock files, 816 global packages, 167 cached tarballs (14530 distinct versions)
  Under:       /Users/you
  Advisory DB: 2026-10-15 (34952 known-malicious packages)

  OK  No known-malicious package versions found.

When something is found, every location is listed with the evidence and the steps to take:

  EXPOSED  1 known-malicious package version found

  ua-parser-js@0.7.29
    CVE-2021-4229  Maintainer account hijacked. Compromised versions contained XMRig cryptominer and credential stealer. (2021-10-22)
    - lock file    /Users/you/work/api/package-lock.json (node_modules/ua-parser-js)  [installed on disk, runs install scripts]
    - npm cache    tarball downloaded on 2021-10-22

  What to do now:
    1. A malicious version was installed or downloaded on this machine. Treat the machine as compromised...
    2. Rotate every credential reachable from this machine: npm tokens, GitHub tokens and SSH keys, cloud credentials...

What it looks at:

• Every lock file under the given paths (default: your home directory): npm, pnpm, yarn classic and berry, bun. Nested and duplicated copies count, so a malicious version hidden at node_modules/a/node_modules/b is found.
• Globally installed packages (npm root -g).
• The npm download cache. It proves a malicious tarball was downloaded on this machine, and when, even if the project that pulled it is gone.

Only exact matches are reported: a version is flagged only when it falls inside a known-malicious range, and clean versions of packages that were once compromised are never flagged. The data comes from the GitHub Advisory Database, both malware advisories and advisories for legitimate packages that were hijacked to ship malware, refreshed daily. The exit code is 2 when something is found, so it can gate CI:

npx depguard-cli exposure . --skip-global --skip-cache

Why depguard

I work on industrial software where every event has to be logged and recoverable — customers trust the system because the audit trail makes the system trustworthy. When I started wiring AI coding agents into our internal stack, I realised the npm ecosystem treats supply-chain integrity as someone else's problem: install 1,000 packages, hope for the best. depguard brings the same auditability mindset to JavaScript dependencies — verify before installing, audit what's already there, generate an SBOM your security team can actually use.

Zero runtime dependencies — because a security tool that pulls in 200 transitive packages is the joke that writes itself.

Install

npm install -g depguard-cli      # or use directly with npx
npx depguard-cli audit express

MCP server (primary use case)

depguard exposes 15 MCP tools over stdio. Add it to any MCP-compatible client and your AI agent calls them automatically when it's about to install something, audit a project, or review code.

Setup, Claude Code one-liner:

claude mcp add --transport stdio depguard -- npx -y depguard-cli --mcp

Setup — generic MCP config (Claude Desktop, Cursor, Windsurf, Continue.dev, Cline, Roo Code):

{
  "mcpServers": {
    "depguard": {
      "command": "npx",
      "args": ["-y", "depguard-cli", "--mcp"]
    }
  }
}

The 15 tools

Every MCP response includes a tokenSavings field that quantifies the LLM-tokens saved vs equivalent manual research:

"tokenSavings": {
  "responseTokens": 47,
  "manualEstimate": 11100,
  "saved": 11053,
  "percentSaved": 100,
  "manualSteps": [
    "WebSearch: '{package} npm quality maintenance' (~800 tokens)",
    "WebFetch: npm registry page (~3000 tokens)",
    "WebFetch: GitHub repo for activity/stars (~3000 tokens)",
    "WebSearch: '{package} vulnerabilities' (~800 tokens)",
    "WebFetch: advisories page (~3000 tokens)",
    "Reasoning: compute weighted score (~500 tokens)"
  ]
}

Automatic, no configuration. Lets teams quantify the LLM cost reduction of routing dependency questions through depguard instead of free-text web research.

CLI

depguard-cli exposure [paths...] [--skip-global] [--skip-cache] [--max-depth 8] [--json]
depguard-cli audit <package[@version]> [--target-license MIT] [--json|--format sarif]
depguard-cli audit-project <path/package.json> [--include-dev] [--json|--format sarif]
depguard-cli audit-workspace [path] [--json|--format sarif]
depguard-cli audit-deep <package> [--json]
depguard-cli guard <package[@version]> [--threshold 60] [--block] [--json]
depguard-cli should-use <intent...> [--threshold 60] [--json]
depguard-cli sweep [path] [--include-dev] [--json]
depguard-cli review [path] [--full] [--json]
depguard-cli sbom <path/package.json> [--include-vex] [--include-dev] [-o out.json]
depguard-cli remediate <path/package.json> [--json]
depguard-cli search <keywords...> [--limit 10] [--json]
depguard-cli score <package> [--target-license MIT] [--json]
depguard-cli stats [--json]

Pre-install guardian in action:

$ depguard-cli guard expresss
[WARN] expresss
  Possible typosquat of: express
  Score: 45/100 is below threshold 60

$ depguard-cli guard ai-made-up-package
[BLOCK] ai-made-up-package
  Package does NOT exist on npm!

GitHub Code Scanning (SARIF v2.1.0)

audit, audit-project, and audit-workspace accept --format sarif and emit SARIF v2.1.0 with GHSA-stable rule IDs (depguard/vuln/GHSA-…), CVSS-propagated severity, and stable partialFingerprints for dedup across runs.

# .github/workflows/depguard.yml
- name: Pre-open workspace audit
  run: npx -y depguard-cli audit-workspace . --format sarif -o workspace.sarif || true
- name: Project dependency audit
  run: npx -y depguard-cli audit-project ./package.json --format sarif -o project.sarif || true
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: |
      workspace.sarif
      project.sarif

API

import { audit, auditProject, sweep, guard, generateSBOM, auditToSarif } from 'depguard-cli'

const report = await audit('express', 'MIT')
report.vulnerabilities.total     // 0
report.securityFindings          // SecurityFinding[] (static code analysis)
report.licenseCompatibility.compatible // true

const project = await auditProject('./package.json', { includeDevDependencies: true })
project.summary               // { critical: 0, high: 2, moderate: 5, low: 3 }
project.transitiveSummary     // { totalDeps: 800, vulnerable: 12, ... }
project.packageManagerAudit   // audit of `packageManager: yarn@4.5.3`

const sweepResult = await sweep('.', { includeDevDependencies: true })
sweepResult.unused              // [{ name: 'lodash', estimatedSizeKB: 1400, ... }]
sweepResult.estimatedSavingsKB  // 2450

const decision = await guard('expresss')
decision.possibleTyposquat  // true
decision.similarTo          // ["express"]
decision.decision           // "warn"

const bom = await generateSBOM('./package.json', { includeVex: true })
bom.specVersion             // "1.6"
bom.vulnerabilities         // [{ id: "GHSA-...", ratings: [...], affects: [...] }]

What depguard checks

Scoring

Each package is scored 0-100 across five dimensions, with thresholds tuned for AI-agent decision-making:

Decisions (shouldUse): >= 60 → install, 40-59 → caution, < 40 → write from scratch.

Static-analysis caps the security score regardless of popularity — this is deliberate: a wildly popular package with a credential-stealing payload still loses.

Pre-install guardian

Three sequential checks before npm install: (1) does the package exist on npm? (2) is the name a typosquat — Levenshtein distance against 100+ top packages? (3) full security audit. Used as the recommended MCP entry point for AI agents.

Install script analysis

depguard statically pattern-matches preinstall / install / postinstall scripts. Nothing is executed.

Static code analysis (tarball scan)

depguard downloads the package tarball, extracts JS files, and scans for 18+ malware patterns across 6 categories:

Behavioral mismatch compares the package's stated purpose (description + keywords) against detected runtime behavior. A "string formatter" that makes network calls is flagged with a rich SecurityFinding (title, explanation, evidence, file, recommendation).

Dead-dependency detection

sweep scans .js/.ts/.mjs/.cjs/.jsx/.tsx for import / require / export from, recognises config-only dependencies (eslint, prettier, jest, tailwind, …), detects binaries used in npm scripts, pairs @types/* with their runtime peer, and marks untraced devDependencies as "maybe-unused" instead of "unused". Reports estimated disk savings.

Native-alternative advisor

should_use checks for native Node.js APIs before recommending packages — fetch (18+), crypto.randomUUID() (19+), structuredClone() (17+), and 20+ more. Each comes with example code and the minimum Node version.

Fix suggestions

Every vulnerable result includes a fixSuggestions array with currentVersion, fixVersion, and action: 'upgrade' | 'no-fix-available'. depguard_remediate aggregates these and groups vulnerable transitives by the direct dep that pulls them in, sorted by severity weight.

License compatibility

Permissive-to-copyleft hierarchy: Public Domain → Permissive (MIT, ISC, BSD, Apache-2.0) → Weak Copyleft (LGPL, MPL) → Strong Copyleft (GPL) → Network (AGPL). A dependency is compatible if its license is equally or more permissive than the target license.

SBOM (CycloneDX 1.6)

Native CycloneDX 1.6 generation against the public JSON Schema — no @cyclonedx/cyclonedx-library runtime dependency. Output is consumed unchanged by Dependency-Track, Trivy, Grype, and OWASP DT.

depguard-cli sbom ./package.json -o sbom.cdx.json
depguard-cli sbom ./package.json --include-vex --include-dev -o sbom.cdx.json

Suitable for EU Cyber Resilience Act, US Executive Order 14028 / OMB M-22-18, SOC 2, FedRAMP, and supplier procurement. PURLs follow the Package URL spec. SHA-512 integrity hashes are extracted from package-lock.json and converted from base64 to hex per the CycloneDX schema. With --include-vex, advisories are inlined with CVSS ratings and patched versions.

Data, privacy & performance

• Known-malicious packages, bundled. exposure and guard match against a local copy of the GitHub Advisory Database's npm malware advisories plus hijacked-package advisories (CWE-506), refreshed daily, so the check itself makes no network calls. Advisories about packages that were only exposed through a malicious dependency are excluded, and a reviewed exception list overrides the data.
• Two advisory databases, deduplicated. Each advisory is filtered to the installed version range (no noise from advisories that don't actually affect you) and tagged with its source field.

  Source	What it catches
  npm Registry	npm audit advisories
  GitHub Advisory DB	GHSAs, often not in npm

• Everything stays local. No telemetry, no usage reporting, nothing sent anywhere. Audit results are cached in memory (5 min TTL) and on disk under ~/.depguard/cache/ (24h TTL); the cache is cleaned on startup.
• GitHub token (optional). Set GITHUB_TOKEN (no scopes needed — identification only) to raise the GitHub Advisory API rate limit from 60/h to 5,000/h. If gh CLI or GitHub Actions already exposes one, depguard picks it up automatically.

About

Design principles. Zero runtime dependencies. Never throws on network errors — returns degraded results with warnings. TypeScript strict. 100% offline tests. False-positive aversion is a hard constraint for every detection rule — depguard is a security tool, and a security tool with poor precision destroys its own trust.

Development.

npm test          # 543 offline tests
npm run check     # version + build + lint + test + audit:security (gates publish)

Author. Jorge Morais (jorgemopanc.com · LinkedIn) — Tech Lead at Balanças Marques in Braga, Portugal, building edge-to-cloud systems for industrial operations. Issues, PRs, and bug reports welcome. If depguard saves you from a malicious install or unblocks a compliance audit and you'd like to support the project, GitHub Sponsors is the cleanest way — no expectations, the tool is free and will stay so.

License. Apache-2.0 — see LICENSE.