Confirming a Flagged Dependency Is Compromised or Clean

A specific package version in your dependency tree just got flagged, and you have to decide before you ship or roll back: is this an actual supply-chain compromise, or noise? This guide is for engineers and engineering leads who need to carry one flagged release through a no-execution investigation and reach a verdict they can defend. It follows a real compromise end to end - the actual commands, the intermediate findings, and the wrong turns - so you can run the same path on the suspicious package in front of you.

The job here is narrow on purpose. This is not a library-quality grade or a maintenance audit. It is the security triage of one specific flagged release: publisher history, tarball diff, install-hook inspection, provenance check, verdict. Developers now do this almost weekly, and the failure modes are subtle enough that a written standard beats improvising each time.

Why one flagged release needs its own procedure

A flagged release is a fork in the road with a shipping deadline attached, and the honest answer usually lives in a diff, not in a scanner's badge. The generic advice - "use a scanner," "pin your versions" - does not tell you whether the release on your screen is malicious right now.

The threat model shifted. The dominant 2025-2026 vector is maintainer account takeover through phishing, not a new-account typosquat. On September 8, 2025 a threat actor took control of the npm account of the developer known as Qix through social engineering, then published malicious releases of highly popular packages including debug and chalk. The phishing email came from a domain, npmjs.help, registered just three days earlier. So the account you trust is exactly the account that turns on you, and "is the maintainer new?" is the wrong question.

These are not rare edge cases. Multiple large-scale compromises land per year, each spanning hundreds of packages.

The scale is why you need a procedure that works on any single release, fast, without executing anything. The rest of this guide is that procedure, carried through the keyv and node-ipc cases so you can see what each step actually turns up.

The confirmed waves you are triaging against

Recent supply-chain compromises follow a small number of shapes, and knowing the shape tells you where to look first. Table A lists the confirmed 2025-2026 npm waves from public reporting.

Two cautions before you use these numbers. The download-volume units differ - weekly for some events, monthly for others - so they are not directly summable, and none of them count infected machines. Two billion monthly downloads is combined normal traffic for popular packages, not two billion compromises. When you scope your own exposure, the number that matters is whether you did a fresh install inside the compromise window, not the headline download count.

The shape also predicts the tell. The debug/chalk and keyv waves were trusted maintainers with hijacked accounts, so the publisher-history signal is a simultaneous multi-package publish burst. The Shai-Hulud waves were worms, and Shai-Hulud 2.0 moved execution to preinstall, which widened the blast radius across developer machines and CI pipelines. That single detail matters for your inspection: blocking postinstall alone is not enough.

Fetch and inspect without executing anything

The first rule of triage: get the published files onto disk without running a single line of them. For npm, npm pack <pkg>@<version> downloads the tarball without installing it, so you can extract and read the published files - which, importantly, can differ from the GitHub repo.

Extract the tarball with tar in a scratch directory and read package.json plus any bundled files. If you must run a command that installs, the npm CLI has an --ignore-scripts flag that prevents execution of any lifecycle hooks defined in package.json, and it works with npm install, npm ci, and npm update. But treat --ignore-scripts as a seatbelt, not a sandbox: installs can run arbitrary executables through git dependencies, so it is not hermetic. During triage, do not install at all. npm pack and read.

For PyPI, pip download --no-deps performs the same resolution and download as pip install but collects the distributions into a directory instead of installing them. One wrinkle: pip download --no-deps --no-binary :all: can still install build dependencies when resolving an sdist, so prefer wheels or a fully isolated scratch environment.

Capture the tarball and its hashes the moment you have them. Registry cleanup races your investigation: in the keyv case Snyk found eight malicious releases still tagged latest while three had already been removed. Your npm pack evidence can vanish mid-triage, so save it locally before anything else.

Reading the publisher's history

The load-bearing account signal is not "new maintainer" but "trusted maintainer, abnormal simultaneous multi-package publish." List every version of the flagged package and every package that maintainer owns, then look for a burst of near-simultaneous releases across their whole portfolio.

This is exactly how the keyv wave was mapped. Snyk enumerated every package returned by npm for the maintainer jaredwray and identified 11 malicious releases carrying the same two payload files. A single account, a single publishing session, a coordinated fan-out - that pattern is the signature of an account takeover, and it is far more reliable than account age.

The reason it works is mechanical. An attacker who phishes one account publishes everything at once, so timestamps cluster and payloads repeat. Which brings us to the strongest single tell.

Byte-identical payloads across releases catch a staged campaign faster than reading a single line of obfuscated code.

In the node-ipc case, the compromised node-ipc.cjs file was byte-for-byte identical across all three malicious versions, confirming a single staging operation. One obfuscated bundle dropped into several package contexts before a simultaneous publish produces identical hashes. So when you inspect the maintainer's portfolio, hash the suspicious files across releases. Matching hashes across supposedly independent versions is a near-conclusive tell of a staged campaign.

Inspecting the manifest and the changed files

Read the manifest for install hooks and the file list for one oversized obfuscated bundle. These two signals together account for most of what recent compromises look like on disk.

Grep the extracted package.json for preinstall and postinstall. Recent campaigns increasingly favor preinstall: Shai-Hulud 2.0 spreads under filenames math_init.js and Math_Symbol.js, using a preinstall script to execute during install time. The move to preinstall is what widened the CI blast radius, because the payload runs earlier in the install lifecycle.

Then look at file sizes. A malicious payload is usually one large obfuscated single-file bundle that stands out against the rest of the package. In node-ipc, the diff between the last clean release and the compromised version was a single line addition of 80,079 characters. You do not need to read that line to know it does not belong.

Now diff against your last known-good. npm ships a first-party command: npm diff --diff=pkg@good --diff=pkg@flagged prints diff patches of the files published to the registry. Add --diff-name-only to list only the changed files first, then open the ones that matter. Diff the tarballs, never the GitHub repo, because a prepublishOnly step can produce a registry artifact that differs from the source.

At this point in a real triage you can usually point to the exact added lines. That is your verdict evidence. Everything after this either corroborates it or complicates it.

Here is where the concentration of people who can run this well becomes a planning problem. In Refolk's index of professional profiles, the United States has 1,109 Application and Product Security engineers against 49 in Germany - a 22.6x gap once you divide the counts.

Non-US teams are far likelier to lack an in-house triager and to depend on a written standard like this one. If you need to build that bench, describing the specific work is the fastest way to find people who have actually done it.

Provenance and attestation: what it proves and what it does not

Provenance verifies where a package was built, not whether the source that entered the build was safe. Run the check, but read the result correctly.

Verify the provenance attestations of downloaded packages with npm audit signatures. The command fetches the signature data for each package version in the tree, validates the registry signatures against the current and historical npm public keys, and validates any provenance attestations against the sigstore certificate transparency log. To check a single package, run npm view package-name --json | jq '.dist.attestations'. If you prefer, cosign v2.4.0 verifies attestations in the bundle format used by npm provenance, GitHub Artifact Attestations, and Homebrew provenance.

Now the limitation you must not overstate. The npm signature is the registry's signature, not the publisher's, and a compromise of an individual package's publish credentials would still produce a signature that verifies cleanly. This is not theoretical. Attackers used the legitimate GitHub Actions release process to publish poisoned keyv 6.0.0, so it carried valid provenance information on npm. The signature verified where the package was built, but not whether the source code entering that process was safe.

That is why the ordering in this guide puts the diff before the provenance check. Some sources run provenance first, but because provenance can verify on a poisoned build, a green result read as "clean" is a false positive waiting to happen. Provenance is corroboration; the diff is proof.

The procedure

Run these eight steps in order on the single flagged release. The first seven are a triager's job and take about an hour total; the last is an engineering lead's job and takes hours if the verdict is "compromised."

Keep a copy-pasteable command block next to the procedure so you are not reconstructing flags under pressure.

mkdir triage && cd triage
npm pack pkg@FLAGGED            # download tarball, run nothing
tar -xzf pkg-FLAGGED.tgz        # extract to ./package
grep -E "preinstall|postinstall" package/package.json
find package -type f -size +50k # flag oversized bundles
npm view pkg versions --json    # publisher history / version list
npm diff --diff=pkg@GOOD --diff=pkg@FLAGGED --diff-name-only
npm diff --diff=pkg@GOOD --diff=pkg@FLAGGED   # read the changed files
npm audit signatures            # corroboration only, not proof
npm view pkg --json | jq '.dist.attestations'
sha256sum package/<suspicious-file>   # hash for cross-release comparison

How this goes wrong

Most bad verdicts come from a small set of predictable mistakes. Each one below has a real-world false positive or false negative and a specific check that defeats it.

• Reading a provenance pass as "clean." keyv 6.0.0 verified because it was built by the real GitHub Actions workflow. Check: diff the source; do not stop at a green npm audit signatures.
• Assuming --ignore-scripts is hermetic. A git dependency can still run a system binary. Check: do not install git deps during triage; inspect the tarball only.
• Trusting the "new maintainer" heuristic. The 2025-2026 events were trusted maintainers with hijacked accounts. Check: look for simultaneous multi-package publish bursts, not account age.
• Diffing the GitHub repo instead of the tarball. A prepublishOnly step can make the registry tarball differ from the repo. Check: always npm pack the published artifact and diff that.
• "Upgrade to newest" as remediation. No clean successor may exist; there was none after poisoned keyv 6.0.0. Check: confirm the target version predates the compromise window before pinning.
• Reading download volume as infections. Two billion monthly downloads is combined normal traffic, not compromised machines. Check: scope to your install window and lockfile timestamps.
• Treating pip download as inert. It can trigger build steps for sdists. Check: use wheels or a fully isolated scratch environment.

The two that catch experienced engineers most often are the provenance false positive and the repo-versus-tarball trap. Both let a compromised release read as clean, which is the expensive direction to be wrong in. If you internalize only two habits from this guide, make them: diff the tarball, and never let a green attestation end the investigation.

Remediating once the verdict is "compromised"

The documented order is pin or revert first, then rotate, then hunt. Do them in that sequence, because rotating credentials while a compromised version can still resolve leaves you re-exposed on the next install.

First, pin or downgrade to a last-known-good release. Confirm that the target version predates the compromise window - do not reach for "newest," because a clean successor may not exist yet, as with keyv 6.0.0.

Then, following Singapore's CSA advisory, treat affected systems as potentially compromised and rebuild them if the malicious packages were installed. Rotate exposed credentials, including cloud credentials, GitHub tokens, SSH keys, Kubernetes configurations, and Terraform credentials. Review cloud and source-code environments for unauthorized access following the package installation.

Before you assume the worst, scope your actual exposure. From the debug/chalk case: most apps were only at risk if they performed a fresh install during the compromise window, if the lockfile was created during that window, and if a compromised package was included directly or transitively. Check your lockfile timestamps against the known compromise window. If you did not install fresh during that window, your blast radius is far smaller than the headlines imply.

Finally, close out the job with a verification pass before you call it done.

Keeping this current

The mechanics of this triage are stable, but the ecosystem's defaults are moving in your favor, so re-check two things periodically. npm v12 shipped with dependency lifecycle scripts off by default, and npm began scanning newly published packages for malware - though that scan applies to new publishes only, not the existing back catalog. Neither replaces the procedure; both shrink the window in which a fresh compromise reaches you.

Do not read the tooling improvements as a reason to skip the diff. The load-bearing evidence is still the changed files in the published tarball, and the reusable tells - simultaneous multi-package bursts and byte-identical payloads across releases - will outlast any specific CLI flag. When a new wave lands, confirm the vector, capture the tarballs before cleanup races you, and run the eight steps. The verdict is only as defensible as the evidence you saved to produce it.