Shai-Hulud Supply Chain Attack: In-Depth Analysis of the Keyv npm Package Compromise and Defense Guide

Incident Overview

The open-source ecosystem has once again been hit by a serious supply chain security crisis. Recently, the security community disclosed that the widely popular npm package Keyv and a series of its related dependencies were compromised in an active supply chain attack known as Shai-Hulud. This news immediately raised high alert across the developer community, as Keyv serves as a universal key-value storage abstraction layer that is directly or indirectly depended upon by a massive number of projects.

Shai-Hulud (named after the giant sandworms from Frank Herbert's science fiction masterpiece Dune, where they are revered by the Fremen as embodiments of the desert god) is the codename for a recently active class of self-propagating npm attacks. The core characteristic of these attacks is their worm-like spreading capability — once a maintainer's account or publishing credentials are stolen, the attacker injects malicious code into multiple packages they maintain, then uses newly stolen credentials to continue lateral propagation, much like the sandworms of Dune that endlessly devour everything in their path. Security researchers chose this name to aptly describe the attack's behavioral pattern of "lurking underground and suddenly erupting" within the dependency ecosystem.

Why Keyv Became a Core Target for Supply Chain Attacks

Keyv's Critical Position in the npm Ecosystem

Keyv is a simple yet powerful key-value storage library that provides a unified API capable of interfacing with Redis, MongoDB, SQLite, in-memory caching, and various other backends. Due to its flexibility and ease of use, Keyv has been incorporated into the dependency trees of numerous well-known frameworks and toolchains, including caching libraries, HTTP clients (such as got), and more.

To understand Keyv's impact range, one must grasp the concept of transitive dependencies in the npm ecosystem. Transitive dependencies are packages that a project does not directly declare but indirectly introduces through its direct dependencies' dependency chains. In the npm ecosystem, a typical medium-sized project might declare 30-50 direct dependencies, but its complete dependency tree often contains 500-1,500 packages. According to npm's official data, the registry hosts over 2 million packages with billions of weekly downloads. In this highly interconnected network, if we analyze the npm dependency graph from a graph theory perspective, Keyv qualifies as a "high betweenness centrality" node — numerous shortest paths pass through it, meaning its compromise can impact downstream projects at an exponential rate. Research shows that the top 1% of highly connected packages in the npm ecosystem can directly or indirectly affect over 70% of active projects.

This means that even if developers have never actively installed Keyv, their projects are very likely to have introduced this package through transitive dependencies. This characteristic of being deeply embedded in the ecosystem is precisely what supply chain attacks favor most — attacking a highly connected node allows maximum downstream impact at minimal cost.

Chain Reaction and Scope of Propagation

The phrase "Keyv and friends" refers to an entire group of packages related to Keyv. Attackers are often not satisfied with compromising a single target — they leverage the publishing permissions of compromised accounts to simultaneously poison multiple related packages. This mass-poisoning approach dramatically expands the attack surface and makes defense and cleanup extraordinarily complex.

In npm's permission model, a single maintainer account typically holds publishing rights to multiple packages. Many open-source maintainers simultaneously manage a group of functionally related packages (for example, Keyv's various storage adapters: @keyv/redis, @keyv/mongo, @keyv/sqlite, etc.). Once a single account is breached, the attacker gains control over the entire package family. What makes this even more challenging is that npm version publishing takes effect immediately — after a new version is published, all downstream projects that haven't locked exact versions will automatically pull the malicious version on their next installation. This time window is often only a few hours, but that's more than enough to cause mass infection.

Technical Analysis of the Shai-Hulud Attack

Worm-Like Self-Propagation Mechanism

The most alarming characteristic of the Shai-Hulud attack series is its automated propagation capability. Malicious code typically executes lifecycle scripts such as postinstall during package installation or runtime, scanning the local environment for sensitive information.

npm's lifecycle scripts are a series of hook functions defined in package.json that execute automatically at different stages of package installation. Among these, the preinstall, install, and postinstall hooks are most critical: preinstall executes before package installation, and postinstall executes after installation completes. These scripts have the same system privileges as the current user and can execute arbitrary code — reading and writing files, making network requests, spawning child processes. This design was originally intended to support legitimate use cases like native module compilation (such as node-gyp compiling C++ extensions), but it also provides a perfect execution entry point for malicious code.

The sensitive information typically scanned by attack payloads includes:

• npm authentication tokens: Tokens stored in .npmrc files. .npmrc is npm's configuration file, located in the user's home directory or project root, where the //registry.npmjs.org/:_authToken= field stores authentication tokens. Possessing this token allows publishing packages under that user's identity without additional verification (unless 2FA is enabled).
• Cloud service credentials: AWS ~/.aws/credentials files, GCP service account JSON keys, Azure subscription credentials, etc.
• Passwords and API keys in environment variables: Many developers store sensitive information in environment variables, which are readable by any process running under the same user.
• Deployment keys in CI/CD systems: In continuous integration environments like GitHub Actions, GitLab CI, and Jenkins, build tasks typically need access to npm publishing tokens and deployment keys. While these keys are injected as "secrets," they are decrypted into environment variables at runtime, and malicious postinstall scripts can easily read them during the build phase.

Once new npm publishing permissions are obtained, the malicious script automatically plants the same payload into other packages maintained by the victim, creating a worm-like chain infection. This is precisely why it earned the "sandworm" moniker. This self-replication mechanism means the attack propagates far faster than human response speed — before security teams discover and revoke the first malicious version, the virus may have already spread to dozens of new packages.

Credential Theft and Data Exfiltration Paths

Beyond self-replication, attack payloads typically exfiltrate stolen sensitive data to attacker-controlled servers, or leverage public platforms like GitHub to create repositories for staging stolen information.

Data exfiltration techniques are diverse, and attackers choose different strategies based on the target environment's network restrictions: the most common approach is sending data via HTTPS POST requests to attacker-controlled remote servers, as this traffic is indistinguishable from normal API calls and extremely difficult for firewalls to identify; more covert methods include DNS tunneling — encoding stolen data into DNS query subdomains, which is highly stealthy since DNS traffic is almost never blocked by enterprise networks; some attackers also use GitHub/GitLab public APIs to create private repositories or Gists for storing stolen data, since these platforms' domains are whitelisted in most network environments and traffic won't trigger any security alerts.

In previous supply chain attacks on packages like ua-parser-js, coa, and rc, security researchers have repeatedly observed similar exfiltration patterns. Attackers even incorporate delayed execution and conditional logic into payloads — activating credential theft behavior only when a CI environment is detected (via the CI=true environment variable) to reduce the probability of discovery on developers' local machines.

Developer Emergency Response and Investigation Steps

Immediate Investigation and Remediation Measures

For developers and teams that may be affected, the following measures are recommended:

1. Lock dependency versions: Check package-lock.json or yarn.lock to confirm whether Keyv and related packages have been updated to suspicious malicious versions. Lockfiles record the exact version number and integrity hash of every package in the dependency tree, serving as the first line of defense against automatic upgrades to malicious versions. Always include lockfiles in version control.
2. Audit installation scripts: Be vigilant about abnormal postinstall script behavior in packages. Use the --ignore-scripts flag for defensive installations. You can also use the npm query ':attr(scripts, [postinstall])' command to list all dependencies containing postinstall scripts.
3. Rotate all credentials: If related packages were installed during the affected time window, immediately rotate npm tokens, cloud keys, and CI/CD credentials. npm tokens can be revoked using the npm token revoke command, then regenerated. Also check npm's access logs to confirm whether any abnormal package publishing activity occurred.
4. Roll back to known safe versions: Pin dependencies to trusted versions from before the attack occurred and wait for official fixes. Use npm audit signatures to verify package signature integrity.

Long-Term Supply Chain Security Defense Strategy

This incident once again highlights the fragility of the modern software supply chain. Teams should establish more comprehensive protection systems:

• Enable npm two-factor authentication (2FA) and enforce provenance for package publishing. npm provenance is a supply chain security mechanism built on the Sigstore project. Sigstore is an open-source project under the Linux Foundation that provides keyless signing capability — it binds package publishing to specific CI/CD workflows, verifies publisher identity through the OIDC (OpenID Connect) protocol, and records signatures in an immutable transparency log (Rekor). With provenance enabled, users can verify whether a package was actually built and published by its declared GitHub Actions workflow, rather than manually pushed using a stolen token.
• Use supply chain security tools like Socket and Snyk for continuous dependency monitoring. These tools have different approaches: Socket employs a "deep package inspection" strategy, statically analyzing package source code to identify suspicious behavior patterns like network requests, filesystem access, and environment variable reads, rather than relying solely on known vulnerability databases; Snyk maintains a continuously updated vulnerability database combined with dependency graph analysis to assess actual reachability. Using both together can cover "known vulnerabilities" and "zero-day malicious behavior" threat categories.
• Isolate sensitive credentials in CI environments and follow the principle of least privilege. Specific practices include: using scoped granular access tokens rather than global tokens for npm publishing; separating package installation and publishing into different jobs in CI, so the installation phase doesn't expose publishing credentials; using OIDC federated identity authentication instead of long-lived static tokens.
• Regularly review the dependency tree and reduce unnecessary transitive dependencies. Use npm ls --all to view the complete dependency tree and evaluate whether lighter alternatives exist. The "zero-dependency" movement has also emerged in the community, advocating direct implementation of simple functionality rather than importing external packages.

Reflection: The Ongoing Crisis of Open-Source Trust Chains

The Shai-Hulud attack is not an isolated incident. From the early event-stream incident to the continuous poisoning of multiple popular packages in recent years, the npm ecosystem's trust model faces severe challenges.

The event-stream incident is a landmark case of open-source supply chain attacks, occurring in 2018. The attacker right9ctrl gained the trust of the original maintainer dominictarr by posing as an enthusiastic contributor, obtaining publishing permissions for the package. Subsequently, the attacker introduced a malicious dependency called flatmap-stream, which contained targeted theft code aimed at the Copay Bitcoin wallet. This incident first brought widespread industry attention to the "maintainer social engineering" attack vector and exposed the structural vulnerability of critical open-source infrastructure being maintained by single volunteers.

Since then, the npm ecosystem has experienced incidents including ua-parser-js (7 million+ weekly downloads, maintainer account stolen), colors and faker (maintainer deliberately sabotaged as protest), and node-ipc (maintainer planted destructive code targeting Russian IPs). Each incident reveals trust chain fragility from different angles: account security, maintainer mental health, political motivations — all can become attack entry points.

To address this systemic risk, the industry is advancing multi-layered defense frameworks. SLSA (Supply-chain Levels for Software Artifacts, pronounced "salsa") is a supply chain security framework initiated by Google and promoted by OpenSSF (Open Source Security Foundation), defining four security levels from L1 to L4 covering build process automation, auditability, isolation, and source verifiability. npm provenance implementation corresponds to SLSA L2-L3 requirements. Additionally, the OpenSSF Scorecard project provides automated security health scoring for open-source projects, evaluating whether projects have enabled branch protection, code review, dependency updates, and other security practices.

The core value of open-source software lies in collaboration and sharing, but this openness inherently becomes an attacker's breakthrough point. The compromise of a single maintainer account can ripple through dense dependency networks to affect thousands of projects. This reminds the entire industry: relying solely on individual maintainers' security awareness is far from sufficient. Platform-level mandatory security mechanisms, automated anomaly detection, and community rapid response capabilities are the keys to containing such worm-like attacks.

The npm platform has progressively strengthened security measures in recent years: since 2022, high-impact packages (over 1 million weekly downloads or more than 500 dependents) require maintainers to enable 2FA; login verification and suspicious publishing behavior alerts have been introduced; granular access tokens are now supported to restrict token scope by package and IP range. However, these measures still cannot fully defend against token theft targeting CI/CD environments, as automated publishing workflows inherently require non-interactive authentication methods.

For every developer, treating npm install as an act of trust that requires careful consideration may be the most fundamental security literacy of our era. Every dependency installation essentially grants code execution privileges to a stranger whose source code you may have never reviewed — understanding this is the first step toward building supply chain security awareness.