NPMScan

Reviewed 1h ago.

• tools: 23 tools scanned
• metadata: scanned

• mediumReviewRemote tools take credentials as input

  Whatever an agent passes to a remote tool leaves the machine. Never send connection strings, tokens or passwords to a third-party MCP server unless it is the service those credentials belong to.

  check_maintainer_blast_radius

Tools (23)

• 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_

• 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 mean

• 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.

• 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 a

• 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

• batch_query_vulnerabilities

  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/works

• 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

• 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-CV

• 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 fir

• analyze_transitive_dependencies

  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).

• 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 a

• check_maintainer_changes

  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

• 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 userna

• 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 pol

• diff_dependencies

  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

• prioritize_remediation

  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

• simulate_dependency_upgrade

  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 n

• 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 u

• compare_packages

  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 deprecat

• audit_github_repository

  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 befo

• 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) legitim

• 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 (f

• 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 (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