VidToDoc
Lire en françaisSe connecter
F
Fireship
#npm#pnpm#supply chain attack

Preventing npm Supply Chain Attacks with pnpm and Sentry

Learn how to secure your JavaScript projects against sophisticated supply chain attacks using pnpm's built-in security features and Sentry's AI-powered error monitoring. This guide covers critical configurations and tools to protect your npm dependencies.

5 min readAI Guide

Introduction

This guide details how to protect your JavaScript projects from supply chain attacks, like the recent Mini Shai-Hulud worm, by leveraging pnpm's security features and Sentry's AI-driven monitoring. It provides actionable steps to prevent malicious code from compromising your dependencies and production environments.

Configuration Checklist

Element Version / Link
Language / Runtime Node.js 22+ (required for pnpm 11.x), Python (for PyPI variant of malware)
Main library pnpm 11.x (or higher)
Required APIs npm Registry, GitHub API (for OIDC tokens)
Keys / credentials needed npm publish tokens, GitHub tokens

Understanding the Mini Shai-Hulud Attack Mechanism

Understanding the Mini Shai-Hulud Attack Mechanism
The Mini Shai-Hulud worm exploited a misconfiguration in GitHub Actions' trusted publishing setup for npm packages. The attack involved:

  1. Pull Request Trigger: An attacker created and immediately closed a pull request from a forked repository. Due to the pull_request_target option in the workflow configuration, this triggered the main repository's publishing workflow, granting it permissions to the main repository's secrets.
  2. Cache Poisoning: The malicious code in the pull request wrote a poisoned file into the shared cache of the CI server. This cache is typically used by GitHub Actions to reuse dependencies between jobs.
  3. Token Exfiltration & Malicious Publish: When a legitimate, unrelated pull request was later merged, the poisoned file was triggered. It then grabbed the npm publish token from the CI cache and used it to publish compromised versions of packages to the npm registry.
  4. Lateral Movement: The malware scanned infected systems for other npm publishing tokens, using them to publish new poisoned versions of other packages, spreading the attack across the npm and PyPI ecosystems.
  5. Persistence and Dead-Man's Switch: On infected machines, the malware embedded itself into developer tooling like Claude Code and VS Code. It also installed a background process that would wipe the user's home directory (rm -rf ~/) if the stolen GitHub token was revoked, acting as a dead-man's switch.

Example of Malicious Code (Dead-Man's Switch Logic):

// This is an example of the malicious code logic, not to be implemented.
// It demonstrates how the dead-man's switch was designed.

var b9 = "IfYouRevokeThisTokenItWillWipeTheComputerOfTheOwner";
// ... other malicious payload code ...

// The malware would install a background process (e.g., gh-token-monitor.sh or LaunchAgent) 
// that periodically checks the validity of the stolen GitHub token.
// If the token is revoked (HTTP 40x response), it triggers a destructive command.
// Example of the destructive command:
// rm -rf ~/

Step-by-Step Guide for Preventing Supply Chain Attacks with pnpm

Step 1 — Implement pnpm for Enhanced Security

Step 1 — Implement pnpm for Enhanced Security
Why: pnpm version 11.x and higher includes built-in supply chain protection features that are enabled by default, significantly reducing the risk of installing compromised packages.

Install Command:

npm install -g pnpm@11 # Installs pnpm version 11 globally

Step 2 — Configure Minimum Release Age

Why: This feature delays the installation of newly published package versions, providing a window for malicious releases to be discovered and removed from the registry before they can be installed by your project. Most malicious packages are detected within an hour.

Configuration (in .npmrc or pnpm-workspace.yaml):

# .npmrc or pnpm-workspace.yaml
minimumReleaseAge: 1440 # Refuses packages published less than 24 hours (1440 minutes) ago

Step 3 — Block Exotic Subdependencies

Why: This setting prevents transitive dependencies from being pulled in from untrusted locations like random Git repositories or tarball URLs on attacker-controlled servers. It ensures that all dependencies originate from a trusted source, such as the configured npm registry.

Configuration (in .npmrc or pnpm-workspace.yaml):

# .npmrc or pnpm-workspace.yaml
blockExoticSubdeps: true # Only direct dependencies can use exotic sources; all transitive dependencies must come from trusted sources.

Step 4 — Approve Builds for Install Scripts

Why: Many npm malware attacks leverage install scripts that run automatically during npm install. pnpm 11.x blocks all install scripts by default, requiring explicit approval for packages to run code during installation. This gives you fine-grained control over what code executes on your system.

Usage:

pnpm approve-builds esbuild fsevents lcore-js # Whitelist specific packages to run install scripts

# To deny a package, prefix its name with '!'
pnpm approve-builds !malicious-package

# During install, packages with ignored builds are automatically added to pnpm-workspace.yaml
# with a placeholder value, which you can manually set to true or false.

Step 5 — Leverage Sentry's Seer Agent for Production Monitoring

Why: Even with robust prevention, issues can still arise in production. Sentry's Seer Agent, an AI-powered debugging agent, automatically investigates production issues, identifies root causes across services, and can even propose code fixes. This reduces manual debugging time and accelerates incident resolution.

Usage:

  1. Integrate Sentry: Set up Sentry in your application to capture errors, traces, logs, and replays.
  2. Ask Seer Agent: When a critical error or performance spike occurs, use natural language queries within Sentry's dashboard to ask Seer Agent to investigate.
  3. Review Insights: Seer Agent will analyze issue context, tracing data, logs, and performance metrics to provide a summary of the problem and its root cause.
  4. Draft Fixes with Autofix: Utilize Sentry's Autofix feature to collaborate with Seer Agent in drafting solutions and opening pull requests for identified issues.

Comparison Tables

Feature / Tool Traditional npm (without pnpm 11.x features) pnpm 11.x (with default security features)
Supply Chain Protection Limited, relies on manual vigilance Enhanced, with automated checks
Minimum Release Age Not available Default 1440 minutes (24 hours) delay for new package installs
Transitive Dependency Source Allows dependencies from any URL (Git, tarball) Blocks exotic subdependencies, enforces trusted sources
Install Script Execution Runs install scripts automatically by default Blocks install scripts by default, requires explicit approval
Cache Management Less secure, potential for cache poisoning More secure, but still susceptible if pull_request_target is misconfigured

⚠️ Common Mistakes & Pitfalls

  1. Using Older Package Managers or Versions: Relying on older versions of pnpm or other package managers like npm/yarn without equivalent security features leaves your project vulnerable. Fix: Upgrade to pnpm 11.x+ and ensure its security features are active.
  2. Misconfiguring GitHub Actions pull_request_target: Using pull_request_target without proper safeguards can allow pull requests from forks to run in the context of the main repository with elevated permissions, leading to cache poisoning or token exfiltration. Fix: Carefully review GitHub Actions workflows, especially those using pull_request_target, to ensure they only grant necessary permissions and do not expose sensitive secrets or caches to untrusted code.
  3. Ignoring Transitive Dependencies: Focusing only on direct dependencies and overlooking the sources of transitive dependencies can introduce malicious code. Fix: Enable blockExoticSubdeps in pnpm to ensure all transitive dependencies come from trusted registries.
  4. Blindly Allowing Install Scripts: Allowing all install scripts to run automatically can execute malicious code during package installation. Fix: Use pnpm approve-builds to explicitly whitelist only trusted packages that genuinely need to run scripts during installation.
  5. Manual Production Debugging: Relying solely on manual investigation of dashboards and logs for production issues is slow and reactive. Fix: Implement an AI-powered error monitoring solution like Sentry's Seer Agent to automatically investigate, diagnose, and help fix production problems proactively.

Glossary

Supply Chain Attack: A cyberattack that targets less secure elements in a software supply chain, such as open-source dependencies or build processes, to compromise a target system.
npm Registry: The public database of JavaScript packages that developers use to share and download code.
OIDC (OpenID Connect): An authentication layer on top of OAuth 2.0, used by npm's trusted publishing to authenticate CI/CD workflows without long-lived tokens.
Transitive Dependency: A dependency that your project uses indirectly, through one of its direct dependencies.
Dead-Man's Switch: A mechanism designed to activate a destructive action (e.g., data deletion) if a specific condition is met, such as the revocation of a stolen token.

Key Takeaways

  • The Mini Shai-Hulud worm demonstrated a sophisticated supply chain attack exploiting GitHub Actions and npm's trusted publishing.
  • Traditional phishing and token theft were not involved; the attack leveraged CI/CD misconfigurations and cache poisoning.
  • pnpm 11.x offers significant built-in protections against such attacks, including minimumReleaseAge and blockExoticSubdeps.
  • Explicitly manage which packages can run install scripts using pnpm approve-builds to prevent malicious code execution.
  • Sentry's Seer Agent provides AI-driven insights and automated root cause analysis for production issues, enhancing your incident response capabilities.
  • Regularly review your CI/CD pipeline configurations, especially those involving pull_request_target, to prevent similar vulnerabilities.
  • Be aware of the dead-man's switch tactic used by malware, which can destroy data upon token revocation.

Resources

All guidesLire en français →