package-trust-check

NPMScan package trust check

Use this skill when the user names one specific package (optionally a version) and asks a trust question about it — "is X safe to use," "was X compromised," "should I be worried about X," "check X's maintainers." This is a deep, single-package investigation: it runs checks dependency-audit deliberately skips for every package in a batch because they're too expensive to run at scale.

If the user instead pastes a package.json/lockfile/dependency list or asks to audit multiple packages, use the dependency-audit skill instead — don't run this skill's checks across a whole inventory. If the question is purely factual with no trust/safety angle ("what does lodash do," "what's the latest version of express"), just answer directly with get_package — don't invoke the full investigation for that. If the user is instead choosing between candidates for something not yet installed ("should we add X," "X vs Y for this job"), that's a forward-looking pick, not a trust investigation — use the new-dependency-evaluation skill.

Connecting the npmscan tools

This skill calls the npmscan MCP server's tools (listed under "Tools used" below). They only read public package data: no API key or account, nothing is installed or changed on the user's machine, and the only server contacted is https://npmscan.com/api/mcp.

• Claude Code, Codex, Gemini CLI, Kimi, Grok: the npmscan plugin connects the server for you.
• OpenClaw: openclaw mcp add npmscan --url https://npmscan.com/api/mcp --transport streamable-http, then openclaw mcp doctor npmscan --probe to check it.
• Any other MCP client: add a remote (streamable HTTP) server with that URL.

Some clients prefix tool names with the server name (for example npmscan__get_package). If the tools aren't available at all, tell the user how to connect them for their client instead of answering from memory.

Steps

1. Baseline with get_package (or get_package_version if the user gave an exact version). Pull deprecated, maintenanceSummary, possibleTyposquatOf, isLatestVersionVulnerable/highestSeverity, downloadTrend, and days-since-last-publish. This alone answers a good chunk of "should I trust this" and grounds the deeper checks that follow — don't skip straight to the maintainer/provenance tools without it. If get_package_version comes back with versionExists: false, that version is no longer on npm but OSV still has advisories for it — usually a release npm pulled for being malicious (ua-parser-js 0.7.29, debug 4.4.2). Report its vulnerabilities as real; it is not a "not found."
2. Check for malware. Every vulnerability finding carries isMalware — true for a confirmed-malicious package (an OSV MAL-* record, or a GitHub advisory with CWE-506 such as ua-parser-js's GHSA-pjwm), not an ordinary bug. Read it on the step-1 findings for this version, and call query_vulnerabilities({ name }) with no version to see whether ANY release of this package was ever malicious — a past compromise is worth naming even when the current version is clean. Any isMalware: true finding on the version in question is the most severe possible outcome: report it plainly as known malware, never as "worth verifying." get_latest_advisories({ type: "malware", affects: name }) (GitHub's malware feed) and ({ type: "osv", affects: name }) (OpenSSF's) only cover recently published advisories — useful for a brand-new incident OSV hasn't indexed yet, but an empty result says nothing about history.
3. Call check_maintainer_changes({ name }). It reconstructs maintainer add/remove history from the npm packument and flags:
   • a maintainer added recently who then published shortly after (the account-takeover pattern behind the Sept 2025 chalk/debug "qix" compromise and ua-parser-js),
   • a full sudden replacement of the maintainer list,
   • a long-standing maintainer quietly dropped,
   • a maintainer-list change on npm not yet tied to any release — flag this as the more urgent case, since access changed hands but nothing has shipped with it yet, so there's no version to warn the user off of. Also reports GitHub repository transfer/archival — a transfer isn't automatically hostile (e.g. jade → pug was a documented rename), say so rather than treating every transfer as a red flag. If it flags a newly added or fully turned-over maintainer, immediately follow up with check_maintainer_blast_radius({ maintainerUsername }) on that account — it lists every other package the same account currently touches and flags a tight cluster of packages published within a short window of each other, the compromised-account shape behind incidents like the 2025 chalk/debug ("qix") compromise and the 2026 keyv/cacheable "Shai-Hulud" worm. Don't stop at the one named package if the maintainer signal is already concerning — a tight cluster across several packages is a materially worse finding than a single-package maintainer change, and this is a single-package investigation's best chance to catch that before the user asks about the next affected package separately. A large totalPackagesFound alone is not a red flag; only a tight cluster is. A cluster note starting "Discounted:" means it's at least 30 days old and OSV.dev lists no malware for its versions — a past burst that stayed clean, not a current threat; one naming a malware advisory is the opposite.
4. Call check_package_provenance({ name, version }). Three checks in one call: does the Sigstore build attestation's source repo/commit match package.json's declared repository; is this version missing provenance while its npm-scope or maintainer peers consistently publish with it (a real anomaly, not just "no provenance" — a version published before npm provenance existed, 2023-04-19, skips this comparison, and peers.note says so); and does the tarball's actual install scripts/ dependencies match what's committed at the attested source commit — a script or dependency on npm that was never committed in source is the stolen-npm-token publish pattern. This is structural verification, not a cryptographic re-check of the Sigstore bundle — say so if the user asks how deep it goes. For a version npm no longer lists, this tool returns a not-found error that names any OSV advisories — use those, don't stop at the 404.
5. If get_package/get_package_version in step 1 showed hasLifecycleScripts/a preinstall/postinstall/prepare entry, follow up with analyze_install_script({ name, version }). It fetches the published tarball and statically scans the script — and the files it references — against npmscan's red-flags rubric (child_process, network calls, .ssh/.aws/.npmrc/*TOKEN/*KEY access, obfuscation, remote binaries off untrusted hosts, exfil endpoints, eval-on-decoded-content), returning a totalScore/riskTier. A nonzero score isn't automatically malicious — a legitimate binary download (e.g. cypress) scores nonzero too — so report the actual findings, not just the score. A prepare-only package scores 0 unless its command does something alarming: npm never runs a dependency's prepare on install.
6. If the combined picture ends up genuinely concerning (a maintainer- takeover pattern, a malware finding, a provenance mismatch, a possibleTyposquatOf hit, or a critical install-script finding), offer — don't force — suggest_alternative({ name, reason }) with reason set to whichever of "vulnerable"/"abandoned"/"typosquat"/"general" best fits, so the user has a next step instead of just a warning.
7. Produce one findings report, most-concerning signal first:
   • State the verdict per check plainly (e.g. "no maintainer-change red flags in the lookback window," not silence-as-clean).
   • Every finding from check_maintainer_changes/check_package_provenance is a hedged signal meant to prompt verification, not proof — say "worth verifying independently," matching the tools' own language, especially for anything below their high/critical tiers.
   • Include the npmscanUrl so the user can read the full write-up.
   • If nothing turned up anything but a low/none riskTier and no maintainer or provenance findings, say so plainly — this skill exists to give confident "looks clean" answers as often as it flags real risk.

Do not

• Do not run this skill's checks across every package in a list — that's dependency-audit's job, and check_maintainer_changes/ check_package_provenance are deliberately reserved there for already-flagged packages only, not a full inventory.

• Do not treat a missing provenance field, a repository transfer, or a single maintainer addition as confirmed compromise on its own — report what the tool actually flagged (or didn't) and let the riskTier/points speak, don't editorialize past it.

• Do not skip get_package and jump straight to the deep checks — the baseline (deprecated, popularity/maintenance tiers, typosquat) is cheap and often already answers the question.

• Do not invent a replacement package name yourself — let suggest_alternative return its own whySuggested/nonPackageAlternatives rather than guessing.

• Do not silently skip analyze_install_script when lifecycle scripts exist just because check_maintainer_changes/check_package_provenance came back clean — a legitimate maintainer can still ship a genuinely risky script, and vice versa; report all applicable signals, not just whichever ran first.

• Do not skip check_maintainer_blast_radius once check_maintainer_changes flags a newly added or fully turned-over maintainer — that combination is exactly when the follow-up matters most, not an optional extra step.

• Do not treat a large totalPackagesFound from check_maintainer_blast_radius as a red flag by itself — many legitimate maintainers publish hundreds of packages over a career. Only a tight-cluster finding (several packages' latest versions landing within a short window of each other) is the actual signal.

• Do not soften an isMalware: true finding into a hedged "worth verifying" the way a check_maintainer_changes/check_package_provenance signal is — it is a confirmed report of malicious code, not a heuristic.

• Do not treat an empty get_latest_advisories malware/osv result as a clearance — those feeds only cover recent advisories. The isMalware flags on the OSV findings are the malware check.

• Do not read a versionExists: false result, or a provenance not-found error that names advisories, as "the version doesn't exist so it's fine" — that is exactly how npm removes malicious releases.

• Do not attempt to install, upgrade, or publish packages yourself; this skill only reads data through NPMScan's read-only MCP tools.

Tools used

get_package, get_package_version, query_vulnerabilities, get_latest_advisories, check_maintainer_changes, check_maintainer_blast_radius, check_package_provenance, analyze_install_script, suggest_alternative — all provided by the npmscan MCP server bundled with this plugin (.mcp.json). See references/test-prompts.md for prompts to manually verify this skill after installing or editing it.