dependency-audit Skill
在安装、升级或发布前,审计项目的 npm 依赖是否存在已知漏洞和危险安装脚本。当用户粘贴或附加 package.json/lockfile、列出依赖,或要求检查/审计/扫描包的安全问题时使用——包括比较两个快照(PR diff)或检查许可证合规。
安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。
技能指令原文(SKILL.md)
NPMScan dependency audit
Use this skill when the user wants a security check across multiple npm
packages at once (a package.json, a lockfile, or a plain list of
name@version pairs) — not for a question about a single package. A plain
factual single-package question ("what does X do") you can answer directly
with get_package or query_vulnerabilities; a single-package
trust question ("is X safe," "was X compromised/hijacked") should use the
package-trust-check skill instead, which runs the deeper
maintainer-history and publish-provenance checks this skill deliberately
reserves for already-flagged packages only. A forward-looking question about
what to add rather than what's already installed ("should we add X," "X
vs Y vs Z for this job," "what should we use to do X") should use the
new-dependency-evaluation skill instead — it orchestrates
compare_packages/suggest_alternative for exactly that decision, which
this skill's per-inventory vulnerability/license flow isn't built for.
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.
Input
Accept dependency name+version pairs from:
- Pasted
package.jsoncontents (usedependencies; only include
devDependencies if the user asks to include dev dependencies — say
explicitly which set you audited).
- Pasted lockfile contents (
package-lock.json,yarn.lock,pnpm-lock.yaml). - Pasted CycloneDX JSON or SPDX JSON SBOM contents.
- A plain list the user typed, e.g. "lodash 4.17.15, express 4.17.1".
- Raw
npm audit --jsonoutput (npm 7+'s{vulnerabilities: {...}}format,
or legacy npm 6's {advisories: {...}}) — do NOT re-parse this by hand
into a packages list for batch_query_vulnerabilities. Call
enrich_npm_audit({ content }) directly instead: it parses the report
itself, resolves each finding's GHSA advisory to a CVE alias via OSV
(npm audit JSON almost never carries a CVE id on its own), and returns the
same remove-now/patch-now/patch-soon/scheduled/monitor ranking as step 9
below in one call — this replaces steps 1, 3, and 9 for the findings it covers, though
steps 4-8 (install scripts, maintainer/provenance checks, license
compliance) still need the package names it flagged run through those
tools separately, since npm audit's own JSON has no license/maintainer/
install-script data. yarn audit --json/pnpm audit --json are not
supported — treat those like a lockfile paste (step 1) instead.
- A GitHub repository URL (e.g. "audit https://github.com/owner/repo") — do
NOT ask the user to paste package.json/lockfile contents in this case.
Call audit_github_repository({ url }) directly instead: it fetches the
manifest/lockfile from the repo's default branch itself and runs steps 3,
4, 6, and 8 below (vulnerability, install-script signal, license
compliance, and — for whatever it flagged as critical/high severity, a
possible typosquat, or deprecated — the check_maintainer_changes/
check_package_provenance ownership checks too, up to 5 packages per call
— one slot per package, so several versions of one package share its
result — prioritized the same way step 6 already ranks them) in one call, replacing
that part of the flow below. Read coverage and the summary first: every
lockfile entry is checked for vulnerabilities, but only 100 packages
(vulnerable ones first) get the license/install-script detail, and a
summary starting PARTIAL AUDIT means not everything was covered — say
so; never call a repo "clean" when coverage.complete is false.
vulnerablePackageCount covers the whole lockfile; vulnerable packages
past the 100-package detail cap are in overflowVulnerablePackages.
Check ownershipCheckNote for any flagged
package past that 5-package cap and call the two ownership tools on those
directly. Still follow up per-package with analyze_install_script (for a
package the tool's lighter `installScriptScanScope:
"lifecycle-scripts-only"` signal flagged but didn't deep-scan — check
deepScanNote) and suggest_alternative the same way you would from the
pasted-content flow.
A non-npm list (a Python requirements.txt, a Cargo.toml, ...) can't go
through this flow — every audit tool here is npm-only. Say so, then check
each name==version with `query_vulnerabilities({ name, version,
ecosystem }) ("PyPI", "crates.io"`, ...), and label the result as a
per-package lookup, not a full audit.
If the user instead pastes two snapshots and asks what changed (a PR,
before/after, "did this upgrade introduce anything") — see
Comparing two snapshots below instead
of the single-inventory flow.
If the message contains no parseable package list at all, ask the user to
paste their package.json or lockfile — or give a GitHub repo URL — rather
than guessing at what to audit.
Steps
- Prefer passing the raw pasted inventory straight to
batch_query_vulnerabilities via its content input when the user gave a
package.json, lockfile, CycloneDX JSON, or SPDX JSON document. Only
manually build a packages array when the user gave a plain dependency
list instead.
- For raw
package.jsoncontent, setincludeDevDependencies: trueonly if
the user explicitly asked to include dev dependencies; otherwise the tool
defaults to production-ish dependencies only. Be explicit in the answer
about what set you audited. For yarn.lock, note that the file itself
cannot distinguish production from dev dependencies, so the tool will scan
every resolved package and emit a warning about that.
- Call
batch_query_vulnerabilitiesonce with the parsed/raw input. The tool
now chunks large inventories internally — do not re-chunk the request in
the skill layer unless the client's own request-size limit forces it.
Each finding already includes severity, a summary, CVE aliases, and the
fixed version — do not call query_vulnerabilities again per flagged
package just to re-fetch detail you already have. The only exception:
if the result has an enrichmentNote (a very large audit crossed the
enrichment cap, or some advisory details couldn't be fetched), the
vulnerabilities it names are ID-only — their severity and malware status
are unverified, so don't call those packages safe or non-malicious; call
query_vulnerabilities on those specific packages for full detail. Each result also carries signals (deprecated,
hasInstallScripts, popularityTier/maintenanceTier,
possibleTyposquatOf) directly — a clean vulnerabilityCount: 0 with a
flagged signals entry is NOT clean, and signals is null (not "the
package is fine") for a not-scanned git/file/workspace entry, so don't
read that null as reassurance either. When content was a lockfile, each
result also carries source (resolvedUrl/integrity and
nonRegistryHost/identityMismatch): identityMismatch: true means the
resolved tarball doesn't actually match the declared package/version —
the vulnerability count above was computed for the DECLARED package, not
whatever the tarball actually is, so treat this as its own critical
finding, separate from and on top of any CVE result. See the tool's own
warnings array for anything flagged this way. For a hand-typed
dependency list or raw package.json content (names never resolved
against a registry, unlike a real lockfile/SBOM), also check the result's
unresolvedPackages/existenceCheckNote: a name that doesn't exist on
npm shows vulnerabilityCount: 0 exactly like a genuinely clean package,
and that field is what tells the two apart — report an unresolved name as
its own finding (typo? never published?), never as "no known
vulnerabilities." Every finding also carries isMalware — true for a
confirmed-malicious package (an OSV MAL-* record, or a GitHub advisory
with CWE-506), not an ordinary bug. An isMalware finding is the
headline of the report: the package must be removed, not patched.
- For every package the batch call flags, use
signalsfrom step 3 first
— it already gives you deprecated/maintenanceSummary-equivalent data,
hasInstallScripts, and possibleTyposquatOf for the specific requested
version with no extra call. Only follow up with get_package (or
get_package_version when an exact version was provided) for what
signals does NOT cover: license, and a closer look at maintainers.
Treat install scripts as a separate risk signal from known CVEs, not
something to fold into the same score. If the user wants to know what a
flagged install script actually does rather than just that one exists,
follow up with analyze_install_script — it fetches the published
tarball and statically scans the script and the files it references
against npmscan's red-flags rubric, returning a totalScore/riskTier.
signals.hasInstallScripts covers preinstall/install/postinstall only — a
dependency's prepare never runs on a registry install. Also surface
signals.deprecated (and maintenanceSummary, when you did call
get_package) — a deprecated or abandoned dependency is a real finding,
not just a CVE footnote. If signals.possibleTyposquatOf is set, this package's name is one typo
away from a much more popular one — flag it prominently as a
supply-chain risk to verify, not as confirmed malice.
- If the user wants coverage beyond the direct dependencies you were given
(asks about "transitive"/"indirect" risk, or the inventory is small — up
to 15 root packages), call analyze_transitive_dependencies instead of, or
in addition to, step 3. It walks each root's own dependency tree (default
depth 2, capped at 3) and returns vulnerablePaths naming which direct
dependency actually pulled in each vulnerable transitive package —
batch_query_vulnerabilities alone only ever checks the exact packages
listed. It has no content shortcut, so build the packages array by
hand from the parsed inventory.
- For a package that's flagged as critical/high severity, deprecated, a
possible typosquat, or that the user specifically calls suspicious, add
the two ownership/supply-chain checks — don't run these for every clean
package in a large audit, they're expensive and only useful signal on
elevated-risk packages:
check_maintainer_changes— reconstructs maintainer-add/remove history
from the npm packument and flags account-takeover patterns (a new
maintainer who published shortly after being added, a sudden full
maintainer-list replacement, a long-standing maintainer quietly
dropped) plus GitHub repo transfers/archival. If it flags a newly added
or fully turned-over maintainer, 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 the 2025
chalk/debug ("qix") incident (~18 packages within ~2 hours). A large
total package count 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 — report it as a past
burst that stayed clean, not a current threat.
check_package_provenance— checks npm's Sigstore publish provenance
against reality: does the attested source repo/commit match
package.json's declared repository, is this package missing
provenance while its npm-scope/maintainer peers consistently have it,
and does the tarball's install scripts/dependencies match what's
actually committed at the attested source commit (a mismatch here is
the stolen-npm-token publish pattern). Structural only, not a
cryptographic re-verification. A version published before npm
provenance existed (2023-04-19) skips the peer comparison.
- Only call
get_latest_advisoriesif the user separately asks for
broader npm-ecosystem context — it is not part of the default flow, and
it is NOT the malware check: its malware/osv feeds only list recently
published advisories. Malware detection is the isMalware flag on the
findings from step 3.
- If the user asks about license policy/compliance (or pastes an
allow/deny list), call check_license_compliance with the same parsed
package list. With no policy given it applies the default enterprise
rule (copyleft/network-copyleft/proprietary = violation); pass
policy: { allow, deny } when the user states their own rule. Report
needsReview licenses (unrecognized/mixed SPDX expressions) separately
from confirmed violations — don't silently treat "unknown" as compliant.
- Once you have the full set of flagged CVE/GHSA findings (from step 3
and/or 5), and there is more than a couple of them, call
prioritize_remediation with one `{packageName, cveId, severity,
currentVersion, fixedVersion, advisoryId, findingType}` entry per finding
to get a remove-now / patch-now / patch-soon / scheduled / monitor tier
per finding (a confirmed-malware finding forces remove-now ahead of
everything else — pass each finding's id through as advisoryId, which
the tool looks up to detect malware advisories itself, and set
findingType: "malware" for every finding whose isMalware was true;
CISA KEV status overrides everything else after that; EPSS exploitation
probability is the primary ranking signal otherwise, and an EPSS of 10%+
always ranks at least patch-soon; severity is the fallback). If
malwareCheckFailedAdvisoryIds is non-empty, say those findings' malware
status is unknown. Lead the
summary report with this ranking instead of a flat severity list — it
answers "what do I fix first," which is usually what the user actually
needs from an audit with more than a few findings. Treat any remove-now
finding as the headline of the report, ahead of the ranked table, not
just its top row.
- For any package that ends up flagged as deprecated, vulnerable at its
latest version, abandoned/stale, or a confirmed typosquat, offer (don't
force) a replacement: suggest_alternative combines the maintainer's own
deprecation hints with category-matched search results and returns
plain-language whySuggested notes per candidate, or a
nonPackageAlternatives entry when a language built-in supersedes the
package entirely. Call it when the user asks what to use instead, or
proactively name it as available in the summary rather than always
running it unasked for every flagged package.
- Produce one summary report: a table of package → flagged issue(s) (CVE/
GHSA id + severity + fixed version, "risky install script", "deprecated/
unmaintained", "possible typosquat", "maintainer/provenance anomaly",
and/or "license violation") → the npmscanUrl from that tool's result →
a one-line recommendation (upgrade to the fixed version, patch, replace,
or no action needed). If prioritize_remediation ran, order the table by
its tier/rank instead of by package name.
Comparing two snapshots (PR review)
When the user gives a before and after snapshot (any mix of
package.json, package-lock.json, yarn.lock, pnpm-lock.yaml) and asks
what changed, call diff_dependencies({ before, after }) directly — this
replaces the batch-query flow above, it doesn't precede it.
- Lead with
installScriptIntroducedfindings — a routine-looking version
bump that quietly adds a postinstall script is the shape of a
compromised-maintainer supply-chain attack, and is the single highest-
signal field this tool returns. It counts preinstall/install/postinstall
only; a newly added prepare shows up in installScriptKeysIntroduced
but never runs on a registry install, so mention it without alarm.
- Check
sourceIntegrityChangedon every changed package too, right
alongside installScriptIntroduced — it catches a DIFFERENT attack shape:
a lockfile entry whose resolved tarball URL or integrity hash changed
while the version string stayed IDENTICAL (a compromised registry mirror,
or a hand-edited lockfile), which a version-only read of the diff would
report as "no change" (changeType: "source-swap"). See resolvedUrl/
integrity on the entry for what actually changed. If identityMismatch
is true, the tarball is a different package or version than declared —
tarballName/tarballVersion say what really installs, and the
vulnerability fields describe that. Report it as a headline finding.
- Check
projectLifecycleChanges(the SCANNED PROJECT's own root
preinstall/install/postinstall/prepare scripts) and overridesChanges
(overrides/resolutions/pnpm.overrides) even when the dependency list
itself shows nothing — a PR that only adds a root postinstall or quietly
removes a security override changes neither added/removed/changed,
and is exactly the kind of change a diff review exists to catch. Both are
counted in flaggedCount; don't report "no changes" on a diff that only
flagged one of these.
- Report
vulnerabilityDeltaper changed package (introduced / fixed /
still-vulnerable / still-clean), not just a final isVulnerable flag — the
direction of the change is the point of a diff.
- Note the detected
beforeFormat/afterFormatand anycomparisonNote
when the two snapshots are different formats (e.g. a range in
package.json resolved against a pinned lockfile version).
- yarn.lock has no direct/transitive distinction, so a diff against a
yarn.lock covers every resolved package in the file, not just direct
dependencies — say so if relevant to what changed.
If the user instead wants a machine-parseable PASS/WARN/FAIL merge
verdict — for a CI check or a PR-comment bot, not a conversational
explanation — use the ci-pr-gate skill instead; it applies a fixed policy
on top of the same diff_dependencies/simulate_dependency_upgrade output.
Output requirements
- Always include the
npmscanUrlfor every flagged package so the user can
read the full write-up on npmscan.com.
- Keep known-vulnerability, install-script, maintenance/deprecation,
typosquat, maintainer/provenance, and license risk visually separate — a
package with no CVEs but a postinstall script (or a possibleTyposquatOf
flag) is not "clean."
- When a CVE has a
fixedVersion, name it directly in the recommendation
("upgrade to X.Y.Z") rather than a generic "upgrade the package."
- State which set was audited (e.g. "checked 24 production dependencies,
skipped devDependencies").
- If the input was an SBOM, state that non-npm entries (if any) were skipped
and surface the tool's warning/ignored-count metadata when relevant.
Do not
- Do not guess a version that wasn't provided — call
batch_query_vulnerabilities
without a version rather than inventing one.
- Do not fabricate CVE/GHSA ids, severities, or fixed versions beyond what
the tools returned.
- Do not silently drop non-npm SBOM entries — say they were skipped because
npmscan's vulnerability pipeline is npm-only.
- Do not treat
possibleTyposquatOfas proof of malice — it's a rule-based
heuristic (name similarity + low popularity), not a verdict. Report it as
"worth verifying," matching the tool's own hedged language.
- Do not run
check_maintainer_changes/check_package_provenanceacross an
entire large inventory by default — reserve them for flagged/suspicious
packages or an explicit request, they're per-package deep checks, not a
batch scan.
- Do not treat a missing
provenanceor a repository transfer as confirmed
compromise on its own — both tools return hedged findings meant to prompt
verification, not a verdict.
- Do not treat a large
totalPackagesFoundfromcheck_maintainer_blast_radius
as a red flag by itself — many legitimate maintainers publish hundreds of
packages over a career. Only a tight-publish-cluster finding (several
packages' latest versions landing within a short window of each other) is
the actual signal.
- Do not invent a replacement package name —
suggest_alternativealready
distinguishes maintainer-named replacements from category-matched guesses
and reports nonPackageAlternatives when no package is the right answer;
don't override that with your own guess.
- Do not read
source.identityMismatch: trueas a minor detail folded into
the vulnerability count — it means the vulnerabilityCount/signals reported
for that package were computed for the DECLARED name/version, not
whatever the resolved tarball actually is. Report it as its own headline
finding, not a footnote.
- Do not read a name in
unresolvedPackages(from a hand-typed list or raw
package.json audit) as clean just because its vulnerabilityCount is 0 —
it means the name wasn't found on the npm registry at all, not that it has
no known vulnerabilities. This check doesn't run for a real lockfile/SBOM
input, since those names were already registry-resolved when generated.
- Do not call an
audit_github_repositoryresult clean when
coverage.complete is false or the summary starts PARTIAL AUDIT.
- Do not skip
projectLifecycleChanges/overridesChangeswhen reporting a
diff_dependencies result just because the dependency list itself shows
no changes — a PR that only touches the project's own root scripts or an
override is a real, flaggable change with nothing in added/removed/
changed to hint at it.
- Do not attempt to install, upgrade, or publish packages yourself; this
skill only reads data through NPMScan's read-only MCP tools.
Tools used
batch_query_vulnerabilities, get_package, get_package_version,
analyze_install_script, analyze_transitive_dependencies,
check_maintainer_changes, check_maintainer_blast_radius,
check_package_provenance,
check_license_compliance, diff_dependencies, prioritize_remediation,
enrich_npm_audit,
suggest_alternative, get_latest_advisories, audit_github_repository — 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.