Skip to content

npm publish-time malware scanning and dual-use declarations

Summary

GitHub announced on July 28, 2026 that newly published npm packages are automatically scanned before they become installable. Based on the result, npm can publish a package normally, hold it for manual review, or block it. GitHub also introduced package.json metadata and disclosure requirements for legitimate dual-use packages whose security-relevant behavior can resemble malware.

This is a registry-side prevention layer that can disrupt package waves before first install. It does not replace staged publishing, trusted publishing, package cooldowns, explicit install trust, endpoint telemetry, or incident response for packages and versions that evade detection.

Tags

What changed

  • npm scans newly published packages before making them available for installation.
  • A package can be released, held for manual review, or blocked. GitHub describes a typical availability delay of about five minutes, potentially 15 minutes or longer at peak times or for some package content and sizes; this is not a service guarantee.
  • While scanning is pending, npm dist-tag remains available. Operations that depend on the published version, including npm deprecate and npm unpublish, do not work until the version becomes available.
  • Publishers of blocked packages may receive an appeal path. GitHub notes that severe or high-confidence findings can also trigger action against associated maintainer accounts.
  • Legitimate packages with security-relevant dual-use behavior must declare a contentPolicy field in package.json and place a text-only DISCLOSURE file at the package root describing the functionality and intended legitimate use.
  • Declaring dual-use behavior can trigger additional scanning and does not guarantee publication.
  • Dual-use packages must use a publishing path that enforces 2FA: trusted publishing (OIDC), an interactive 2FA session, or staged publishing. Direct, unstaged publication with a token that bypasses 2FA is not allowed.
  • Once published, the dual-use declaration is persistent. Later versions cannot remove contentPolicy or DISCLOSURE; GitHub says rejection of declaration removal will be progressively enforced.

Operational impact

Publishers

  • Change release automation that assumes immediate installability after npm publish; poll for availability with bounded retries rather than treating the expected scan delay as a failed publish.
  • Do not attempt deprecation or unpublishing until the version is available.
  • For legitimate dual-use packages, review the current npm policy and add accurate contentPolicy metadata plus a narrowly written text DISCLOSURE file before enforcement blocks publication.
  • Prefer trusted publishing or staged publishing over long-lived publication tokens. Treat any automation that still relies on bypass-2FA tokens as migration debt.
  • Preserve scan notifications and appeal records during a false-positive review; do not weaken package behavior or hide security-relevant functionality merely to evade scanners.

Consumers and defenders

  • Treat publish-time scanning as one prevention signal, not proof that an available package is benign. Mutable external payloads, delayed activation, import-time behavior, cross-package composition, compromised legitimate versions, and environment-gated logic can evade static or pre-publication analysis.
  • Continue package cooldowns and internal-registry quarantine even though npm introduces a pre-availability delay. Minutes of scanning are not equivalent to days of ecosystem observation.
  • Keep lifecycle scripts, Git dependencies, and remote URL dependencies fail-closed unless explicitly approved. Continue monitoring import-time and runtime execution.
  • An npm block or maintainer-account action is an incident-response trigger: preserve package archives and release logs, scope previous versions and downstream artifacts, and rotate credentials if publisher or CI compromise is plausible.
  • Do not allow contentPolicy or DISCLOSURE to become an automatic enterprise allowlist. The declaration is context for Trust & Safety review, not a safety attestation.

Detection and governance pivots

  • Alert on release pipelines that repeatedly retry publish, alter dist-tags, or fail because downstream checks assume immediate package availability.
  • Inventory packages with contentPolicy and review changes to their dual-use capabilities, disclosure text, publisher identities, provenance, and release workflows.
  • Alert if a package that previously declared dual-use behavior attempts to remove or materially minimize its declaration.
  • Correlate npm blocks or holds with GitHub Actions workflow changes, maintainer email or 2FA recovery events, trusted-publisher changes, and unexpected package-source differences.
  • Keep internal quarantine and malware matching across npm, PyPI, and source dependencies; npm's control only covers npm publication.

Limits and attacker adaptation

Expected adaptations include spreading behavior across multiple apparently benign packages, moving payloads to mutable GitHub or cloud-hosted configuration, using import-time or runtime execution, environment-gating malicious branches, poisoning already trusted packages, and adding misleading dual-use disclosures. Detection should model the dependency and execution graph rather than score each package archive in isolation.

Sources