Detecting Malicious npm Packages

Legal Notice: Analyze packages in an isolated, disposable environment. Some malicious packages execute on install (npm install runs lifecycle scripts automatically) or on import. Never analyze a suspect package on a workstation with credentials, SSH keys, cloud tokens, or network access to production. This skill is for defensive analysis and authorized incident response only.

Overview

The npm registry is the largest software package ecosystem in the world and the most heavily targeted by supply-chain attackers. Malicious packages reach victims through typosquatting (expresss, crossenv), dependency confusion, account/maintainer takeover (the 2025 Shai-Hulud worm and the event-stream compromise are canonical examples), and starjacking. The defining danger of npm is that npm install automatically runs preinstall, install, and postinstall lifecycle scripts with the developer's full privileges before any application code is invoked — so simply installing a package is enough to be compromised. Roughly 2% of npm packages use install scripts, which makes them both common and a powerful malware delivery vehicle.

Typical malicious behaviors are: exfiltrating environment variables, ~/.npmrc tokens, SSH keys, and cloud credentials to an attacker-controlled URL; opening reverse shells; dropping cryptominers; reading and posting process.env; obfuscating payloads with base64/eval; and self-propagating (worming) by stealing the maintainer's npm token and republishing trojanized versions of other packages they own.

This skill provides a repeatable triage workflow centered on GuardDog (Datadog's open-source heuristic scanner built on Semgrep + metadata rules), supplemented by manual tarball inspection, lockfile-based compromise checks against known-bad version lists, and dynamic detonation with network and filesystem monitoring. The goal is to decide, quickly and safely, whether a given package or a project's dependency tree contains malicious code.

When to Use

• Triaging a specific npm package before adding it as a dependency.
• Vetting a full package.json / package-lock.json during code review or onboarding a third-party library.
• Responding to a supply-chain advisory (e.g., a worm campaign) and needing to check whether your lockfiles pulled a known-bad version.
• Investigating an endpoint or CI runner suspected of having installed a trojanized package.
• Building a pre-install gate in CI/CD that blocks packages exhibiting malicious indicators.

Prerequisites

• An isolated VM or disposable container with no production credentials and snapshot/rollback capability.
• GuardDog:

  pip install guarddog
  # or run via Docker without local install:
  docker pull ghcr.io/datadog/guarddog
  alias guarddog='docker run --rm ghcr.io/datadog/guarddog'
  

• Node.js + npm (use --ignore-scripts when downloading for analysis).
• jq, tar, and optionally OSV-Scanner for known-vulnerability/known-malicious cross-checks:

  go install github.com/google/osv-scanner/cmd/osv-scanner@v1
  

• For dynamic analysis: a sandbox with egress logging (e.g., tcpdump, a DNS sink, or a network namespace).

Objectives

• Statically scan an npm package (or a whole dependency tree) for malicious heuristics without executing it.
• Identify install-script abuse, environment/credential exfiltration, obfuscation, and silent process execution.
• Cross-check lockfile-pinned versions against known-malicious version lists / OSV.
• Safely detonate a suspect package and observe network and filesystem behavior.
• Extract indicators of compromise (URLs, IPs, hashes) for blocking and threat intel.
• Produce a defensible verdict (benign / suspicious / malicious) with evidence.

MITRE ATT&CK Mapping

…