How to Defend Against npm Supply Chain Attacks: A Step-by-Step Guide

Introduction

In the wake of the Shai Hulud campaign and subsequent analyses by Unit 42, the npm ecosystem has become a primary target for attackers seeking to infiltrate software supply chains. From wormable malware that self-replicates across packages to multi-stage attacks that establish persistence in CI/CD pipelines, the threat landscape is evolving rapidly. This guide provides a structured approach to understanding and mitigating these risks, helping you protect your projects and infrastructure.

What You Need

• Basic knowledge of npm and Node.js package management
• Access to your CI/CD pipeline (e.g., GitHub Actions, Jenkins, GitLab CI)
• Security tooling or at least the ability to install npm packages like npm-audit or third-party scanners
• Administrative rights to modify repository settings and pipeline configurations
• Time to audit existing dependencies and implement new processes

Jump to tips

Step 1: Map Your npm Attack Surface

Begin by identifying every point where npm packages enter your development lifecycle. This includes direct dependencies, transitive dependencies, devDependencies, and any packages installed in CI/CD scripts.

• Run npm ls --depth=Infinity to get a complete dependency tree.
• Audit your package-lock.json or yarn.lock for unexpected packages.
• Review scripts in .npmrc, preinstall, postinstall, and prepare hooks—these can execute arbitrary code.
• Check if your CI/CD pipeline uses npm install without lockfile verification.

Key insight: Attackers often exploit typosquatting (e.g., lodash vs. lodahs) and dependency confusion (using public package names that conflict with internal private packages). After the Shai Hulud attack, wormable malware was found that could spread by infecting other popular packages through typo-squatted names.

Step 2: Enforce Package Integrity and Provenance

Once you know your attack surface, you must ensure every installed package is legitimate and unmodified.

• Use lockfiles (package-lock.json or yarn.lock) and commit them to version control. This ensures deterministic installs.
• Enable npm package provenance (npm 9.5+): Use npm install --provenance to verify packages come from trusted sources (via Sigstore).
• Audit with npm audit regularly. Integrate it into your CI pipeline to fail builds on critical vulnerabilities.
• Use SCA tools (Software Composition Analysis) like Snyk, WhiteSource, or GitHub Dependabot for automated alerts.

For example, multi-stage attacks often deliver payloads in a second or third package downloaded during installation. Lockfiles help detect when a package’s integrity hash changes without your knowledge.

Step 3: Harden CI/CD Pipelines Against Persistence

Unit 42’s research highlighted how wormable malware can establish persistence inside CI/CD runners. Attackers may inject malicious scripts that survive across builds by modifying pipeline configuration files or using token theft.

• Limit runner permissions: Use short-lived, scoped tokens instead of full repository access tokens. Rotate them frequently.
• Isolate build environments: Run npm install in ephemeral containers that are destroyed after each build. Avoid caching node_modules between builds unless checksums are verified.
• Audit pipeline scripts: Review YAML/JSON pipeline files for unexpected commands. Ensure only authorized users can modify them.
• Disable install scripts when possible: Use npm install --ignore-scripts for packages that do not require build steps. For others, audit the scripts field in each package.

In the Shai Hulud case, initial access via a single malicious package led to CI/CD token exfiltration, enabling the attacker to push updates to other repositories. This step prevents that lateral movement.

Step 4: Detect and Respond to Wormable Malware

Wormable npm malware is designed to spread autonomously, often by compromising other packages in the registry. Detection requires a multi-faceted approach.

• Monitor network behavior: If your build process makes unexpected outbound connections to IPs or domains not related to npm, it could indicate beaconing malware.
• Check for unusual file operations: Wormable malware often modifies package.json or creates new files in other projects. Use runtime monitoring tools like Falco or auditd.
• Implement behavior-based detection: Look for anomalies such as packages downloading additional payloads during install, or process spawning.
• Use registry mirrors: Consider using a private npm registry (e.g., Verdaccio) that caches packages and allows you to scan and approve updates before distribution.

Multi-stage attacks may start with a benign-looking package that later downloads a second stage. After Shai Hulud, Unit 42 observed packages that remained dormant until triggered by a specific environment variable.

Step 5: Maintain Continuous Vigilance

Securing the npm supply chain is not a one-time task. New threats emerge frequently, so you must embed ongoing practices.

• Subscribe to security advisories (npm advisory database, GitHub Security Advisories).
• Automate dependency updates using Dependabot or Renovate, but always review changes before merging.
• Conduct periodic red team exercises that simulate supply chain attacks, such as dependency confusion or typo-squatting.
• Educate developers on safe npm usage: avoid sudo, verify package authors, and double-check package names.

The evolving tactics—like the wormable malware in Shai Hulud that used CI/CD as a launchpad—require a proactive mindset. By staying informed and automating defenses, you reduce the chance of being the next victim.

Tips for Success

• Start small: Begin with the most critical projects (those that are publicly distributed or have high privileges). Apply mitigations incrementally.
• Combine tools: No single tool catches everything. Use a mix of SCA, runtime detection, and registry monitoring.
• Document your process: Create runbooks for incident response when a malicious package is detected. Include steps to revoke tokens and rebuild containers.
• Test rollback: Ensure you can quickly revert to a known good state (e.g., by pinning exact versions in package.json).
• Engage with the community: Share your findings with npm maintainers and security researchers to help improve registry defenses.

By following these steps, you’ll be equipped to handle the current npm threat landscape—from wormable malware to multi-stage CI/CD persistence—and stay ahead of future attacks.