npm Publish Pipeline Security Audit Guide

An npm publish pipeline security audit verifies who can release a package, which source and workflow produced it, what enters the tarball, how credentials are constrained, and how the team responds when a version is delayed or blocked. Publishing is a production deployment: consumers may install the artifact within minutes and inherit every included file and lifecycle behavior.

In July 2026, npm announced automatic malware scanning before newly published packages become installable. A version can proceed, wait for manual review, or be blocked. Release automation that assumes immediate availability must now tolerate a scanning window.

Inventory every publishing path

Teams often secure the primary release workflow while a maintainer laptop, legacy token, scheduled job, or old repository can still publish. Start with the registry account and work backward to every authorized path.

Record:

• Package names, scopes, ownership, and maintainer accounts.

• Repositories and branches allowed to initiate release.

• CI workflows, reusable actions, and third-party release tools.

• Trusted-publisher configurations and identity claims.

• Granular tokens, classic credentials, and local login sessions.

• Two-factor requirements and recovery methods.

• Staging, promotion, deprecation, and emergency procedures.

• Webhooks or downstream jobs triggered by a new version.

Remove access only after confirming the exact identity and recovery owner. An unexplained token may be dangerous, but deleting it during an active release can create a separate incident.

Verify artifact provenance

The audit should demonstrate that the tarball comes from the reviewed commit and approved workflow. Rebuilding on a maintainer machine after checks pass breaks that chain even if the source tree looks identical.

Check that the pipeline:

1. Uses an immutable commit or signed release reference.

2. Runs in a protected environment with reviewed workflow changes.

3. Installs dependencies from a locked and controlled source.

4. Executes required tests before packaging.

5. Inspects the actual tarball contents.

6. Records package name, version, digest, source commit, and workflow run.

7. Publishes through short-lived identity where supported.

8. Preserves evidence needed to investigate a disputed release.

Generate a dry-run tarball and compare it with the publish artifact. .npmignore, files, build scripts, and workspace layout can include secrets, test fixtures, internal documentation, or unexpected binaries.

Adapt automation to the scan window

npm says availability may usually take a few minutes and can take longer depending on load and package characteristics. Do not treat a temporary “not found” immediately after publish as failure and republish the same version.

Update the workflow to:

• Poll registry availability with bounded backoff.

• Distinguish pending scan, blocked publish, network failure, and version conflict.

• Delay dependent release jobs until the exact version can be installed.

• Verify the downloaded digest before downstream promotion.

• Alert an owner when the expected window is exceeded.

• Prevent duplicate attempts with the same immutable version.

• Preserve logs without exposing registry credentials.

• Provide a manual stop before a wider release proceeds.

Test consumers against the registry artifact, not only the local package directory.

Decide whether staged publishing fits the risk

npm's staged publishing and install-time controls announcement describes a queue where CI can upload a prepared tarball and a maintainer approves promotion with two-factor authentication. Staging adds a human proof-of-presence step between build and public availability.

It is especially useful for:

• Widely used public packages.

• Security-sensitive libraries and tooling.

• Releases generated by broad automation.

• Teams separating build authority from release approval.

• Packages where a mistaken version creates costly consumer impact.

Define who can approve, how the tarball is reviewed, how long staged artifacts remain valid, and how emergency releases work. A human click without meaningful artifact evidence is ceremony rather than control.

Handle dual-use packages explicitly

Packages with security-relevant capabilities may resemble malicious behavior to automated scanning. npm introduced a contentPolicy declaration and a text-only DISCLOSURE file for dual-use content, with stronger publishing requirements.

The audit should identify whether package functionality includes credential access, remote execution, network scanning, persistence, obfuscation, or other behavior likely to require explanation. Domain and legal owners should review the declaration; developers should not invent a vague statement solely to pass a scanner.

Verify:

• The declaration accurately describes legitimate use.

• The disclosure matches shipped behavior.

• Required metadata persists in later versions.

• Publishing uses an allowed two-factor-enforced method.

• Maintainers know the appeal and incident process.

• Documentation warns users about sensitive capabilities.

Reduce credential and workflow exposure

Prefer trusted publishing with workload identity over stored long-lived registry tokens. Restrict workflow permissions, pin or verify third-party actions, protect release environments, and require review for pipeline changes.

Audit workflow inputs for command injection and untrusted branch or tag names. A secure registry credential cannot compensate for a release script that executes attacker-controlled text.

Use the AI incident response guide to connect publishing controls with repository and recovery governance. The Agent Plugins implementation guide adds review questions when agent-created packages or automation are involved.

Build an emergency response plan

Prepare for a leaked token, compromised maintainer, incorrect artifact, malicious dependency, blocked package, or accidental sensitive-file publication. The response differs by event, so record specific first actions.

The runbook should cover:

• Freeze and revoke publishing authority.

• Preserve workflow, registry, and account evidence.

• Identify affected versions and consumers.

• Coordinate deprecation, advisory, replacement, or removal options.

• Rotate secrets exposed inside the artifact.

• Communicate verified facts and safe upgrade instructions.

• Review related packages and automation paths.

• Add a regression control before restoring publication.

Do not assume unpublishing removes every copy. Consumers, proxies, mirrors, and build caches may retain the version.

What the audit should deliver

Expect an access inventory, provenance map, workflow threat model, tarball review, credential findings, scan-window changes, staged-publishing recommendation, dual-use assessment, incident runbook, and prioritized remediation plan.

Each finding should name evidence, plausible impact, owner, and verification method. Generic warnings about supply chains do not help a maintainer decide what to change.

Frequently asked questions

Does registry scanning replace our own checks?

No. Registry scanning is another layer. Your team still owns source review, dependency controls, secret detection, tests, artifact inspection, identity, and incident response.

Should every package use staged publishing?

Not automatically. Match the extra approval step to package reach, capability, maintainer model, and release frequency. Document the decision either way.

What is the highest-value first improvement?

For many teams, replacing stored publish tokens with controlled workload identity and verifying the final tarball materially reduces both credential and artifact risk.

Explore Voquarn's software security services or request a publishing-pipeline assessment for an evidence-based review.