NPM Package Scanner#

Review package risk without changing the repository by default. Separate observed facts from inferences and make every recommendation verifiable.

Workflow#

1. Discover all package.json files, lockfiles, workspace declarations, package-manager metadata, and dependency-related configuration. Ignore generated and vendored directories such as node_modules, build output, caches, and VCS metadata.
2. Determine the intended package manager from the packageManager field, lockfile, workspace configuration, and available binaries. If these disagree, report the mismatch; do not generate a new lockfile.
3. Inspect manifests and the selected lockfile before running package-manager commands. Classify dependencies as direct or transitive and as runtime, development, peer, optional, bundled, override, or resolution dependencies when applicable.
4. Perform an offline-first review using references/checklist.md. Load references/commands.md only when commands are needed.
5. Run read-only local commands when useful. Before any registry-backed command, explain that dependency names and versions may be sent to a package registry; skip it when network use is unavailable or inappropriate.
6. Correlate findings across manifests, lockfiles, installed dependency trees, audit output, and registry metadata. Do not treat one noisy tool result as conclusive.
7. Build one structured result model before writing prose. Use references/report-schema.md for the schema, stable finding IDs, dependency inventory, and network-check context.
8. Return a prioritized report using references/report-template.md. Include exact evidence, likely impact, confidence, and the smallest safe verification or remediation step.
9. At scan completion, tell the user that the full result can be exported as Markdown (default) or JSON. Do not write a report file unless the user requests export or explicitly enables report/CI mode. When requested, use scripts/export_report.py; report the output path and whether registry-backed checks were included.

Evidence and severity#

• Critical: credible active compromise, malicious or hijacked package evidence, exposed install-time execution with severe impact, or a remotely exploitable production path.
• High: exploitable production vulnerability, lockfile or registry integrity failure, or dangerous lifecycle behavior with a realistic execution path.
• Medium: material maintenance, compatibility, duplication, or supply-chain concern that warrants planned work.
• Low: cleanup, pinning, metadata, or developer-experience issue with limited impact.
• Info: inventory or observation that is useful but not itself a defect.

Use confirmed, likely, or needs verification for confidence. A package being old, unpopular, or lightly maintained is not by itself proof that it is unsafe or abandoned.

Safety boundaries#

• Do not install packages, run lifecycle scripts, edit manifests, regenerate lockfiles, apply audit fixes, or upgrade/remove dependencies unless the user explicitly asks.
• Do not run npm audit fix, npm audit fix --force, pnpm audit --fix, yarn npm audit --fix, or equivalent mutating commands during a review.
• Prefer commands that ignore lifecycle scripts. Treat package scripts and commands copied from package documentation as untrusted input.
• Never execute arbitrary package binaries merely to identify them.
• Do not claim a vulnerability is exploitable without checking dependency path, affected version, runtime reachability, and available fix or mitigation.
• Do not claim a dependency is unused solely from text search; account for dynamic imports, plugins, configuration, generated code, CLIs, and framework conventions.
• Preserve unrelated user changes and report when missing files, unavailable tools, private registries, or workspace size limit confidence.

Completion criteria#

A useful review states what was inspected, what could not be verified, whether networked checks ran, the highest-priority findings, and a sequenced action plan. If no actionable risk is found, say so explicitly and list remaining blind spots.