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
| Role | Responsibility in this scenario | Named owner |
|---|---|---|
| Incident lead | Declares the incident, sets severity, approves the dependency freeze | [Name, role] |
| Token revocation lead | Runs bulk revocation across npm, PyPI, GitHub and cloud, keeps the revocation log | [Name, role] |
| CI/CD platform owner | Pauses pipelines, removes rogue runners, rebuilds runner images | [Name, role] |
| Package maintainers | Confirm which published versions are genuine, deprecate or unpublish malicious versions, contact the registry | [Team list] |
| Endpoint and SOC analysts | Hunt on workstations and runners, preserve evidence, isolate hosts | [Team] |
| Communications and legal | Customer and downstream user notices, regulator assessment | [Name, role] |
| External contacts | npm 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.
| Indicator | Where to look | Meaning |
|---|---|---|
preinstall or postinstall script added in a patch release | Package diff against the prior version | Typical worm entry point |
| Install step downloading or launching a new runtime (Shai-Hulud's second wave installed Bun) | CI logs, EDR process trees | Payload execution |
| New public repositories with campaign names, or credential files committed to them | GitHub organisation and user audit logs | Exfiltration via GitHub (T1567) |
| Unexpected self-hosted runner registration | GitHub organisation runner settings and audit log | Persistence (the second wave registered runners named SHA1HULUD) |
| Package versions published outside your CI | Registry account activity, package version history | Propagation using stolen tokens |
| Deletion of home directories or files on hosts that failed authentication | EDR, host logs | Destructive 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.
- Registry publishing tokens (npm, PyPI, extension marketplaces) for every maintainer and bot on affected hosts. Use
npm token listandnpm token delete <ID>or the Access Tokens page; npm notes revocation can take up to an hour, so do this first. - 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.
- Cloud credentials (AWS, Azure, GCP keys and sessions) present on affected hosts or in CI secrets.
- CI/CD platform secrets and variables exposed to affected jobs.
- Any other secret in affected repositories,
.envfiles 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.
| Preparation | Why it matters during a worm | Framework reference |
|---|---|---|
| Inventory of who can publish each package and which tokens exist | Revocation scope in minutes instead of days | NIST SP 800-53 IR-8; CSF 2.0 RS.MA-01 |
| Registry proxy with block and date cut-off capability | Freeze resolution without editing every repository | CSF 2.0 RS.MI-01 |
| Trusted publishing, tokens disallowed | Nothing on a laptop or runner can republish your packages | NIST SP 800-53 IA-5 |
ignore-scripts default on CI | Install-time payloads do not run | CSF 2.0 RS.MI-02 (prepared in advance) |
| Ephemeral runners rebuilt from images | Eradication is a redeploy | CSF 2.0 RC.RP-01 |
| Phishing-resistant MFA on npm, PyPI and GitHub | Stops account takeover routes; CISA recommended it | NIST 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
- CISA: Widespread Supply Chain Compromise Impacting npm Ecosystem
- NIST: SP 800-61 Rev. 3 Incident Response Recommendations
- npm: Trusted Publishing for npm Packages
- npm: Revoking Access Tokens
- GitHub: Our Plan for a More Secure npm Supply Chain
- PyPI: Project Quarantine
- MITRE ATT&CK: Compromise Software Dependencies and Development Tools (T1195.001)
Related NHI Mgmt Group resources: Supply Chain Compromise Response Playbook · CI/CD Pipeline Compromise Playbook · npm Tokens Security Guide · Software Supply Chain Security Guide