Official MCP RegistryListed
NPMScan
Detect malicious or vulnerable npm packages: registry search, OSV.dev and GitHub advisory lookups
First seen 2 Oct 2026. Evidence as of 3 Oct 2026.
23
Tools
From an anonymous probe
1
Source listings
Each with its own history
4
Recorded changes
Since first seen
Tools
| Tool | Description | Behaviour |
|---|---|---|
| analyze_install_script | 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. | Read-only |
| analyze_transitive_dependencies | Recursively resolves one or more direct/root packages' dependency graphs — e.g. the "dependencies" section of a package.json — up to maxDepth levels deep (default 2, max 3) and batch-checks every resolved package@version against OSV.dev, so vulnerabilities buried several levels down (which would never show up from checking direct dependencies alone) still surface. `summary` is a one-sentence, deterministic recap (packages scanned, unresolved count, vulnerable count and which roots pulled them in) — read it first. The `vulnerablePaths` field directly answers "which of my dependencies pulled this in" by naming the root package(s) responsible for each vulnerable transitive package; `nodes` has the full resolved graph (depth, parents, resolutionError) for deeper inspection. An npm alias (e.g. `"totally-safe": "npm:[email protected]"`) is followed to its real target — `actualName` names the real package that vulnerability data attaches to (`name` stays the declared/alias key) — this is NOT silently skipped, since doing so would mean a vulnerable package hides behind whatever name a project calls it. A node with `resolutionError` set (unsatisfiable range, 404, or a git/file/workspace/URL specifier — those still aren't followed, only npm: aliases are) has `isVulnerable: null`, not `false` — it was never actually scanned, so "not vulnerable" would be a fabricated clean bill of health; only trust `isVulnerable: true`/`false` once a real version was resolved and checked. Scope/limits worth knowing before trusting a "clean" result: only the "dependencies" field is followed (not devDependencies/peerDependencies/optionalDependencies); each range is resolved independently per branch via semver max-satisfying against published versions — this does NOT emulate npm/yarn's actual node_modules hoisting/dedup, so read results as "which vulnerable versions are reachable in the graph," not the exact installed layout; and the whole traversal is capped at a total node budget — check `truncated`/`truncationNote` rather than assuming a large graph was scanned exhaustively. Prefer batch_query_vulnerabilities instead when you only need to check exact packages you already have a flat list for (faster, no graph walk). | Read-only |
| audit_github_repository | Given a GitHub repository URL, fetches its package.json (and, if present, a pnpm-lock.yaml/package-lock.json/yarn.lock — first one found wins, in that priority order) straight from the repo's default branch and runs the same vulnerability, license-compliance, install-script, and ownership-risk pipelines batch_query_vulnerabilities/check_license_compliance/analyze_install_script/check_maintainer_changes/check_package_provenance expose individually, in one call — no copy-pasting file contents required. A monorepo (package.json#workspaces, Yarn's {packages:[...]} form, or pnpm-workspace.yaml) is detected automatically: pnpm-lock.yaml and yarn.lock already record every workspace member's dependencies directly, and for package.json-only or package-lock.json repos this additionally lists the repo's file tree, resolves the declared glob patterns to member directories, and merges each member's dependencies into the audit (capped at 50 member packages) — see isMonorepo/workspacePatterns/workspacePackageCount/workspaceNote in the result. Every direct dependency (up to 100 per call, across the root and any merged workspace members) gets: an OSV.dev vulnerability check, a license-compliance verdict against the given policy (same default as check_license_compliance: only copyleft/network-copyleft/proprietary are violations unless you pass one), and a tarball-free install-script risk signal (installScriptScanScope: 'lifecycle-scripts-only'). Up to 10 of the packages that actually declare a lifecycle script — prioritized by already-vulnerable, then possible-typosquat, then whatever's left — additionally get the full tarball-fetching deep scan analyze_install_script itself runs (installScriptScanScope: 'deep-tarball-scan', with a populated installScriptFindings array); any remaining flagged packages past that cap keep the lighter signal only, noted in deepScanNote. Any package that comes back vulnerable at high/critical severity, a possible typosquat, or deprecated (ownershipRiskEligible) additionally gets check_maintainer_changes and check_package_provenance run against it — up to 5 such packages per call (ownershipRiskChecked), prioritized the same way as the deep install-script scan, populating maintainerRiskTier/maintainerFindings and provenanceRiskTier/provenanceFindings; remaining eligible packages past that cap are named in ownershipCheckNote. This is the most expensive tool in the suite (a repo lookup, a handful of file fetches, up to 100 registry doc fetches, one OSV batch call, up to 10 tarball fetches, up to 5 packages each getting a maintainer-history check plus a provenance check — the latter alone can fan out to ~8 more registry fetches on its own — and, for a monorepo needing enumeration, one file-tree listing plus up to 50 more manifest fetches) — don't call it in a loop across many repos. `peerDependencies` (root and, for a monorepo, each workspace member's own manifest) are excluded from the audit by default, same as batch_query_vulnerabilities — pass `includePeerDependencies: true` to also check them; see `warnings` for which peers were excluded. | Read-only |
| batch_query_vulnerabilities | Query OSV.dev for known vulnerabilities across a whole npm dependency inventory at once: either pass a flat {packages:[...]} list, or paste raw package.json / lockfile / CycloneDX JSON / SPDX JSON content via `content`. The tool normalizes npm dependencies first, then chunk-queries OSV behind the scenes so large SBOMs don't stop at the upstream 100-package batch limit. Each finding includes severity, a summary, CVE aliases, and the fixed version — not just a bare advisory ID — so a dependency audit answer doesn't need a follow-up call per flagged package. For an explicit `packages` list or raw `package.json` content — names that were never actually resolved against a registry, unlike a real lockfile/SBOM — package names are also cross-checked against the npm registry (capped at 200 unique names): a name that doesn't exist there would otherwise show a silent, indistinguishable `vulnerabilityCount: 0` — see `unresolvedPackages`/`existenceCheckNote` and do not read those entries as a clean bill of health. The same facts are attached to each result as `registryStatus` ("found" | "package-not-found" | "version-not-found" | "unchecked") — independent of `scanStatus`, which stays "scanned" for these because OSV IS still queried (a package unpublished for malware keeps its OSV/MAL- record, so treating registry absence as "not scanned" would hide exactly that case). A `packages[].version` that doesn't currently appear on the registry (a typo'd/fabricated version, OR a real version that was published and later removed, e.g. unpublished for containing malware) is cross-checked the same way — see `nonexistentVersions`; don't assume it never existed, and don't assume `vulnerabilityCount:0` for it means clean, since OSV can still carry findings for a version the registry no longer lists. A `packages[]` entry given with NO version at all (e.g. `{name:"react"}`) is intentionally queried unversioned against OSV — this returns advisories affecting ANY historical published version of that package, not just the latest or whatever a project actually has installed; see the corresponding `warnings` entry naming which packages this applied to, and don't report "package X is vulnerable" from an unversioned result without separately confirming against the specific version in use (get_package/get_package_version). Each result also carries `signals` (deprecated, hasInstallScripts for the specific requested/resolved version, popularityTier/maintenanceTier, and possibleTyposquatOf — same deterministic rule-based labels as get_package/search_packages, capped at the same 200 unique names): a clean `vulnerabilityCount:0` does NOT mean safe to use if `signals` flags a likely typosquat, an abandoned/stale package, or a deprecation notice — surface those explicitly rather than reporting only the vulnerability count. `signals` is `null` for a `scanStatus: "not-scanned"` entry, deliberately — a git/file/workspace/URL dependency can be declared under a name that collides with a real npm package (e.g. a git dependency literally named "lodash"), and that unrelated public package's popularity/maintenance signals must not be attached to it just because the name happens to resolve on the registry. A lockfile-resolved result also carries `source` (resolvedUrl/integrity straight from that lockfile entry, plus `nonRegistryHost`): `nonRegistryHost: true` means the tarball URL points somewhere other than the expected npm/yarn registry host — e.g. a compromised mirror or a hand-edited lockfile — which a name+version match against OSV cannot detect on its own, since a malicious tarball can share the same name/version as the real package and carry zero OSV findings. `source` is `null` when the input format doesn't record this (package.json content, an explicit `packages` entry, or pnpm-lock, which never records a resolvedUrl). `nonRegistryHost: false` alone is NOT proof the tarball is correct — `source.identityMismatch: true` catches a SAME-HOST swap that host-checking cannot: a lockfile entry can declare e.g. "[email protected]" while resolvedUrl actually points at the real registry.npmjs.org's own tarball for a completely different package/version, and `vulnerabilityCount` above was still computed for the DECLARED name/version, not whatever that resolved tarball actually is — treat `identityMismatch: true` as a lockfile-tamper finding, not a cosmetic mismatch, and see `source.resolvedName`/`resolvedVersion` for what the tarball actually names. `vulnerabilityCount`/`advisoryCount` are raw OSV/GHSA advisory counts and can over-count: OSV sometimes publishes more than one advisory record for the same underlying CVE — use `uniqueVulnerabilityCount` (deduped by shared CVE alias) when reporting 'how many distinct issues' rather than a raw advisory tally. When `content` is itself a package.json (not a lockfile/SBOM), `projectLifecycleScripts` surfaces that SCANNED PROJECT's own preinstall/install/postinstall/prepare scripts, if any — these run arbitrary code the moment someone runs `npm install` on the project itself, separate from anything a dependency does, and 'scan my package.json' should not silently skip the one script that actually executes for the project being scanned. An npm alias (e.g. `"totally-safe": "npm:[email protected]"`) is followed to its real target in every input format — `results[i].package.actualName` names the real package that vulnerability/signal data attaches to (`.name` stays the declared/alias key); this is NOT silently skipped, since doing so would let a vulnerable package hide behind whatever name a project calls it. A dependency whose spec points somewhere other than the registry (git/file/workspace/URL) or that never resolved to a version is excluded from vulnerability querying entirely rather than queried by name alone — `vulnerabilityCount: 0` for one of these would otherwise misleadingly attach an unrelated public npm package's entire vulnerability history to it. When `content` is a package.json, `peerDependencies` are excluded from scanning by default (a peer is often intentionally left unresolved by the consumer) — see `ignoredPeerDependencyNames`, and pass `includePeerDependencies: true` to also check them, since a vulnerable/malicious peerDependency is otherwise invisible to this scan. `results[i].package.declaredSpec` is set whenever `.version` was RESOLVED from a package.json semver range/tag (e.g. `"^18.2.0"` -> `"18.2.0"`) rather than being an already-exact pin or a lockfile-derived version — a range can silently pick up a new, possibly-compromised release the next time this project is installed, while an exact pin can't, so don't treat a range-resolved `isVulnerable:false` as equally durable to a pinned one just because they look identical today. | Read-only |
| check_license_compliance | 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. | Read-only |
| check_maintainer_blast_radius | 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. | Read-only |
| check_maintainer_changes | Reconstructs a package's maintainer-change history straight from the npm packument — every published version carries the maintainers-list SNAPSHOT as it stood at that publish plus who actually ran `npm publish` (`_npmUser`), so diffing consecutive snapshots in publish-time order recovers exactly who was added or removed and when, with no extra API calls. Flags: (1) a maintainer added recently who then published a release shortly afterward on a package with real prior history — the account-takeover/hostile-handoff shape behind incidents like ua-parser-js, event-stream, and the 2025 chalk/debug ('qix') compromise; (2) a full, sudden replacement of the entire maintainer list; (3) a long-standing maintainer quietly dropped from the list; (4) a maintainer-list change that happened on npm's site AFTER the latest release — not yet tied to any published version, which is the more urgent case since it means access changed hands but nothing has shipped with it yet. Also cross-checks the declared GitHub repository: whether it still resolves to the same owner/name (a transfer/rename), whether it's reachable at all, and whether the latest npm release landed long after any real push activity there — repository.ownerLogin/ownerAvatarUrl name and show the CURRENT owning account (the new one after a transfer, not the one originally declared in package.json), with ownerAvatarUrl a proxied GitHub avatar image, both null whenever the repo check itself didn't reach GitHub. Use get_package/check_package_provenance first for the package's general health and publish-integrity signals; use this specifically for the 'who controls this package, and did that change recently' question. If this flags a newly added or fully turned-over maintainer, follow up with check_maintainer_blast_radius on that maintainer's username — it lists every other package the same account currently touches and flags a tight publish-time cluster across them, the 'did this compromise hit just one package or a dozen' question this tool can't answer on its own. | Read-only |
| check_package_provenance | 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. | Read-only |
| compare_packages | Given 2-5 candidate packages for the same job (e.g. "axios vs got vs node-fetch"), fetches the same registry/popularity/maintenance/vulnerability enrichment get_package computes for each one in parallel and returns a structured side-by-side plus a deterministic, reasoned pick. Each candidate gets downloads + trend, popularityTier/maintenanceTier, GitHub stars, TypeScript support, license, deprecated status, latest-version vulnerability status, a lightweight installScriptRisk signal (scans lifecycle script command strings for known red flags — does NOT fetch the tarball; call analyze_install_script on a specific candidate for that deeper scan), and installSize (the candidate's own dist.unpackedSize plus a transitive rollup — summed dist.unpackedSize across its resolved dependency tree, walked up to depth 2 / 60 nodes per candidate; `installSize.transitive.truncated`/`sizeUnknownCount` flag when that sum is partial rather than pretending it's exact — call analyze_transitive_dependencies on a specific candidate for the full graph). `differentiators` names which candidates stand out on each dimension (most downloads, only ones with TS types, which are deprecated/vulnerable/flagged as a typosquat/install-script risk, smallest/largest install size). `recommendation.pick` is chosen deterministically from a weighted score (popularity, maintenance, deprecation, vulnerabilities, typosquat flag, install-script risk, TS support, GitHub stars — install size is reported but not scored) — never a deprecated or typosquat-flagged candidate — with `rationale` explaining why and `confidence` reflecting how close the top two scored. If a candidate's OSV.dev vulnerability check itself failed (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 that candidate's safe/not-safe answer is unknown, not confirmed clean. A name that can't be resolved (typo, unpublished, malformed) still appears in `candidates` with `found:false` and `resolutionError` set rather than failing the whole call; duplicate names in the input are rejected. More than 5 names is rejected with an error, never truncated: to compare more, split them into separate calls (or shortlist first) rather than dropping names to fit. | Read-only |
| diff_dependencies | Compares two raw snapshots of a package.json, package-lock.json (npm v1-v3), yarn.lock (classic v1 or Berry), or pnpm-lock.yaml — e.g. before/after a PR — and reports which packages were added, removed, or version-bumped. An npm alias (e.g. `"totally-safe": "npm:[email protected]"`) is followed to its real target in every format — `actualName` names the real package that vulnerability/install-script data attaches to (`name` stays the declared/alias key); this is NOT silently skipped, since doing so would let a vulnerable package hide behind whatever name a project calls it. For every added or bumped package (up to 100 per call), also checks whether its resolved version carries a preinstall/install/postinstall/prepare lifecycle script that the before-version did NOT have (`installScriptIntroduced`, a headline signal — a routine-looking patch bump quietly adding a postinstall is exactly the shape of a compromised-maintainer supply-chain attack) and batch-checks it against OSV.dev, reporting `vulnerabilityDelta` (introduced/fixed/still-vulnerable/still-clean) rather than just a bare isVulnerable flag. `installScriptIntroduced` is a boolean across all four lifecycle keys, so it treats a bare `"prepare": "husky"` bump the same as a newly-added network-capable `postinstall` — read `installScriptKeysIntroduced` (null when only npm-lock's boolean hint was available, not the real scripts object; otherwise the actual key(s) added) to tell those apart before treating a flag as high-severity. `sourceIntegrityChanged` catches a DIFFERENT attack shape than a version bump: a lockfile entry whose resolved tarball URL or integrity hash changed while the version string stayed IDENTICAL — e.g. a compromised registry mirror or a hand-edited lockfile pointing a legitimate-looking "[email protected]" at a different, unverified artifact — which a version-only diff would report as "no change" (`resolvedUrl`/`integrity` are null when a format doesn't record either, package.json has neither). Scope notes: package.json is diffed as its own declared dependency list only (a manifest has no transitive data at all, and this includes `peerDependencies`, unlike batch_query_vulnerabilities/generate_sbom which exclude them by default — a diff should catch a peerDependency change just like any other); every lockfile format (package-lock.json, pnpm-lock.yaml, yarn.lock) reports its FULL resolved graph — direct and transitive alike — so a transitive-only change (e.g. a nested `qs` bumped while the direct `express` version is untouched) is caught, not just direct dependency changes; check `comparisonNote` when the two snapshots are different formats/scopes. The install-script check is presence-only (read from the registry packument or lockfile metadata, not a tarball content scan) — use analyze_install_script for a deep-dive on anything flagged here. `projectLifecycleChanges` diffs the SCANNED PROJECT's own root preinstall/install/postinstall/prepare scripts (package.json only — null when neither snapshot is one) — independent of the dependency list above, since a PR that only adds a root postinstall (`"postinstall": "curl ... | sh"`) changes nothing about added/removed/changed and would otherwise be invisible to this tool entirely; `introduced`/`changed` on a preinstall/install/postinstall key is counted in `flaggedCount`. `overridesChanges` similarly diffs package.json's `overrides` (npm), `resolutions` (yarn), or `pnpm.overrides` — these force a specific version onto a transitive dependency (often to pin past a known vulnerability), so a PR that quietly removes, downgrades, or introduces one is exactly the kind of change a dependency diff should catch, and previously nothing here read this field at all; ANY change here (introduced/removed/changed) is counted in `flaggedCount`, since an override can be a security control being weakened just as easily as an attack forcing a compromised version onto an otherwise-untouched dependency. Ideal for a CI gate reviewing a dependency-changing PR. | Read-only |
| enrich_npm_audit | 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 (a MAL-* advisoryId in the audit report is auto-detected as malware 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. | Read-only |
| generate_sbom | 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. | Read-only |
| get_cve | 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. | Read-only |
| get_latest_advisories | 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. | Read-only |
| get_maintainer_profile | 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. | Read-only |
| get_package | 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. | Read-only |
| get_package_version | 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. | Read-only |
| get_remediation_playbook | 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. | Read-only |
| prioritize_remediation | Given a batch of vulnerability findings already flagged elsewhere (e.g. from batch_query_vulnerabilities, analyze_transitive_dependencies, or query_vulnerabilities across a whole package.json/lockfile audit), ranks them by what to actually fix first. Combines CISA KEV status (confirmed active exploitation in the wild — an automatic top-priority override), FIRST.org EPSS (probability of exploitation in the next 30 days — the primary ranking signal, since it measures likelihood rather than just impact), and severity (a secondary/fallback signal, most useful for a GHSA finding with no CVE alias) into one composite score and a remove-now/patch-now/patch-soon/scheduled/monitor tier per finding. A finding with `findingType: "malware"` (or a MAL-* advisoryId, auto-detected even when findingType is omitted) always lands in `remove-now` — the tier above patch-now — regardless of score: a confirmed-malicious package needs removal/replacement, not an "urgent patch" (there often isn't a fixed version to patch TO), and EPSS/severity don't meaningfully apply to "how malicious" the way they do to a genuine vulnerability. When EPSS data isn't available at all (no CVE id, or a real CVE that just isn't in FIRST.org's database) severity becomes the sole usable signal and is scored on its own scale instead of being diluted to a ~10% sliver of the composite — a bare CRITICAL/HIGH GHSA finding with no CVE alias lands in patch-soon/scheduled, not monitor, the way it would if severity kept its normal secondary weight with nothing else to combine it with. This does NOT re-query OSV/NVD itself — pass in the severity/CVE id findings other tools already returned; it only adds KEV/EPSS enrichment (the same data get_cve returns per-CVE) and ranks the batch. A CVE id shared by multiple findings in the same call is only looked up once. The tier is a fix-ORDER ranking across a backlog, not a severity verdict or a merge/admission gate: a CRITICAL CVE with low EPSS and no KEV listing can legitimately land in `monitor` (minimist's CVE-2021-44906 has ranked there). Do not report a `monitor`/`scheduled` finding as "low severity", and when deciding whether a change that INTRODUCES a vulnerability is acceptable, judge it on severity, not on this tier. | Read-only |
| query_vulnerabilities | 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. | Read-only |
| search_packages | 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. | Read-only |
| simulate_dependency_upgrade | Given a package and a current/target version, tells you whether that specific upgrade is a safe patch/minor bump or a likely-breaking major bump, before you actually run npm install. Natural follow-up to prioritize_remediation: pass its `packageName` + `currentVersion` + `fixedVersion` straight in to check whether the suggested fix is a drop-in patch or something that needs a review pass. Classifies the jump by semver (major/minor/patch/prerelease), treats a minor bump between two pre-1.0 (0.x) versions as breaking-risk per semver's own "the API isn't stable yet" convention, and flags skipping over multiple major versions in one jump (e.g. 2.x -> 5.x) as needing a per-major changelog review rather than just a diff against the final target. Beyond semver, it also checks the registry for real signals the version number alone won't tell you: whether the target version is marked deprecated, whether it introduces a preinstall/install/postinstall/prepare lifecycle script the current version didn't have, whether it tightens its engines.node requirement, and whether it is itself a prerelease. Finally it batch-checks both versions against OSV.dev and reports vulnerabilityDelta (introduced/fixed/still-vulnerable/still-clean) — catching the case where a suggested "fix" version doesn't actually clear every open CVE. Combines all of this into one riskTier (safe/low-risk/review-recommended/breaking-change-likely/unknown) with a reasons list explaining exactly which signals drove it. This does NOT read the package's changelog/release notes or scan the target tarball's source diff for actual breaking API usage — it's a fast, deterministic pre-check, not a substitute for reading the release notes on a flagged major bump. For simulating more than one upgrade at once — e.g. every "patch-now" finding prioritize_remediation just ranked — pass `packages: [{packageName, currentVersion, targetVersion?}, ...]` (1-100 items) instead of `packageName`/`currentVersion`/`targetVersion`, not both. Registry fetches are deduped/parallelized and all OSV checks for the whole batch run as one call, so this is not the same cost as N single-item calls. A package that can't be resolved at all (typo, unpublished, registry error) shows up as its own `results` entry with `fetchError` set instead of failing the whole batch. | Read-only |
| suggest_alternative | 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. | Read-only |
Change history
- query_vulnerabilities: input schema changed
- get_package_version: input schema changed
- compare_packages: input schema changed
- compare_packages: description changed (+"More than 5 names is rejected with an error, never truncated: to compare more, split them into separate calls (or shortlist first) rather than dropping names to fit.")
| Source | Listing | First seen | Last seen | Versions |
|---|---|---|---|---|
| Official MCP Registry | io.github.salemalem/npmscan | 2 Oct 2026 | 3 Oct 2026 | 1 |