NPMScan

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

Detect malicious or vulnerable npm packages: registry search, OSV.dev and GitHub advisory lookups

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "NPMScan": {
      "url": "https://npmscan.com/api/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (23)

• search_packages read-only

  Search the npm registry by name or keywords. Each result includes its current weekly/monthly download counts, dependentsCount (how many other npm packages depend on it), topPackagesRank (position among npmscan's own top-100k-by-downloads snapshot — not live, but a second independent popularity signal), and deterministic (not model-generated) popularityTier/maintenanceTier labels — a package matching the query with a 'very-low' popularityTier, zero dependents, or a 'stale' maintenanceTier is very likely an abandoned, copy-paste, or squatted package, not a real contender, regardless of how relevant its name/description look. A result may also carry possibleTyposquatOf — set when its name is one typo away (e.g. 'raect' vs 'react') from a top-5,000 package while itself having very low popularity; treat that as a red flag to call out explicitly, not silently filter. Use these (not name recognition or the package's own README) to judge which candidates are actually established, and call get_package on your shortlist for install-script risk, TypeScript support, and GitHub stars before recommending one. Includes a link to each package's full npmscan.com risk/analysis page.

  Parameters:

  • query (required) — string — Search text, e.g. a package name or keywords
  • limit — integer — Max results to return (default 20, max 50)

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• get_package read-only

  Fetch npm registry metadata for a package: latest version, install scripts (preinstall/postinstall are a key risk signal), maintainers, license, recent version history, weekly downloads, GitHub stars, TypeScript support, days since last publish, a topPackagesRank (position among npm's ~100k most-downloaded packages, from npmscan's own periodically-refreshed snapshot — not live), and a downloadTrend (growing/stable/declining vs. ~3 months ago). Also checks the LATEST version against OSV.dev for known vulnerabilities — isLatestVersionVulnerable/highestSeverity give a direct safe/not-safe answer, and each finding includes severity, a summary, and the fixedVersion to upgrade to (use get_package_version or query_vulnerabilities to check a specific older version instead). If the OSV.dev query itself fails (network/timeout/upstream outage), isLatestVersionVulnerable comes back `false` only because the field has to be a boolean — vulnerabilityCheckFailed:true is the real signal there, and means the safe/not-safe answer is unknown, not confirmed clean. Also returns popularityTier/maintenanceTier (deterministic rule-based labels, not model-generated) and a plain-language maintenanceSummary, plus a possibleTyposquatOf flag if the name is one typo away from a top-5,000 package while itself being obscure — read `deprecated` and maintenanceSummary before recommending a package, since a long gap since the last release can mean either a stable/finished package or a slowing one. Includes a link to the full npmscan.com analysis page.

  Parameters:

  • name (required) — string — Exact npm package name, e.g. "lodash" or "@scope/name"

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• get_package_version read-only

  Fetch registry metadata for one exact version of a package (dependencies, install scripts, tarball) AND check that exact version against OSV.dev for known vulnerabilities — isVulnerable/highestSeverity give a direct answer, and each finding includes severity, a summary, and the fixedVersion to upgrade to. Use this to check a version pinned in a lockfile rather than the latest release. If the OSV.dev query itself fails (network/timeout/upstream outage), isVulnerable comes back `false` only because the field has to be a boolean — vulnerabilityCheckFailed:true is the real signal there, and means the answer is unknown, not confirmed clean.

  Parameters:

  • name (required) — string — Exact npm package name
  • version (required) — string — Exact version string, e.g. "4.17.21", or a dist-tag such as "latest" (resolved to its exact version before the vulnerability check). Semver ranges like "^4.17.0" are not supported.

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• get_maintainer_profile read-only

  Given an npm username, returns every package npm's own maintainer:<username> search index currently returns for that account (registry.npmjs.org's /-/v1/search — the public registry API has no dedicated 'list packages by maintainer' endpoint otherwise), plus precomputed aggregates: currentlyMaintainsCount (still listed as maintainer right now vs. already-revoked), totalWeeklyDownloads and totalDependents summed across every returned package, and avatarUrl — a proxied Gravatar image (null if no email is on record). This is a plain info lookup — it does NOT run the publish-cluster / compromised-account detection that check_maintainer_blast_radius does; use that tool instead when the goal is a security read on whether this account's recent activity looks like a takeover, not just a profile summary. Natural pairing with check_maintainer_changes: once that tool names a maintainer on a package, call this with that maintainer's username to see the rest of what they touch. npmscanUrl is this account's profile page on npmscan itself; npmProfileUrl is the account's actual page on npmjs.com, included for verification since that's the authoritative record of the account.

  Parameters:

  • maintainerUsername (required) — string — Exact npm username, e.g. "sindresorhus" — as shown at npmjs.com/~username. Not an email address, not a package name or scope.
  • limit — integer — How many packages to list (default 50, max 250), most-downloaded first. Totals still cover every package found.

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• query_vulnerabilities read-only

  Query OSV.dev for known vulnerabilities affecting an npm package, optionally scoped to one exact version (e.g. to check whether a version pinned in a lockfile is safe). Returns isVulnerable and highestSeverity as a direct answer, plus each finding's severity, a plain-language summary, CVE aliases, and the fixedVersion to upgrade to — not a raw advisory dump. Also cross-checks the name/version against the npm registry: isVulnerable:false on a package that does not actually exist there (typo, wrong ecosystem) would otherwise look identical to a genuinely clean result — see packageExists/existenceCheckNote. A name or version not found on the registry does NOT discard already-fetched OSV data or short-circuit into an error: OSV/GHSA advisory data is independent of the package's current registry listing, and a package/version pulled from npm for being malicious (unpublished/yanked) is exactly the case where real vulnerability data must still be reported, not hidden behind a 404. Use before recommending, installing, or upgrading a package.

  Parameters:

  • name — string — npm package name (required; `packageName` is accepted as an alias)
  • version — string — Optional exact version to narrow results, e.g. to check one version pinned in a lockfile. For the npm ecosystem a dist-tag such as "latest" is also accepted and resolved to its exact version first; semver ranges like "^4.17.0" are rejected.
  • ecosystem — string — OSV ecosystem, default "npm"
  • packageName — string — Alias for `name`, matching simulate_dependency_upgrade/prioritize_remediation

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• batch_query_vulnerabilities read-only

  Check a whole npm dependency inventory against OSV.dev in one call: pass `packages: [{name, version?}]`, or raw package.json / package-lock / yarn.lock / pnpm-lock / CycloneDX / SPDX content via `content`. Large inventories are chunked automatically. Each finding has severity, summary, CVE aliases, fixedVersion and isMalware, so no per-package follow-up is needed. Before calling anything clean, read: - `unresolvedPackages`/`nonexistentVersions` (and each result's `registryStatus`): a name or version not on npm shows vulnerabilityCount 0 just like a clean package. A version npm removed can still have real OSV findings (often malware). - A `packages` entry with no version is checked against every historical version; confirm against the version actually in use before calling it vulnerable. - `signals` (deprecated, hasInstallScripts, popularity/maintenance tiers, possibleTyposquatOf): 0 vulnerabilities can still be deprecated, abandoned or a typosquat. `signals` is null for git/file/workspace/URL entries, which are not scanned. - `source` (lockfile input): `nonRegistryHost` means the tarball comes from an unexpected host; `identityMismatch` means it is a different package/version than declared (`resolvedName`/`resolvedVersion`) and the counts describe the declared one. Treat both as lockfile tampering. - Use `uniqueVulnerabilityCount` for distinct issues; raw counts can list one CVE twice. - package.json input: `projectLifecycleScripts`/`projectLifecycleScriptRisk` are the project's own install scripts; peerDependencies are skipped unless `includePeerDependencies: true` (see `ignoredPeerDependencyNames`); `declaredSpec` marks a version resolved from a range, which can change on the next install. - npm aliases are followed: `package.actualName` is the real package the data describes.

  Parameters:

  • content — string — Raw dependency inventory content: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, CycloneDX JSON, or SPDX JSON. Use this OR `packages`, not both.
  • packages — array — Explicit package list (1-1000 items). Use this OR `content`, not both.
  • includeDevDependencies — boolean — Ignored when using `packages`; only applies when `content` is a manifest/lockfile format that distinguishes dev dependencies.
  • includePeerDependencies — boolean — Ignored when using `packages`; only applies when `content` is a package.json. peerDependencies are excluded from scanning by default (see ignoredPeerDependencyNames) since a peer is often intentionally left unresolved by the consumer — set this to also check them.

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• get_latest_advisories read-only

  Browse recently published npm security advisories and known-malicious-package findings. Three disjoint sources, selected via type: "reviewed" (default) is GitHub's curated, mostly CVE-backed advisories; "malware" is GitHub's own known-malicious-package advisories; "osv" is OSV.dev's OpenSSF malicious-packages feed, a separate dataset whose entries use MAL-/OSV ids rather than GHSA ids. None of "malware"/"osv" carry a CVE or meaningful CWE beyond "embedded malicious code". Filter by severity, vulnerability category (XSS, SQL/NoSQL Injection, SSRF, Access Control, Code Injection, etc. — reviewed only), an affected package name, or (reviewed/malware only) look up one exact advisory by GHSA or CVE ID. Advisories GitHub has withdrawn (most often "Duplicate Advisory: ..." records merged into a canonical GHSA) are excluded from browse results, so a page can hold fewer than 30 entries; an exact ghsaId/cveId lookup still returns a withdrawn advisory, with withdrawnAt set — treat it as retracted, not as a live finding. Paginated with an opaque cursor: pass a previous response's nextCursor back in as cursor to fetch the next page.

  Parameters:

  • type — string — Advisory source: "reviewed" (curated CVE-style, default), "malware" (GitHub-curated known-malicious packages), or "osv" (OSV.dev/OpenSSF malicious-packages feed)
  • cveId — string — Look up one exact advisory by its CVE ID (e.g. "CVE-2024-12345") — reviewed/malware only
  • cursor — string — Opaque pagination cursor from a previous response's nextCursor, to fetch the next page
  • ghsaId — string — Look up one exact advisory by its GHSA ID (e.g. "GHSA-xxxx-xxxx-xxxx") — reviewed/malware only
  • affects — string — Filter to advisories affecting this npm package name
  • category — string — Filter by vulnerability category (reviewed only). One of: access-control, dos, xss, ssrf, auth, code-injection, info-exposure, path-traversal, input-validation, prototype-pollution, command-injection, sqli, crypto, race-condition, open-redirect, csrf, crlf-injection, xml-injection, malicious-code, deserialization
  • severity — string — Filter by severity (default all; not applicable to "malware"/"osv")
  • direction — string — Sort by published date, newest or oldest first (default desc)

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• get_cve read-only

  Look up authoritative NIST NVD data for one exact CVE ID (e.g. "CVE-2026-2950"), or browse/search NVD by keyword, CVSS severity, CWE, or a publication-date range. Every result is enriched with CISA KEV status (`kev`, non-null only if this CVE is a confirmed, actively-exploited-in-the-wild vulnerability — treat that as an urgent-patch signal regardless of CVSS score) and FIRST.org EPSS (`epss`, the probability of exploitation in the next 30 days — a better prioritization signal than CVSS severity alone, which measures impact, not likelihood). If the KEV or EPSS lookup itself fails (network/timeout/upstream outage), `kev`/`epss` come back `null` only because those fields have to be nullable — `kevCheckFailed`/`epssCheckFailed` (true in that case) is the real signal, and means "unknown", not "confirmed absent/unscored". For a search, a failed EPSS batch call sets `epssCheckFailed` on every result in that response, since one call scores every id together; `kevCheckFailed` is tracked per-CVE since each is looked up independently. For a single cveId lookup, if NVD has no record yet or hasn't scored it, this falls back to the raw MITRE CVE record automatically (`source: "mitre"` on the result) rather than returning nothing. NVD is NOT npm-scoped — unlike query_vulnerabilities/get_latest_advisories, search results can include CVEs for any ecosystem, so pass keywordSearch (e.g. the package name) to narrow it. Prefer this for the authoritative CVSS score/vector/KEV/EPSS data on a CVE already found via another tool, or when a user pastes a CVE ID/link directly; prefer get_latest_advisories for npm-specific browsing. NVD enforces a strict shared rate limit, so this tool may occasionally ask you to retry in a few seconds — do so rather than assuming failure.

  Parameters:

  • cveId — string — Exact CVE ID for a single lookup, e.g. "CVE-2026-2950". When given, search filters below are ignored and should be omitted.
  • cweId — string — Filter by weakness type, e.g. "CWE-79"
  • severity — string — Filter by CVSS v3 base severity
  • startIndex — integer — Pagination offset for a search
  • keywordSearch — string — Free-text search, e.g. a package or product name
  • publishedSince — string — Publication date range start (YYYY-MM-DD). Must be given together with publishedUntil.
  • publishedUntil — Publication date range end (YYYY-MM-DD). Must be given together with publishedSince; range is capped at 120 days.
  • resultsPerPage — integer — Max results for a search (default 10, capped at 50)

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• analyze_install_script read-only

  Statically scans a package's preinstall/install/postinstall/prepare lifecycle scripts AND the file(s) they reference — fetched directly from the published tarball, not just the command string in package.json — against npmscan's documented red-flags rubric (/docs/red-flags): child_process use, network calls, access to sensitive paths/env (.ssh, .aws, .npmrc, *TOKEN/*KEY), obfuscation, remote binaries hosted off trusted CDNs, writes to HOME, Discord/Telegram/Pastebin exfil endpoints, eval on decoded strings, chmod+exec of downloaded binaries, and CI-metadata telemetry — plus a possibleTyposquatOf name check. Returns a weighted totalScore and riskTier ('none'/'low'/'moderate'/'high'/'critical'). This is a heuristic static scan, not proof of malice or a guarantee of safety: it doesn't execute any code, can't see behavior gated on runtime conditions, and does NOT check maintainer/ownership history (a separate red-flags signal this tool doesn't cover). Use get_package/get_package_version first for the raw script listing; use this when you need to know what an install script actually does, not just that one exists.

  Parameters:

  • name (required) — string — Exact npm package name, e.g. "lodash" or "@scope/name"
  • version — string — Exact version to analyze; omit to use the latest published version

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• analyze_transitive_dependencies read-only

  Walk one or more root packages' dependency trees (e.g. a package.json "dependencies" section) up to `maxDepth` levels (default 2, max 3) and check every resolved package@version against OSV.dev, so vulnerabilities several levels down still surface. Read `summary` first; `vulnerablePaths` answers "which of my dependencies pulled this in"; `nodes` has the full graph. npm aliases are followed (`actualName`). Before calling a result clean: - A node with `resolutionError` (unsatisfiable range, 404, or a git/file/workspace/URL specifier) has `isVulnerable: null` — it was never scanned, not clean. - Only "dependencies" are followed (not dev/peer/optional). Each range is resolved independently to its max-satisfying version, so this shows which vulnerable versions are reachable, not npm's exact hoisted install. - The walk has a node budget: check `truncated`/`truncationNote`. Use batch_query_vulnerabilities instead when you already have a flat list of exact versions (faster, no graph walk).

  Parameters:

  • packages (required) — array — 1-15 direct/root packages to expand from, e.g. a package.json's "dependencies". version accepts an exact version or a semver range like "^4.17.21"; omitted = latest.
  • maxDepth — integer — How many levels of transitive dependencies to expand beyond the given root packages (0 = only check the roots themselves). Default 2, capped at 3 to bound registry calls and stay within the request timeout.

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• check_package_provenance read-only

  Checks whether a package version was published with npm's own Sigstore-backed publish provenance (`npm publish --provenance`), and cross-checks that provenance against reality rather than just reporting its presence. Three checks: (1) parses the SLSA build attestation (declared source repo, commit, builder identity, GitHub Actions run URL) and flags a builder that isn't GitHub-hosted, or an attested source repo that doesn't match package.json's own `repository` field; (2) when this version LACKS provenance, checks whether most peer packages (same npm scope, or same maintainer for an unscoped name) DO have it — a package that's the odd one out in an org that otherwise always publishes from CI is a real anomaly, not proof of malice; (3) fetches package.json from the source repository at the exact attested commit (or a best-effort matching git tag when no provenance/commit is available) and diffs its install-lifecycle scripts (preinstall/install/postinstall/prepare) and dependency names against what's actually in the published tarball — this is the single highest-signal check here, since a script or dependency that exists on npm but was never committed is exactly the pattern of a stolen-npm-token publish that bypasses CI (the event-stream/ua-parser-js incident shape). This is a heuristic, structural check: it does NOT cryptographically re-verify the Sigstore bundle (Fulcio cert chain, Rekor inclusion proof) — it trusts that npm's registry already refused to accept a publish that failed that verification, and checks the CONTENT of what the registry reports instead. Most packages don't use --provenance yet, so its bare absence is never scored on its own — only an org-norm anomaly or an actual source mismatch is. Use get_package/get_package_version first for basic package info; use this specifically to assess publish-integrity risk.

  Parameters:

  • name (required) — string — Exact npm package name, e.g. "lodash" or "@scope/name"
  • version — string — Exact version to check; omit to use the latest published version

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• check_maintainer_changes read-only

  Reconstruct who has controlled an npm package and when, straight from the packument (each version records the maintainer list at publish time and who ran `npm publish`). Use it for the 'who controls this package, and did that change recently' question; use get_package/check_package_provenance for general health and publish integrity. Flags: 1. a maintainer added recently who then published soon after, on a package with real prior history — the takeover shape behind ua-parser-js, event-stream and the 2025 chalk/debug ('qix') compromise 2. the whole maintainer list replaced at once 3. a long-standing maintainer quietly dropped 4. a maintainer change on npm AFTER the latest release — more urgent: access changed hands but nothing has shipped yet It also checks the declared GitHub repository: transferred or renamed (`repository.ownerLogin`/`ownerAvatarUrl` show the CURRENT owner), unreachable, or a latest release that landed long after any real push activity. If it flags a newly added or fully replaced maintainer, follow up with check_maintainer_blast_radius on that username to see whether the same account touched other packages at the same time. Findings are signals to verify, not proof of compromise.

  Parameters:

  • name (required) — string — Exact npm package name, e.g. "lodash" or "@scope/name"

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• check_maintainer_blast_radius read-only

  Given an npm username, lists the packages npm's maintainer:<username> search index returns for that account and looks for a tight cluster of packages whose latest version was published within a short rolling window of each other — the shape of a compromised-account supply-chain attack, where a stolen credential is used on every package the account can publish to within hours (e.g. the September 2025 chalk/debug compromise, ~18 packages in ~2 hours). A large total package count is not itself a red flag; only a tight publish-time cluster is scored, weighted by its package count and combined weekly downloads/dependentsCount. Clusters mostly within one npm scope (a monorepo release) are dampened, and multiple clusters combine with diminishing returns. isCurrentMaintainer shows whether the account still maintains each package. avatarUrl is a proxied Gravatar image (null if no email is on record). Natural follow-up to check_maintainer_changes: call this with a newly added maintainer's username to see whether the same account touched other packages around the same time. Limitations: npm's search index can lag or omit packages; results are capped at 250 packages ranked by relevance, not recency (see resultsTruncated/totalPackagesFound); lastPublished reflects only each package's latest version. npmscanUrl is the account's npmscan profile; npmProfileUrl is its npmjs.com page.

  Parameters:

  • maintainerUsername (required) — string — Exact npm username, e.g. "sindresorhus" — as shown at npmjs.com/~username. Not an email address, not a package name or scope.
  • limit — integer — How many packages to list (default 50, max 250), most-downloaded first. Totals still cover every package found.

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• check_license_compliance read-only

  Given a list of packages (name + optional exact version or semver range — e.g. straight from a package.json "dependencies" object) and an optional allow/deny license policy, resolves each package's declared SPDX license and reports a compliance verdict per package. Classifies every license into one of permissive/weak-copyleft/copyleft/network-copyleft/proprietary/public-domain/unknown, and understands simple SPDX expressions: "(MIT OR GPL-3.0)" is compliant if EITHER side is permitted (a consumer may legally pick the clean alternative), "MIT AND Apache-2.0" requires both sides to pass, and "X WITH exception" is judged on X. A mixed/nested expression like "(MIT OR ISC) AND Apache-2.0" is reported as needsReview rather than guessed at. `policy.deny` entries always win over `policy.allow` (so a name can appear in both without a silent contradiction); with `policy.allow` set, anything not matching it is a violation (unproven is treated as non-compliant); with neither given, the default policy flags only copyleft/network-copyleft/proprietary (e.g. GPL/AGPL/UNLICENSED) — weak-copyleft (LGPL/MPL/EPL) and unrecognized license strings are surfaced but not auto-flagged. Policy entries accept an exact SPDX id, a family prefix ("GPL" catches GPL-2.0/GPL-3.0-only/etc.), or a category name. This reads only the registry-declared `license` field — it does not fetch or parse LICENSE file contents from the source repository.

  Parameters:

  • packages (required) — array — 1-100 packages to check. version accepts an exact version or a semver range like "^4.17.21"; omitted = latest.
  • policy — object — Omit entirely to use the default policy: only copyleft/network-copyleft/proprietary are violations.

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• diff_dependencies read-only

  Compare two snapshots of a package.json, package-lock.json (v1-v3), yarn.lock (classic or Berry) or pnpm-lock.yaml (e.g. before/after a PR; formats can differ) and report added, removed and changed packages. Lockfiles cover the full resolved graph, so transitive-only changes are caught; npm aliases are followed (`actualName`). Up to 100 added/changed packages are checked in detail. Ideal for a CI gate. Per added/changed package: - `installScriptIntroduced`: a preinstall/install/postinstall script the old version lacked — the shape of a compromised-maintainer release. `prepare` never runs on a registry install, so it is excluded; `installScriptKeysIntroduced` lists every new key, prepare included. - `sourceIntegrityChanged`: the same version now resolves to a different tarball URL or hash, or a bump moved to another host (ordinary bumps are not flagged). A same-version swap is `changeType: "source-swap"`. - `identityMismatch`: the tarball is a different package or version than declared; `tarballName`/`tarballVersion` say what really installs, and the vulnerability fields describe that. - `vulnerabilityDelta` (introduced/fixed/still-vulnerable/still-clean) plus the findings, each with isMalware. Project-level: `projectLifecycleChanges` diffs the project's own root install scripts (package.json only; a PR that only adds a root postinstall changes no dependency), and `overridesChanges` diffs overrides/resolutions/pnpm.overrides, from package.json or between two pnpm-lock.yaml files (removing one can let a vulnerable version back in). Both count toward `flaggedCount`. Read `comparisonNote` when the two snapshots differ in format. Install-script checks are presence-only; use analyze_install_script to see what a script does.

  Parameters:

  • before (required) — string — Raw file content of the "before" snapshot — a package.json, package-lock.json (npm v1-v3), yarn.lock (classic v1 or Berry), or pnpm-lock.yaml. Format is auto-detected; before/after may be different formats.
  • after (required) — string — Raw file content of the "after" snapshot — a package.json, package-lock.json (npm v1-v3), yarn.lock (classic v1 or Berry), or pnpm-lock.yaml. Format is auto-detected; before/after may be different formats.

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• prioritize_remediation read-only

  Rank vulnerability findings other tools already returned (batch_query_vulnerabilities, query_vulnerabilities, analyze_transitive_dependencies, diff_dependencies...) by what to fix first. Pass up to 200 `{packageName, cveId?, severity?, advisoryId?, currentVersion?, fixedVersion?, findingType?}`. Each gets a tier: remove-now / patch-now / patch-soon / scheduled / monitor. How the tier is decided: - remove-now: confirmed malware — `findingType: "malware"`, a MAL-* advisoryId, or an advisoryId whose OSV record is a malware advisory (CWE-506 or a MAL-* alias, looked up automatically). Malware is removed, not patched. Advisories that could not be looked up are listed in `malwareCheckFailedAdvisoryIds`. - patch-now: on the CISA KEV list (actively exploited), whatever the severity. - otherwise a score led by FIRST.org EPSS (30-day exploitation probability), with severity as a secondary signal — or the only signal when there is no EPSS data (no CVE id). An EPSS of 10% or more always ranks at least patch-soon. The tier is a fix-ORDER across a backlog, not a severity verdict or a merge gate: a CRITICAL CVE with low EPSS can rank monitor. Never describe a monitor/scheduled finding as "low severity", and judge whether a change that INTRODUCES a vulnerability is acceptable by its severity, not this tier.

  Parameters:

  • findings (required) — array — 1-200 previously-flagged vulnerability findings to rank

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• simulate_dependency_upgrade read-only

  Before running npm install, check whether upgrading a package from a current to a target version is safe. Pass `packageName` + `currentVersion` + `targetVersion` (omit target for "latest"), or `packages: [...]` (1-100) to check many in one call; a name that cannot be resolved comes back with `fetchError` instead of failing the batch. A natural follow-up to prioritize_remediation: pass its packageName/currentVersion/fixedVersion straight in. What it checks: - semver jump (major/minor/patch/prerelease; a 0.x minor bump counts as breaking; skipped majors are flagged) - registry signals on the target: deprecated, a newly added preinstall/install/postinstall script (`installScriptIntroduced`; a new `prepare` is listed in `installScriptKeysIntroduced` but never runs on a registry install), a tightened engines.node, prerelease - OSV for both versions: `vulnerabilityDelta` (introduced/fixed/still-vulnerable/still-clean) and `targetVulnerabilities` with isMalware — catching a "fix" that does not clear every CVE Result: one `riskTier` — safe / low-risk / review-recommended / breaking-change-likely / unknown / do-not-upgrade — with `reasons`. `do-not-upgrade` means the target is known malware, or npm no longer lists it while OSV still has advisories for it (how npm removes malicious releases). It does not read changelogs or diff source; it is a fast pre-check, not a substitute for release notes on a major bump.

  Parameters:

  • name — string — Alias for `packageName`, matching the other tools
  • packages — array — Batch of upgrades to simulate (1-100 items), each mirroring the single-item packageName/currentVersion/targetVersion fields. Use this OR packageName/currentVersion, not both. Natural pairing with prioritize_remediation: pass its ranked findings straight in as one call instead of one simulate_dependency_upgrade call per finding.
  • packageName — string — Exact npm package name, e.g. "lodash" or "@scope/name". Use this (with currentVersion) OR `packages`, not both.
  • targetVersion — string — Version to simulate upgrading to — exact version, range, or dist-tag (e.g. the fixedVersion a prioritize_remediation finding named). Omit to use the registry's "latest" dist-tag. Only applies to the single-item `packageName` form.
  • currentVersion — string — Currently installed version — an exact version (e.g. "4.17.20"), a semver range (e.g. "^4.17.0"), or a dist-tag. Required when `packageName` is used.

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• suggest_alternative read-only

  Given a package that looks deprecated, vulnerable, abandoned, or suspicious, suggest better-maintained alternatives in the same category. This tool first checks the source package's own latest-version health (deprecation, latest-version OSV verdict, popularity/maintenance tiers, typosquat flag), then combines maintainer-provided deprecation hints with deterministic npm search-based category matching. It ranks candidates using category overlap plus search_packages-style popularity/maintenance signals, filters out typosquats and weak/stale contenders, and returns a short list with plain-language whySuggested notes. A candidate is also never suggested if it's deprecated, has a confirmed HIGH/CRITICAL OSV vulnerability, or its own OSV check itself failed (network/timeout/upstream outage) — an unverifiable candidate is excluded the same as a confirmed-bad one, not defaulted to 'looks fine', since this tool's entire purpose is not recommending something dangerous. Best for turning a 'don't use this package' warning into an actionable replacement shortlist. If the OSV.dev vulnerability check fails for the SOURCE package (as opposed to a candidate, which gets excluded per above), source.isLatestVersionVulnerable comes back `false` only because the field has to be a boolean — source.vulnerabilityCheckFailed:true is the real signal there, and means that safe/not-safe answer is unknown, not confirmed clean.

  Parameters:

  • name (required) — string — Exact npm package name, e.g. "request" or "node-sass"
  • limit — integer — Max suggestions to return (default 5, max 10)
  • reason — string — Optional reason to bias filtering/ranking

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• compare_packages read-only

  Compare 2-5 candidate packages for the same job (e.g. "axios vs got vs node-fetch") side by side and get a deterministic pick. More than 5 names is rejected, never truncated; duplicate names are rejected. Use search_packages first if you have no shortlist. Per candidate: downloads and trend, popularity/maintenance tiers, GitHub stars, TypeScript support, license, deprecation, latest-version vulnerabilities, a tarball-free installScriptRisk (scores preinstall/install/postinstall; a prepare-only package scores 0 since prepare never runs on install — use analyze_install_script for the deep scan), and installSize (own size plus a transitive rollup up to depth 2 / 60 nodes; `truncated`/`sizeUnknownCount` mark a partial sum). `differentiators` names who stands out on each dimension. `recommendation.pick` comes from a weighted score (popularity, maintenance, deprecation, vulnerabilities, typosquat flag, install-script risk, TypeScript, stars; size is reported, not scored) — never a deprecated or typosquat-flagged candidate — with a `rationale` and a `confidence` from how close the top two scored. Before trusting the result: `vulnerabilityCheckFailed: true` means the safe/not-safe answer is unknown, not clean; a name that cannot be resolved stays in `candidates` with `found: false` and `resolutionError`.

  Parameters:

  • packages (required) — array — 2-5 exact npm package names to compare, e.g. ["axios", "got", "node-fetch"]. More than 5 is rejected with an error, not truncated.

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• audit_github_repository read-only

  Audit a GitHub repository's npm dependencies from its URL — no pasted files needed. Fetches package.json plus the first lockfile found (pnpm-lock.yaml, then package-lock.json, then yarn.lock) from the default branch (or `ref`), and detects monorepos (package.json workspaces, pnpm-workspace.yaml), merging member dependencies (up to 50 members). What it checks: - Every lockfile entry (up to 3,000; the repo's own workspace/link entries skipped) against OSV.dev, so `vulnerablePackageCount` covers the whole dependency set. - Up to 100 packages, vulnerable ones first, also get a license verdict (same default policy as check_license_compliance, or pass `policy`) and an install-script signal; up to 10 with lifecycle scripts get the deep tarball scan (`installScriptScanScope`). - Up to 5 high-risk packages (critical/high vulnerability, possible typosquat, deprecated) get the maintainer-change and provenance checks; others are named in `ownershipCheckNote`. Read `coverage` and the summary before calling a repo clean: a summary starting `PARTIAL AUDIT` (`coverage.complete: false`) means not every package got every check. `findings` has full detail only for packages with something to report; the other detailed packages are listed compactly in `cleanFindings`. Vulnerable packages past the 100-package detail cap are in `overflowVulnerablePackages`. peerDependencies are skipped unless `includePeerDependencies: true`. This is the most expensive tool here — do not call it in a loop across many repos.

  Parameters:

  • url (required) — string — GitHub repository URL, e.g. "https://github.com/owner/repo".
  • ref — string — Branch, tag, or commit SHA to audit. Omit to use the repository's default branch.
  • policy — object — License allow/deny policy, same shape as check_license_compliance. Omit for the default policy (only copyleft/network-copyleft/proprietary are violations).
  • includeDevDependencies — boolean — Include package.json devDependencies in the audit. Default false. Ignored when a lockfile is used instead (its own format decides direct-dependency scope), and yarn.lock can never distinguish dev from production dependencies regardless of this flag.
  • includePeerDependencies — boolean — Include package.json peerDependencies (root and, for a monorepo, each workspace member) in the audit. Default false — a peer is often intentionally left unresolved by the consumer. See warnings for which peers were excluded.

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• get_remediation_playbook read-only

  Maps a finding's `rule` value from analyze_install_script, check_maintainer_changes, or check_package_provenance to the matching human-authored incident-response playbook (the same content published at /docs/playbooks) and returns its concrete, ordered steps, severity tier, real-incident references, and prevention tips — not just a link. Pass the exact `rule` string(s) a prior finding already returned (batch up to 10 in one call to cover a whole findings array; duplicates resolving to the same playbook are deduplicated) or an `id` to look up a specific playbook by slug directly. Each matched rule also gets its own short situationNote explaining specifically what that rule caught — so a batch of several different rules landing on the same playbook does not read as identical, repeated boilerplate. An unrecognized rule or id is not an error — it comes back with matched:false and a note, since a low-severity or baseline-only finding (e.g. analyze_install_script's lifecycle-present) legitimately has no dedicated playbook.

  Parameters:

  • id — string — A playbook slug to look up directly, e.g. "postinstall-binary" — see /docs/playbooks
  • rules — array — 1-10 exact `rule` values copied from findings already returned by analyze_install_script/check_maintainer_changes/check_package_provenance

  Hints: read-only yes · destructive no · idempotent not declared · open-world no

• generate_sbom read-only

  Given the same inputs batch_query_vulnerabilities accepts — either a flat {packages:[...]} list, or raw package.json / lockfile / CycloneDX JSON / SPDX JSON content via `content` — emits a spec-valid CycloneDX 1.6 or SPDX 2.3 JSON document (pick with `format`, default 'cyclonedx') with npmscan's own OSV.dev vulnerability findings and registry license data embedded in each spec's native fields: CycloneDX gets a top-level `vulnerabilities[]` array (VEX `analysis.state: 'in_triage'` — an unreviewed automated finding, not a claim of exploitability) and per-component `licenses[]`; SPDX (which has no vulnerabilities array in 2.3) gets one `externalRefs` SECURITY/advisory entry per finding and `licenseDeclared`/`licenseConcluded`. Only a flat package inventory is known here, so the CycloneDX `dependencies[]` transitive graph and any SPDX package hierarchy are intentionally omitted rather than fabricated. Set `includeVulnerabilities`/`includeLicenses` to false to skip either enrichment pass (faster, no registry/OSV calls for that pass); pass `policy` (same shape as check_license_compliance) to also get per-package compliance context; `componentName`/`componentVersion` name the SBOM's own root component/document if known. When `content` is a package.json, `peerDependencies` are excluded by default (a peer is often intentionally left unresolved by the consumer) — pass `includePeerDependencies: true` to include them as SBOM components too, since an SBOM meant to be complete shouldn't silently omit a whole dependency category.

  Parameters:

  • format — string — SBOM format to emit. Default 'cyclonedx'.
  • policy — object — License allow/deny policy, same shape as check_license_compliance. Omit for the default policy.
  • content — string — Raw dependency inventory content: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, CycloneDX JSON, or SPDX JSON. Use this OR `packages`, not both.
  • packages — array — Explicit package list (1-1000 items, capped to 100 when includeLicenses is on). Use this OR `content`, not both.
  • componentName — string — Name of the SBOM's own root component/document, if known.
  • includeLicenses — boolean — Resolve registry license data and embed it natively. Default true.
  • componentVersion — string
  • includeDevDependencies — boolean — Ignored when using `packages`; only applies when `content` is a manifest/lockfile format that distinguishes dev dependencies.
  • includeVulnerabilities — boolean — Query OSV.dev and embed findings natively. Default true.
  • includePeerDependencies — boolean — Ignored when using `packages`; only applies when `content` is a package.json. peerDependencies are excluded by default — set this to also include them as SBOM components.

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

• enrich_npm_audit read-only

  Given the raw output of `npm audit --json` (npm 7+'s `{vulnerabilities: {...}}` format, or legacy npm 6's `{advisories: {...}}`), parses it directly — no need to re-paste package.json/lockfile content — and runs it through the same remove-now/patch-now/patch-soon/scheduled/monitor ranking prioritize_remediation exposes for hand-built finding lists (an advisory that is malware — a MAL-* id, or a GHSA whose OSV record carries CWE-506 / a MAL-* alias — is auto-detected and forces remove-now). npm audit's JSON almost never includes a CVE id (only a GHSA advisory URL), so this resolves each GHSA to its CVE alias via OSV.dev when one exists (ghsaResolvedToCveCount reports how many) before doing the same CISA KEV + FIRST.org EPSS + severity scoring — skipping this step would silently degrade most findings to severity-only ranking despite prioritize_remediation being built around CVE-keyed KEV/EPSS data. Also carries through npm-audit-specific context prioritize_remediation itself has no field for: isDirect (direct vs. transitive dependency) and fixAvailable/fixTarget (npm's own computed fix — note fixTarget can name a different package than the vulnerable one, e.g. bumping a parent to pull in a patched transitive dependency). A package with more than one distinct advisory in the source report only has its first advisory used for ranking; a warning names the package so query_vulnerabilities can be called on it directly for the rest. `yarn audit --json` and `pnpm audit --json` use different report shapes and are not supported — use batch_query_vulnerabilities with the project's manifest/lockfile for those instead.

  Parameters:

  • content (required) — string — Raw stdout of `npm audit --json` — either npm 7+ format ({"auditReportVersion": 2, "vulnerabilities": {...}}) or legacy npm 6 format ({"advisories": {...}}).

  Hints: read-only yes · destructive no · idempotent not declared · open-world yes

Publisher website Repository

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.