Keyv npm Worm: AI Coding Agent Security Guide

The short answer

The August 4, 2026 Keyv/Cacheable npm compromise was not merely a bad dependency release. Independent analyses from Wiz, Snyk, and Datadog Security Labs independently found malicious package versions that used an npm preinstall hook, credential-stealing payloads, and repository-local Claude Code or VS Code execution paths. The confirmed starting point was [email protected], followed by related packages including cacheable, cacheable-request, file-entry-cache, cache-manager, and ecto.

If an affected version was installed or its lifecycle script executed, treat the developer workstation or CI runner as potentially compromised. Do not simply upgrade the package. Isolate the host, preserve evidence, remove persistence, revoke credentials from a clean machine, inspect cloud and source-control activity, and rebuild the environment.

This guide explains what happened, how AI coding agents change the exposure path, how to check lockfiles and package manifests, and how to build a safer dependency-and-agent workflow.

Key takeaways

• The initial confirmed malicious release was [email protected]; later independent package sweeps identified additional affected releases, including @cacheable/[email protected], @cacheable/[email protected], [email protected], [email protected], [email protected], and [email protected].
• The payload could run during dependency installation through preinstall, before an application imported the library.
• Repository-local .claude and .vscode files created a second execution route when workspace configuration was trusted or activated.
• Valid build provenance did not make the artifact safe: a legitimate release workflow can attest to compromised source.
• Package download counts are not victim counts. Exposure depends on the exact resolved version and whether the install path executed lifecycle scripts.
• AI coding agents increase the importance of repository trust, hook review, tool permissions, and credential isolation. They do not remove ordinary package-supply-chain controls.

What happened in the Keyv npm incident

On August 4, researchers observed malicious changes in the Keyv ecosystem. Wiz reported that a compromised maintainer identity introduced IDE persistence files and then published a malicious [email protected] release. Snyk independently downloaded and compared registry tarballs without installing them, confirming a preinstall script and two payload files. Datadog reconstructed the release timeline and propagation behavior from package, GitHub, and provenance evidence.

The incident had several layers:

1. A package lifecycle entry point. The compromised manifest added "preinstall": "node setup.mjs". Package managers that permitted lifecycle scripts could execute the loader during installation.
2. A larger second stage. The loader started a compiled payload named Math_Symbol.js. The research reports describe collection of developer, cloud, CI, registry, and other secrets, with technical details attributed to their respective malware analysis.
3. A repository-local entry point. Researchers found .claude/settings.json, .claude/setup.mjs, .vscode/tasks.json, and .vscode/setup.mjs changes. These files created a path through Claude Code session-start behavior or VS Code folder-open tasks when trust and settings allowed it.
4. Propagation. The same payload appeared in additional packages and repositories. The exact campaign-wide total changed as researchers and registries updated their views, so a single headline count should not be treated as a complete affected-package list.

The important operational distinction is between a package being published, a package being resolved, a package being installed, and a payload actually executing. Those are different events and should be investigated separately.

Visual: the two execution paths

Figure 1 — Original execution-path diagram. It distinguishes repository configuration from npm lifecycle execution; either path requires its own investigation. The incident details are based on Wiz, Snyk, and Datadog analyses linked above.

Which versions should teams investigate?

Do not rely on a namespace-wide blocklist or the current latest tag. Registry state changed during the incident, and some packages remained clean while related releases were compromised. Start with lockfiles, package-manager logs, private mirrors, CI caches, and artifact records.

The following releases were independently reported during the initial technical analyses:

This is an investigation starting set, not a permanent campaign manifest. Wiz, Snyk, and Datadog all documented changing package inventories and different collection scopes. Use their current affected-package lists and your own resolved artifacts for incident response.

How to check a repository without executing the package

Use a clean analysis machine or an isolated container. Avoid running npm install in a potentially affected checkout until you have reviewed the lockfile and package metadata. The first goal is to identify whether a vulnerable version was resolved, not to prove the payload by executing it.

1. Search manifests and lockfiles

1rg -n '"(keyv|cacheable|cacheable-request|cache-manager|file-entry-cache|flat-cache|ecto)"' \
2  package.json package-lock.json npm-shrinkwrap.json pnpm-lock.yaml yarn.lock 2>/dev/null

Then inspect the resolved version and integrity value in the relevant lockfile. A dependency name alone is insufficient: transitive packages can be introduced by linting, testing, bundling, or framework tooling.

2. Search installed trees and caches

1find node_modules -path '*/keyv/package.json' -o \
2  -path '*/cacheable/package.json' -o \
3  -path '*/cache-manager/package.json' 2>/dev/null
4
5find ~/.npm ~/.cache -type f \( -name '*keyv*' -o -name '*cacheable*' \) 2>/dev/null

Do not open suspicious JavaScript files in an environment containing production credentials. Copy artifacts to an isolated analysis area and calculate hashes before deeper inspection.

3. Inspect package metadata and lifecycle scripts

1npm view [email protected] version dist.integrity dist.tarball scripts --json
2npm pack --ignore-scripts [email protected] --pack-destination ./quarantine

--ignore-scripts prevents local lifecycle execution during the pack operation. Do not assume this makes every later operation safe: archive extraction, editor tasks, repository hooks, and agent configuration still need review.

4. Search for repository-local execution hooks

1find .claude .vscode -maxdepth 2 -type f -print 2>/dev/null
2rg -n 'setup\.mjs|runOn|folderOpen|SessionStart|preinstall|postinstall' \
3  .claude .vscode package.json 2>/dev/null

A suspicious hook is an exposure indicator, not proof that it ran. Correlate it with editor trust decisions, Claude Code logs, shell history, process telemetry, and network events.

Incident response when an affected install ran

Treat the machine as compromised if an affected package’s lifecycle script executed, the suspicious repository hook ran, or you cannot establish that both paths were blocked.

Contain first

• Disconnect the workstation or runner from sensitive networks while preserving volatile evidence where your incident process requires it.
• Stop automated builds and publication jobs that use the affected runner.
• Disable or quarantine suspicious .claude, .vscode, setup.mjs, and payload artifacts rather than deleting the only evidence copy.
• Record package names, resolved versions, install timestamps, host identity, logged-in accounts, and CI job IDs.

Revoke from a clean environment

Rotate GitHub, npm, cloud, SSH, database, Kubernetes, Vault, CI, signing, and model-provider credentials that were available to the process. Do this from a clean administrative system, and remove active sessions where supported. Researchers reported collection targets spanning developer and cloud configuration, but the exact data exposed depends on host permissions, operating system, installed tools, and whether the second stage ran successfully.

Before rotating tokens, check for local token-monitor or persistence logic. A dead-man or revocation watcher can react to credential changes. SafeDep and the independent analyses recommend disabling malicious monitoring or persistence before completing rotation.

Hunt for follow-on activity

Review GitHub audit logs, npm publication history, cloud API activity, CI workflow changes, new SSH keys, package releases, repository webhooks, and unusual authentication locations. Look for unauthorized package publications or repository commits made with identities available to the affected host.

Do not convert a package’s large download count into a claim about compromised victims. The evidence supports ecosystem reach, not a verified number of successful executions.

Rebuild rather than trust cleanup

For a developer workstation, reinstall the operating system or use your approved clean-image process when the risk and evidence justify it. For CI, destroy and recreate the runner from a trusted image. Restore only reviewed source and dependency lockfiles. Pin known-clean versions, regenerate caches, and require a fresh dependency installation with lifecycle controls.

Why AI coding agents make this incident more serious

AI coding agents often work in repositories that contain project instructions, tool configuration, scripts, and credentials. They can also read files, run commands, modify code, and continue across multiple turns. That makes repository trust a security boundary, not just a convenience setting.

The Keyv incident demonstrates two separate controls that should not be conflated:

• Dependency execution control: package managers and CI should restrict lifecycle scripts, review install-time behavior, and isolate build credentials.
• Agent and editor execution control: coding tools should treat repository-provided settings, hooks, tasks, and instructions as untrusted until explicitly reviewed.

A secure workflow should give an agent short-lived credentials, a narrowly scoped workspace, network egress restrictions, and explicit approval for package installation, publishing, secret access, and infrastructure changes. This complements the broader harness and approval concepts covered in OpenAI Codex’s open agent infrastructure guide and the security practices in Claude Code Auto Mode.

The lesson is not to disable every agent. It is to make the agent’s authority smaller than the repository’s potential to request action.

A safer CI and agent baseline

1. Run dependency resolution in an isolated, ephemeral environment.
2. Disable lifecycle scripts by default where the project permits it; enable them only for reviewed packages and controlled build stages.
3. Require lockfiles and verify registry integrity metadata against an approved source.
4. Scan diffs for new lifecycle scripts, executable payloads, editor hooks, agent settings, and workflow changes.
5. Keep cloud, package, and source-control credentials out of ordinary developer shells.
6. Give CI jobs short-lived, least-privilege identities with separate publish permissions.
7. Block unreviewed outbound network access from dependency installation and test jobs.
8. Treat provenance as evidence of build origin, not a guarantee that source was uncompromised.
9. Record agent tool calls, approvals, package installs, and publication events.
10. Rebuild runners after a suspicious dependency or repository hook executes.

For teams standardizing portable agent instructions and tool integrations, Agent Plugins and MCP is useful background—but plugin portability should never bypass the same trust, review, and permission boundaries.

Common mistakes

“We upgraded, so we are safe.”

An upgrade does not prove that a compromised version never ran. Investigate installation history and rotate credentials when execution is possible.

“The package has valid provenance.”

Datadog and Snyk documented valid provenance around the malicious release. A trusted workflow can faithfully attest to a malicious source state.

“Our app never imports Keyv.”

Install-time scripts run before application import. Transitive development dependencies can still expose a workstation or CI runner.

“Opening the repository proves compromise.”

Repository hooks depend on editor settings, workspace trust, and user or agent actions. Opening a checkout is an exposure condition; correlate it with telemetry.

“The largest reported package count is the confirmed total.”

The research scopes and registry snapshots changed during the incident. Use exact versions, lockfiles, hashes, and current source lists.

FAQ

Is this an AI-specific vulnerability?

No. It is a software supply-chain compromise affecting npm packages. It is especially relevant to AI-assisted development because Claude Code, VS Code, and agent workflows may automatically inspect or act on repository-local configuration.

Should every Keyv or Cacheable package be blocked forever?

No. Investigate exact package names and versions against current researcher and registry data. A namespace-wide block can miss unrelated packages and create unnecessary disruption.

Can --ignore-scripts solve the whole problem?

No. It blocks one npm lifecycle route, but it does not remove malicious source, repository hooks, editor tasks, existing caches, or credentials already exposed by an earlier run.

What should a team preserve for forensics?

Preserve lockfiles, package archives, package-manager logs, CI job records, shell and agent logs, process/network telemetry, suspicious repository files, and credential-use audit logs. Work from copies in an isolated environment.

Conclusion

The Keyv npm worm is a practical warning about the modern developer workstation. A dependency can be reached transitively, execute before application code, and coexist with repository-local hooks aimed at editors or coding agents. The safest response combines ordinary software-supply-chain discipline with explicit agent trust boundaries.

Check resolved versions without executing them. Isolate any host where execution may have occurred. Revoke credentials from a clean system, investigate downstream activity, and rebuild runners instead of trusting cleanup. For future workflows, make package installation, repository hooks, secret access, network egress, and publication deliberate approval points.

Sources and visual credits

• Wiz Research: keyv and cacheable npm package hijack
• Snyk: Inside the keyv npm supply-chain compromise
• Datadog Security Labs: Worm compromises hundreds of npm packages
• The Hacker News: Keyv-linked npm worm analysis
• Figure 1: original Mermaid diagram by Essam Mdani, based on the independently reported execution paths in Wiz, Snyk, and Datadog research.

Related reading

Continue exploring related AI engineering and developer tooling topics:

• Claude Code 2.1.246: Security, MCP, and Auto Mode Changes Developers Should Audit
• Muse Spark 1.3: Meta’s Frontier Coding Agent
• Meta Muse Code: A Practical Guide to Long-Horizon Coding Agents