Full Report
GitHub has rolled out new controls for npm to improve the security of the software supply chain, giving maintainers the ability to explicitly approve a release prior to the packages becoming publicly available for installation. Called staged publishing, the feature is now generally available on npm. It mandates that a human maintainer pass a two-factor authentication (2FA) challenge to approve
Analysis Summary
# Best Practices: npm Supply Chain Security
## Overview
These practices address the rising threat of software supply chain attacks, specifically targeting the injection of malicious code into popular open-source packages. They introduce "proof of presence" requirements to ensure that even automated CI/CD deployments undergo human validation via Two-Factor Authentication (2FA) before public release.
## Key Recommendations
### Immediate Actions
1. **Update npm CLI:** Upgrade all developer environments and CI/CD runners to **npm CLI 11.15.0** or newer to support staged publishing and new install flags.
2. **Enable 2FA:** Enforce Two-Factor Authentication for all npm maintainer accounts; this is a hard prerequisite for utilizing new security gates.
3. **Restrict Local Installs:** In development scripts, append `--allow-file=false`, `--allow-remote=false`, and `--allow-directory=false` to prevent the accidental installation of unverified local or remote tarballs.
### Short-term Improvements (1-3 months)
1. **Implement Staged Publishing:** Transition package release workflows to use `npm stage publish`. This adds a human-in-the-loop requirement for packages deployed via CI/CD.
2. **Migrate to Trusted Publishing:** Configure **OpenID Connect (OIDC)** between your CI/CD provider (e.g., GitHub Actions) and npm to eliminate the need for long-lived, reusable npm tokens.
3. **Audit Dependencies:** Review current package installation sources and replace any git-based or remote URL dependencies with versioned registry packages where possible.
### Long-term Strategy (3+ months)
1. **Zero-Trust Install Policy:** Standardize on an "explicit-allowlist" approach for all projects, ensuring that no non-registry sources (local files, git, or remote URLs) are permitted without documented exceptions.
2. **Supply Chain Integrity Automation:** Integrate OIDC and Staged Publishing into the standard organization-wide "Golden Path" for all internal and public-facing software releases.
## Implementation Guidance
### For Small Organizations
- Focus on enabling 2FA for all maintainers immediately. Use `npm stage publish` manually for critical releases to ensure an extra layer of protection against account takeover.
### For Medium Organizations
- Standardize the npm CLI version across the engineering team. Implement OIDC (Trusted Publishing) to remove static secrets from your CI/CD environment variables.
### For Large Enterprises
- Enforce the new `--allow-*` flags through internal linting or security wrapper scripts. Mandate staged publishing for all public-facing open-source components managed by the company to prevent "poisoned" updates from compromised CI pipelines.
## Configuration Examples
### Using Staged Publishing
To submit a package to the staging queue rather than publishing it immediately:
bash
# Must be run from the package root directory
npm stage publish
*Note: A maintainer must then log into the npm web portal and pass a 2FA challenge to approve the release.*
### Restricted Installation Flags
To ensure a project only installs packages from the official npm registry:
bash
npm install --allow-file=false --allow-remote=false --allow-directory=false --allow-git=false
## Compliance Alignment
- **NIST SSDF (Software Supply Chain Security):** Aligns with requirements for verifying the integrity of software releases and controlling third-party components.
- **CIS Controls:** Supports "Data Recovery" and "Inventory and Control of Software Assets" by restricting where software can be sourced.
- **SLSA (Supply-chain Levels for Software Artifacts):** New staged publishing helps move organizations toward higher SLSA levels by requiring human attestation and verifiable build origins.
## Common Pitfalls to Avoid
- **Ignoring Brand New Packages:** Staged publishing only works for existing packages. Be extra vigilant during the initial creation/first publish of a new package.
- **Outdated CLI:** Using a version of npm older than 11.15.0 will cause the `stage publish` command to fail or be ignored.
- **CI/CD Blind Spots:** Relying solely on OIDC/Trusted Publishing without Staged Publishing still leaves a window of risk if the CI/CD environment itself is compromised.
## Resources
- **npm CLI Documentation:** docs.npmjs[.]com/cli/v11
- **npm Staged Publishing Guide:** docs.npmjs[.]com/staged-publishing
- **OIDC Trusted Publishers:** docs.npmjs[.]com/trusted-publishers