Investigate a suspected malicious package safely

A suspicious package should first be treated as untrusted bytes. Installation can execute lifecycle hooks before an application imports the package, so reproducing an ordinary install on an analyst's workstation can create a new incident. Collect immutable package identity, source registry, archive digest, lockfile changes, publication timing and the relevant build runs. Compare the archive and metadata using a non-executing inspection path, such as the commands below. A repository tag is supporting context, not proof that registry bytes match it.

The fictional log-helper update adds a postinstall hook that reads an environment variable and writes a network request description. The fixture is a static transcript, not a runnable malicious package. The new hook is causally important because three CI builds installed it with credentials present. A minified file or a recently created maintainer account can be a clue, but neither alone proves malicious intent. Preserve evidence and separate confirmed behavior, plausible exposure and unanswered questions.

The npm CLI can answer the first questions without executing anything. npm view shows the declared scripts, the registry integrity hash and the publication time, npm diff lists files that changed between the approved and suspect versions, and npm pack with --ignore-scripts downloads the tarball so its manifest can be read with tar. Run the script below in a disposable directory that holds no credentials. The integrity value it prints is the same SHA-512 hash recorded in package-lock.json, so it also finds every lockfile and build log that pulled the suspect bytes.

#!/usr/bin/env bash
# Inspect a suspect npm version without installing it or running its scripts.
# Usage: ./inspect-package.sh log-helper 1.4.0 1.4.1
set -euo pipefail
pkg=$1 old=$2 new=$3

npm view "$pkg@$new" scripts dist.integrity dist.tarball --json
# npm 12 wraps view results in an array; npm 11 does not.
npm view "$pkg" time --json \
  | jq -r --arg v "$new" '(if type == "array" then .[0] else . end) | "published: " + .[$v]'
npm diff --diff="$pkg@$old" --diff="$pkg@$new" --diff-name-only

# Download the tarball only, then read its manifest from the archive. npm 11 prints
# an array and npm 12 an object keyed by name; first(.[]) reads either.
packed=$(npm pack "$pkg@$new" --ignore-scripts --json)
jq -r 'first(.[]) | .filename, .integrity' <<<"$packed"
tar -xOzf "$(jq -r 'first(.[]) | .filename' <<<"$packed")" package/package.json | jq '.scripts // {}'

Containment has two parts: prevent further installations or execution, and reduce what any already executed code can still do. Pinning the prior version stops a future resolver choice but does not revoke a credential copied during an earlier run. Remove suspect artifacts from promotion, isolate affected workers and review the secret/identity scope available in those runs. Rotate or revoke credentials when the evidence supports exposure, using the organization's incident process and recording the sequence so logs remain interpretable.

For this exercise, run B1 had token T with repository-write authority, B2 had no long-lived token but could request release identity, and B3 had no secret or publishing identity. B2's short-lived identity reduces persistence of the credential, but actions performed while it was valid may outlive it. Review publishing and deployment events as well as token expiry. B3 still produced untrusted build outputs; absence of credentials does not automatically rehabilitate those bytes. Containment may delay releases, so name the affected products and a safe rebuilding path.

OpenSSF Package Analysis illustrates automated observation of package behavior, but a sandbox result is only as complete as its instrumentation and trigger conditions. A package can act differently by environment, time or network response. Begin with static deltas: package scripts, newly included files, dependency changes and encoded payloads. If dynamic analysis is needed, use a disposable isolated environment with synthetic data, no real credentials, controlled network behavior and recorded tool configuration. Do not reconnect that environment to trusted build infrastructure afterward.

The strongest initial question here is narrower than prove the package is malicious: did the changed install path execute in a credential-bearing build? The run transcript answers yes for B1/B2. Network records show one outbound connection from B1 but not its content. That supports suspected token exposure without proving what was transmitted. Preserve raw logs, archive hash and a timeline; do not replace them with a scanner verdict. A negative sandbox result cannot erase the confirmed lifecycle execution in production CI.

Recovery requires a reviewed dependency choice, clean worker state, new credentials where needed and fresh outputs from that path. Reusing a cached executable or promoting an old affected build bypasses the repair. Verify the exact restored package digest, absence of the unauthorized hook, updated lockfile integrity and resulting release evidence. Investigate unauthorized publication and access during the exposure window; revocation prevents future use but cannot undo actions already performed.

Supply-chain risk guidance from NIST emphasizes managing supplier and product risk over the lifecycle. The operational record here connects that principle to a specific event: original observation, affected runs, accessible authority, actions taken, evidence locations, accountable owner and criteria for reopening releases. Mark facts and hypotheses separately. A reliable incident update can say three outputs quarantined and token T requires revocation while also saying exfiltration is unproven. That precision helps the response team act without overstating what the evidence establishes.

Response to a package compromise depends on how the code got in, because the controls that stop a repeat differ. In September 2025 the Shai-Hulud worm (/domains/supply-chain/dependencies/case-study-shai-hulud/) harvested npm, GitHub and cloud credentials from developer machines and CI runners and republished other packages with the stolen npm tokens; CISA reported more than 500 compromised packages. Its second wave, reported on 2025-11-24, ran from a preinstall hook, so it executed before installation finished. A month earlier, malicious nx releases published with a token stolen through a GitHub Actions injection ran a postinstall credential stealer. Two older npm incidents show the two takeover routes, a maintainer handover and an account hijack: /domains/supply-chain/dependencies/case-study-event-stream/.

Commit the install policy so that every developer machine and CI job uses it. On npm 12, dependency install scripts stay blocked until npm install-scripts approve <pkg> records the package, pinned to its reviewed version, in the allowScripts field of package.json; npm rebuild then runs the approved scripts. min-release-age makes npm pick the newest version that is at least that many days old, so a compromised release that is detected and pulled within that window never reaches your builds. Dependabot applies a 3-day cooldown to version updates by default since 2026-07-14 and still opens security updates immediately. /domains/supply-chain/ci-cd/developer-workstation-security/ applies the same settings to developer machines, along with editor extensions and AI agents.

Dependency confusion is a resolution problem, covered per ecosystem in /domains/supply-chain/dependencies/dependency-confusion/. With --extra-index-url, pip treats every index as equal and installs the highest version it finds, so a public package can replace a private one with the same name. Point pip at one index that proxies the public one, or use uv, whose default first-index strategy stops at the first index that has the name. For npm, publish private packages under a scope you also own on npmjs.com and map that scope to the internal registry, as in the file below.

; Resolve the internal scope only from the internal registry.
@acme:registry=https://npm.acme.example/
; Skip versions published less than 3 days ago (npm 11.10 or later).
min-release-age=3
; Refuse git and remote tarball dependencies (the npm 12 defaults).
allow-git=none
allow-remote=none
; npm 11 only: ignore-scripts=true
; npm 12 blocks dependency install scripts unless package.json allowScripts approves them.

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. OpenSSF Package Analysis
2. GitHub Actions secure use reference
3. NIST SP 800-161 Rev. 1, updated: supply-chain risk management. May 2022, updated 1 November 2024.
4. CISA: widespread supply chain compromise impacting the npm ecosystem (2025-09-23)
5. npm Docs: npm ci. npm v11.
6. npm Docs: npm diff. npm v11.
7. npm Docs: npm install-scripts. npm v12.
8. npm Docs: config. npm v11.
9. npm CLI changelog
10. pnpm settings: dependency resolution
11. pnpm settings: build
12. Yarn configuration: .yarnrc.yml
13. pip install documentation. pip 26.2.1.
14. uv settings reference
15. NuGet package source mapping

Reference information

Tags

Dependency managementSupply chain attacksIncident response

SDLC phase

DevelopmentMaintenance

Role

Platform engineers and SREs

ASVS 5.0.0 requirements

v5.0.0-15.2.4

CAPEC attack patterns

• CAPEC-538 at MITRE

Download this guide as Markdown

Continue exploring