npm publish-time malware scanning and dual-use metadata - GitHub Changelog

Try GitHub Copilot CLI

Attend GitHub Universe

Search

Back to changelog

As part of our ongoing supply-chain security work, npm is introducing automatic scanning of packages at publish time . This changelog covers what publishers can expect and a new metadata requirement for dual-use content.

Packages are scanned before they become available

Newly published packages will be automatically scanned before they become available for install. Depending on the results, a package may be published as normal, held for manual review, or blocked.

This introduces a short delay between publishing and availability, typically around five minutes. It may take longer, up to 15 minutes or more, at peak times or depending on a package’s content and size. These times reflect current typical behavior and may change as scanning evolves; they aren’t a service guarantee.

For most publishes, no action is required beyond allowing for this brief delay. If you have automation that assumes a package is installable immediately after publishing, update it to tolerate a short availability delay.

While scanning is pending, the npm dist-tag command continues to work. Other operations that depend on the published version, such as npm deprecate and npm unpublish, will not work until the package becomes available.

Blocked packages and appeals

If a package is blocked, the publisher may receive a notification with the option to appeal. Depending on the severity and confidence of a finding, further action may be taken on the associated maintainer account(s), consistent with our existing policies.

npm blocks the malware we can detect and we are continuously working to improve detection coverage and reduce scan time. For what is and isn’t permitted on the registry, see the npm Acceptable Use Policies.

New metadata requirement for dual-use content

Some legitimate packages have security-relevant capabilities that can resemble malware to automated scanning (dual-use content). We are introducing a contentPolicy field in package.json for maintainers to declare this content.

Maintainers declaring dual-use content must also include a DISCLOSURE file in the package’s root directory, containing only text content. This file is free-form and should describe both the dual-use functionality and its intended legitimate use. Our Trust & Safety team uses it when reviewing dual-use packages.

Declaring this metadata may trigger additional automated scanning suited to dual-use content when needed. It does not automatically grant publication, and our Trust & Safety team may review dual-use packages on a case-by-case basis.

Publishing requirements for dual-use packages

2FA-enforced publishing: Packages declaring dual-use content must be published through a method that enforces two-factor authentication (e.g., trusted publishing (OIDC), an interactive session with two-factor authentication, or staged publishing). Staged publishing is 2FA-enforced through its staging and promotion step, so granular access tokens with bypass-2FA may still be used to publish to staging . Publishing a dual-use package directly (unstaged) with a token that bypasses two-factor authentication is not permitted.

Persistent declaration: Once a package is published with dual-use metadata, the declaration must persist. New versions cannot remove the contentPolicy field or the DISCLOSURE file; publishes that drop them will be rejected.

This requirement will be progressively enforced over time. We are reaching out directly by email to maintainers of dual-use packages that need to add this metadata to avoid being blocked by default.

For more information, see our docs about dual-use content policy.

Follow along and ask questions in the community discussion.

Related Posts

Jul.28 Improvement

Dependabot alerts on malicious packages across more ecosystems

supply chain security

Jul.28 Improvement

GitHub Actions holds potentially malicious workflows for approval

actions<br>supply chain security

...<br>+1

Jul.14 Improvement

Dependabot version updates introduce default package cooldown

supply chain security

Jul.08 Release

Innersource security advisories are generally available

supply chain security

Jul.08 Retired

npm install-time security and GAT bypass2fa deprecation

supply chain security

Jun.30 Release

Open source license compliance is in public preview

supply chain security

Jun.30 Improvement

Dependabot no longer infers .npmrc

supply chain security

Jun.30 Improvement

Upcoming cloud data retention policy for closed security alerts

application security<br>supply chain security

...<br>+1

Jun.26 Improvement

Read-only Actions cache for untrusted triggers

actions<br>supply chain security

...<br>+1

Subscribe to our developer newsletter

Discover tips, technical guides, and best practices in our biweekly newsletter just for devs.

Enter your email*

Subscribe

By submitting, I agree...