Join our Newsletter — 33% off our NHI Course
Home› Guides› Malicious Package Worm Response Playbook: Containing Self-Spreading npm…
Template Software & AI Supply Chain

Malicious Package Worm Response Playbook: Containing Self-Spreading npm and PyPI Malware

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 27 October 2026 10 min read
On this page

A self-propagating package worm turns every developer and CI token it steals into the means of its next infection, so a normal "remove the bad version" response is too slow. Worms such as Shai-Hulud run at install time, harvest npm, GitHub and cloud credentials, and use them to publish trojanised versions of every package the victim maintains, often within hours. Containment therefore depends on revoking tokens at scale, freezing dependency resolution and cleaning CI runners, not just on blocking one package. This template is a scenario playbook for npm, PyPI and similar registries, written for security operations, platform engineering and package maintainers. It sits under the broader Supply Chain Compromise Response Playbook and covers only what is different about worms.

How to use this template

  • Replace the placeholders: fill in every [Organisation], [Role], [Tool] and [Timescale] value before approval. A blank owner is the most common reason a revocation step stalls.
  • Attach it to your plan: invoke it from the [Organisation] incident response plan. See the Incident Response Plan Template. Phases follow NIST SP 800-61 Rev. 3, the incident response Community Profile of CSF 2.0.
  • Prepare the token map first: sections 4 and 5 assume you can list every npm, PyPI, GitHub and cloud credential present on developer machines and CI runners, with an owner. Build that inventory before the incident.
  • Exercise it: run a tabletop at least yearly using the Shai-Hulud waves of September and November 2025. See the Tabletop Exercise Scenario Pack.

1. Scope and triggers

1.1 Scope. This playbook applies when malicious code in a package from a public or internal registry (npm, PyPI, or [Other registries]) has run, or may have run, on an [Organisation] developer workstation, CI/CD runner, build server or production host, and that code steals credentials or republishes packages.

1.2 Triggers. Invoke this playbook when any of the following occur:

  • A registry, GitHub, CISA or a trusted researcher reports a self-propagating campaign, and [Organisation] lockfiles or artefact caches contain any listed package version.
  • Dependency or malware scanning ([Tool]) flags a package version as malicious rather than vulnerable.
  • A package owned by [Organisation] is published from outside the approved CI workflow, or a version appears that no maintainer recognises.
  • New public repositories appear under [Organisation] or employee GitHub accounts with unfamiliar names, or a new self-hosted runner registers unexpectedly.
  • Install-time processes on a runner or workstation spawn an unexpected runtime, download a binary or contact an exfiltration endpoint.

1.3 Severity. Treat as [Critical] if an [Organisation] maintained package was republished, or if any affected host held publishing tokens or cloud credentials. Treat as [High] if a malicious version was installed anywhere. Treat as [Medium] if it is present only in a cache or lockfile and was never installed.

2. Roles and contacts

RoleResponsibility in this scenarioNamed owner
Incident leadDeclares the incident, sets severity, approves the dependency freeze[Name, role]
Token revocation leadRuns bulk revocation across npm, PyPI, GitHub and cloud, keeps the revocation log[Name, role]
CI/CD platform ownerPauses pipelines, removes rogue runners, rebuilds runner images[Name, role]
Package maintainersConfirm which published versions are genuine, deprecate or unpublish malicious versions, contact the registry[Team list]
Endpoint and SOC analystsHunt on workstations and runners, preserve evidence, isolate hosts[Team]
Communications and legalCustomer and downstream user notices, regulator assessment[Name, role]
External contactsnpm and GitHub support, PyPI security, cloud providers, [National CERT][Contact routes]

3. Detection and triage

3.1 Establish exposure, fast. Within [1 hour], search all lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml, poetry.lock, pinned requirements files), including nested dependencies, and every artefact repository and registry proxy cache, for the reported package names and versions. CISA's Shai-Hulud alert called out both lockfiles and cached copies.

3.2 Establish execution. A version in a lockfile is exposure; a version installed with lifecycle scripts enabled is execution. Use CI logs, EDR process telemetry and package manager caches to identify every host that ran the install, and when.

3.3 Indicators to check.

IndicatorWhere to lookMeaning
preinstall or postinstall script added in a patch releasePackage diff against the prior versionTypical worm entry point
Install step downloading or launching a new runtime (Shai-Hulud's second wave installed Bun)CI logs, EDR process treesPayload execution
New public repositories with campaign names, or credential files committed to themGitHub organisation and user audit logsExfiltration via GitHub (T1567)
Unexpected self-hosted runner registrationGitHub organisation runner settings and audit logPersistence (the second wave registered runners named SHA1HULUD)
Package versions published outside your CIRegistry account activity, package version historyPropagation using stolen tokens
Deletion of home directories or files on hosts that failed authenticationEDR, host logsDestructive fallback (T1485)

3.4 Decide scope of revocation. If execution is confirmed on any host, treat every credential that host could read as stolen (T1552.001 Credentials In Files, T1528 Steal Application Access Token). Do not wait for proof of use.

4. Containment

4.1 Freeze dependency resolution. Within [1 hour] of declaring the incident, [CI/CD platform owner] sets the registry proxy ([Tool]) to block the affected versions and, for the duration, to serve only versions published before [cut-off date]. Pipelines must install from committed lockfiles only (npm ci, hash-checked pip installs). Where the proxy cannot do this, set npm before or min-release-age centrally.

4.2 Disable install scripts on CI. Set ignore-scripts=true in runner npm configuration until eradication is complete, with named exceptions approved by [Incident lead].

4.3 Pause publishing. Suspend all release pipelines for [Organisation] packages. For npm packages, set publishing access to "Require two-factor authentication and disallow tokens", which leaves OIDC trusted publishing as the only automated route.

4.4 Revoke tokens at scale, in this order.

  1. Registry publishing tokens (npm, PyPI, extension marketplaces) for every maintainer and bot on affected hosts. Use npm token list and npm token delete <ID> or the Access Tokens page; npm notes revocation can take up to an hour, so do this first.
  2. GitHub personal access tokens, OAuth and GitHub App tokens, and deploy keys for affected users and bots; remove GitHub Apps and OAuth applications that are not needed, as CISA advised.
  3. Cloud credentials (AWS, Azure, GCP keys and sessions) present on affected hosts or in CI secrets.
  4. CI/CD platform secrets and variables exposed to affected jobs.
  5. Any other secret in affected repositories, .env files and runner environments.

4.5 Isolate hosts. Network-isolate affected workstations through EDR. Stop and remove affected ephemeral runners; take persistent runners offline. Remove any unexpected self-hosted runners from repository and organisation settings.

4.6 Block exfiltration routes named in the advisory (CISA advised blocking webhook.site for Shai-Hulud) at egress proxies and DNS.

5. Eradication

5.1 Remove malicious versions from your estate. Purge them from proxy caches and artefact repositories, regenerate lockfiles from known-good versions and commit them through reviewed pull requests.

5.2 Clean your own packages. For each [Organisation] package republished by the worm, maintainers deprecate or unpublish the malicious versions under registry policy, publish a clean version from CI with trusted publishing, and report to the registry. On PyPI, administrators can quarantine a project, which hides it from the simple index so it cannot be installed while the issue is resolved.

5.3 Remove persistence. Delete rogue runners, review GitHub Actions workflow changes, branch protection changes, webhooks and repository secrets added since [first exposure time], and remove public repositories created by the worm after preserving evidence.

5.4 Rebuild, do not clean. Reimage affected workstations and rebuild runner images from source. A worm that ran with user or runner privileges can have changed anything those privileges reach.

5.5 Re-issue credentials safely. Issue replacement credentials only to rebuilt hosts. Replace publishing tokens with trusted publishing; npm supports it from GitHub Actions, GitLab CI/CD and CircleCI cloud (npm CLI 11.5.1 or later). See the npm Trusted Publishing and Provenance Guide and the PyPI API Tokens and Trusted Publishing Security Guide.

6. Recovery

6.1 Restore pipelines in rings: [internal-only services] first, then [customer-facing builds], then release pipelines.

6.2 Lift the dependency freeze only when the registry and advisory sources report the campaign contained, and keep a release age delay of [N days] afterwards.

6.3 Monitor registry, GitHub and cloud audit logs for use of revoked credentials for [30 days]; any attempt confirms theft and should be added to the incident record.

6.4 Confirm with each maintainer that every published version since [first exposure time] is genuine.

7. Communication and notification

7.1 Internal: tell all developers within [2 hours] which packages are frozen, which tokens were revoked and how to get new credentials. Unexplained revocations cause shadow workarounds.

7.2 Downstream users: if an [Organisation] package was republished, publish an advisory naming affected versions, safe versions and actions, through the repository security advisory, release notes and [Customer channels].

7.3 Registries and peers: report malicious versions to npm or PyPI and share indicators with [ISAC or CERT].

7.4 Regulatory: [Legal] assesses notification duties if stolen credentials gave access to personal data or regulated systems, within [jurisdiction deadlines].

8. Post-incident review

8.1 Hold the review within [10 working days]. Record the timeline from first malicious publish to your freeze, to your first revocation and to your last revocation.

8.2 Answer these questions: which credentials were on the hosts that ran the install, and why; why install scripts ran on CI; how long the most privileged token stayed valid; whether any of your packages were republished.

8.3 Track actions to closure: trusted publishing for every package, removal of long-lived tokens, managed release age delay, runner hardening. See the Tabletop Exercise After Action Report Template for the format.

Implementation guidance

What is different about worms. The Shai-Hulud npm worm shows why speed of revocation decides the outcome: its second wave began on 24 November 2025, most reported infections were on CI/CD runners, and more than 60% of leaked npm tokens were reportedly still valid a week later. npm revoked all classic tokens on 9 December 2025. Plan for revocation in minutes, not days.

PreparationWhy it matters during a wormFramework reference
Inventory of who can publish each package and which tokens existRevocation scope in minutes instead of daysNIST SP 800-53 IR-8; CSF 2.0 RS.MA-01
Registry proxy with block and date cut-off capabilityFreeze resolution without editing every repositoryCSF 2.0 RS.MI-01
Trusted publishing, tokens disallowedNothing on a laptop or runner can republish your packagesNIST SP 800-53 IA-5
ignore-scripts default on CIInstall-time payloads do not runCSF 2.0 RS.MI-02 (prepared in advance)
Ephemeral runners rebuilt from imagesEradication is a redeployCSF 2.0 RC.RP-01
Phishing-resistant MFA on npm, PyPI and GitHubStops account takeover routes; CISA recommended itNIST SP 800-53 IA-5

Metrics. Measure time from public disclosure to dependency freeze, time to revoke the last exposed publishing token, percentage of packages using trusted publishing, and number of long-lived registry tokens in existence. Related reading: the Shai-Hulud npm Worm Guide, the npm Install-Time Security Guide, the Secrets Rotation Runbook Template and the Developer Workstation and IDE Security Guide, which covers extension worms such as GlassWorm that follow the same token-theft pattern.

Standards and references

Related NHI Mgmt Group resources: Supply Chain Compromise Response Playbook · CI/CD Pipeline Compromise Playbook · npm Tokens Security Guide · Software Supply Chain Security Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 27 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.