NPM Security Best Practices

[!NOTE]
The NPM ecosystem is no stranger to compromises[^1][^2], supply-chain attacks[^3], malware[^4][^5], spam[^6], phishing[^7], incidents[^8] or even trolls[^9]. In this repository, I have consolidated a list of information you might find useful in securing yourself against these incidents.

Feel free to submit a Pull Request, or reach out to me on Twitter!

[!TIP] This repository covers npm, bun, deno, pnpm, yarn and more.

Add to your agent:

npx skills add bodadotsh/npm-security-best-practices

Table of Contents

• Got Compromised?
  • Immediate actions to take
  • Case Studies
• For Developers
  • 0. SKILL & Helpers
  • 1. Disable lifecycle scripts
  • 2. Set cooldowns / minimum release age
  • 3. Include lockfiles
  • 4. Pin dependency versions
  • 5. Preinstall preventions
  • 6. Runtime protections
  • 7. Reduce external dependencies
  • 8. Isolated development
• For Maintainers
  • 9. Enable 2FA
  • 10. Create tokens with limited access
  • 11. Generate provenance statements
  • 12. Review published files
• Miscellaneous
  • 13. NPM organization
  • 14. Alternative registry
  • 15. Audit, monitor and security tools
  • 16. Support OSS

Got Compromised?

Immediate Actions to take

[!CAUTION] In the case of a npm supply chain compromise, here’s what you can do immediately:

Identify compromised packages

Keep up to update from trusted newsfeed[^20][^21][^22][^23]. My personal choice is . Confirm with vulnerability databases like or

Preserve evidence before cleanup

Before deleting caches or node_modules, preserve CI logs, package manager logs, lockfiles, package.json, npm token audit history, and a timestamped list of installed packages. This helps later root-cause analysis, credential-impact review, and any coordinated disclosure or insurance reporting.

Remove and replace compromised packages

# remove project cache
rm -rf node_modules
yarn cache clean
pnpm cache delete

# remove global cache
npm cache clean --force
yarn cache clean --mirror
bun pm cache rm
pnpm store prune

Downgrade and pin dependencies to a known clean version, or remove them entirely.

Remove node_modules folders from system: cd ~ && npx npkill, for example: npx npkill --delete-all or without npkill: find . -name 'node_modules' -type d -prune -print -exec trash '{}' \;

Restrict or disable automated scripts

Disable automated pipelines or restrict them while the investigation is ongoing.

Rotate all credentials

Supply chain attacks often targets credentials in the system. Revoke and regenerate npm tokens, GitHub PATs, SSH keys, and cloud provider credentials.

Monitoring suspicious activities

Review and monitor for unauthorized activities in your projects or organizations. Limit outbound network access to trusted domains only. Limit or revovke access from outsiders or third-party tools. Resume work on a brand new system (highly recommended!)

Pick the best practices below based on your needs to strengthen your system against the next attack.

Case Studies

For Developers

[!TIP] Highly recommend over npmjs.com, as it is a modern registry browser with features like detailed package packages, compare, source code and more.

0. SKILL & Helpers

1. Disable Lifecycle Scripts

Lifecycle scripts are special scripts that happen in addition to the pre, post, and `` scripts. For instance, preinstall is run before install is run and postinstall is run after install is run. See how npm handles the “scripts” field: . Lifecycle scripts are a common strategy from malicious actors. For example, the “Shai-Hulud” worms[^3] edit the package.json file to add a postinstall script that would then steal credentials.

npm config set --global ignore-scripts true

# since yarn v4.14, enableScripts defaults to false
yarn config set --home enableScripts false

For bun, deno and pnpm, they are disabled by default.

[!NOTE]

For bun, the top 500 npm packages with lifecycle scripts are allowed by default.

[!TIP] We can combine many of the flags above. For example, the following npm command would install only production dependencies as defined in the lockfile and ignore lifecycle scripts:

npm ci --omit=dev --ignore-scripts

ignore-scripts vs allowScripts

To use ignore-scripts, define the following key and value pair in a project level .npmrc file or ~/.npmrc file:

ignore-scripts=true

This is a strict, all-or-nothing binary toggle. It blocks all lifecycle scripts (including your own project’s lifecycle scripts and every dependencies’), with no built-in way to make exceptions for specific trusted packages.

While ⁠allowScripts manages dependency-level scripts (it does not affect your own defined root lifecycle scripts).

To use allowScripts, you can run npm approve-scripts canvas sharp and it will add the following to local package.json file:

"dependencies": {
  "canvas": "^3.2.3",
  "sharp": "^0.35.2"
},
"allowScripts": {
  "[email protected]": true,
  "[email protected]": true
}

Or, you can run npm config set allow-scripts=canvas,sharp --location=project and it will add the following to local .npmrc file:

allow-scripts=canvas,sharp

From npm v12+, allowScripts defaults to false, meaning all dependencies’ lifecycle scripts are blocked by default. If you have ⁠ignore-scripts=true, it will take precedence over any ⁠allowScripts configurations. Therefore, developers have two options:

• The all-or-nothing ⁠ignore-scripts approach, where all dependencies’ lifecycle scripts (including your own) are blocked.
• The more granular ⁠allowScripts approach, where by default, dependencies’ lifecycle scripts are blocked, but not your own, and you can allow specific dependencies’ lifecycle scripts.

2. Set Cooldowns / Minimum Release Age

We can set a delay to avoid installing newly published packages. This applies to all dependencies, including transitive ones. For example, pnpm v10.16 introduced the minimumReleaseAge option: , which defines the minimum number of minutes that must pass after a version is published before pnpm will install it. If minimumReleaseAge is set to 1440, then pnpm will not install a version that was published less than 24 hours ago.

# since npm v11.10.0
npm config set --global min-release-age=7 

bun add  --minimum-release-age 

# since pnpm v11, minimumReleaseAge defaults to 1440 (1 day)
pnpm config set --global minimumReleaseAge 

yarn config set --home npmMinimalAgeGate '7d'

deno install --minimum-dependency-age=P7D

[!TIP] Want to quickly set these as defaults globally? Check the helpers.

Examples of other tools that offer similar functionalities:

• npm-check-updates () has the --cooldown/-c flag, for example: npx npm-check-updates -i --format group -c 7
• Renovate CLI () has a minimumReleaseAge config option.
• Step Security () has a NPM Package Cooldown Check feature.

[!TIP] Read how automated tools like Renovate or Dependabot can enable faster malware delivery.

3. Include Lockfiles

Ensure to commit package managers lockfiles to git and share between different environments[^26]. Different lockfiles are: package-lock.json for npm, pnpm-lock.yaml for pnpm, bun.lock for bun, yarn.lock for yarn and deno.lock for deno.

In automated environments such as continuous integration and deployments, we should install the exact dependencies as defined in the lockfile.

npm ci
bun install --frozen-lockfile
yarn install --frozen-lockfile
pnpm install --frozen-lockfile
deno install --frozen

For deno, we can also set the following in a deno.json file:

{
  "lock": {
    "frozen": true
  }
}

[!TIP]

When dealing with merge conflicts in lockfiles, it is not necessary to delete the lockfile. When dependencies (including transitive) are defined with version range operators (^, ~, etc), re-building the lockfile from scratch can result in unexpected updates.

Modern package managers have built-in conflict resolutions[^18][^19], just checkout main and re-run install. pnpm also allows Git Branch Lockfiles where it creates a new lockfile based on branch name, and automatically merge it back into the main lockfile later.

4. Pin Dependency Versions

[!TIP] It is debatable whether pinning versions is a best practice. There are sound basis on either side. Here, I am following the best practice suggested by the node.js security best practices[^28]. But feel free to join the discussion to see why you may not want to pin exact versions.

On npm, by default, a new dependency will be installed with the Caret ^ operator. This operator installs the most recent minor or patch releases. E.g., ^1.2.3 will install 1.2.3, 1.6.2, etc. See and try out the npm SemVer Calculator ().

Here’s how to pin exact version in various package managers:

npm install --save-exact react
pnpm add --save-exact react
yarn add --save-exact react
bun add --exact react
deno add npm:[email protected]

We can also update this setting in configuration files (e.g., .npmrc), with the save-exact key:

npm config set save-exact=true
pnpm config set save-exact true
yarn config set defaultSemverRangePrefix ""

For bun, the config file is bunfig.toml and corresponding config is:

[install]
exact = true

Override the transitive dependencies

However, our direct dependencies also have their own dependencies (transitive dependencies). Even if we pin our direct dependencies, their transitive dependencies might still use broad version range operators (like ^ or ~). The solution is to override the transitive dependencies:

In package.json, if we have the following overrides field:

{
  "dependencies": {
    "library-a": "^3.0.0"
  },
  "overrides": {
    "lodash": "4.17.21"
  }
}

• Let’s assume that ⁠library-a’s ⁠package.json has a dependency on "lodash": "^4.17.0"
• Without the ⁠overrides section, ⁠npm might install ⁠[email protected] (or any of the latest ⁠4.x.x versions) as a transitive dependency of ⁠library-a
• However, by adding "overrides": { "lodash": "4.17.21" }, we are telling ⁠npm that anywhere ⁠lodash appears in the dependency tree, it must be resolved to exactly version ⁠4.17.21

For pnpm, we can also define the overrides field in the pnpm-workspace.yaml file:

For yarn, the resolutions field is introduced before the overrides field, and it also offers a similar functionality:

{
  "resolutions": {
    "lodash": "4.17.21"
  }
}

# yarn also provide a cli to set the resolution: https://yarnpkg.com/cli/set/resolution
yarn set resolution  

For bun, it supports either the overrides field or the resolutions field:

For deno and deno.json, see :

{
  "links": [
    "../path/to/local_npm_package"
  ]
}

5. Preinstall Preventions

How do we know and trust that whenever we install a package (either npm or github actions), everything will be fine? We shouldn’t. Here are few ways we can increase our confidence that install command is safer to run:

Preinstall Scanners

⭐ Socket Firewall Free:

npm i -g sfw
# works for `npm`, `yarn`, `pnpm`
sfw npm install 

# example: alias `npm` to `sfw npm` in zsh
# echo "alias npm='sfw npm'" >> ~/.zshrc

OSV

Google’s OSV (Open Source Vulnerabilities) project offers database, API, scanner , etc that you can use to query vulnerability data in various ecosystems.

deps.dev

Another Google project. The difference is that deps.dev offers a broader package intelligence report, such as metadata, licenses, and health signals etc.

Aikido Safe Chain

The Aikido Safe Chain wraps around the npm cli, npx, yarn, pnpm, pnpx, bun, bunx, and pip to provide extra checks before installing new packages

npm install -g @aikidosec/safe-chain

npq:

npq install express
NPQ_PKG_MGR=pnpm npx npq install fastify

With Bun, we can use its Security Scanner API

bun add -d @socketsecurity/bun-security-scanner

From Bun v1.3+, you can integrate Socket with Bun

# in bunfig.toml
[install.security]
scanner = "@socketsecurity/bun-security-scanner"

brin (for the agents):

npm install -g brin

[!TIP] GitHub Actions has became a popular target for attacks, see Megalodon and TanStack Postmortem. Therefore, it is highly recommended to not only secure/audit npm dependencies, but also other dependencies like github actions or docker images.

⭐ zizmor (static analysis for GitHub Actions):

pinact edit/pin GitHub action files and more:

6. Runtime Protections

Most techniques focus on the install and build phases, we can add an extra layer of security during the runtime phase of JavaScript applications.

Permission Model

In the latest LTS version of nodejs, we can use the Permission model to control what system resources a process has access to or what actions the process can take with those resources. However, this does not provide security guarantees in the presence of malicious code. Malicious code can still bypass the permission model and execute arbitrary code without the restrictions imposed by the permission model.

Read about the Node.js permission model:

# by default, granted full access
node index.js

# restrict access to all available permissions
node --permission index.js

# enable specific permissions
node --permission --allow-fs-read=* --allow-fs-write=* index.js

# use permission model with `npx`
npx --node-options="--permission" 

Deno disables permissions by default. See

# by default, restrict access
deno run script.ts

# enable specific permission
deno run --allow-read script.ts

For Bun, the permission model is currently discussed here and here.

Hardened JavaScript

Companies like MetaMask and Moddable uses and to enable runtime protections like prevent modifying JavaScript’s primordials (Object, String, Number, Array, …), and limit access to the platform API (window, document, XHR, etc) per-package. These mechanism are also suggested as TC39 proposals like

Watch The Attacker is Inside: Javascript Supplychain Security and LavaMoat (~20mins, Nov 2022) to get a quick high level overview of how this works.

7. Reduce External Dependencies

Because npm has a low barrier for publishing packages, the ecosystem quickly grew to be the biggest package registry with over 5 million packages to date[^11]. But not all packages are created equal. There are small utility packages[^8] that are downloaded as dependencies when we could write them ourselves and raise the question of “have we forgotten how to code?[^12]”

Between nodejs, bun, deno and the Web APIs, developers can use many of their modern features instead of relying on third-party libraries. The native modules may not provide the same level of functionality, but they should be considered whenever possible. Here are few examples:

[!TIP] Check out where they have an excellent list of module replacements (i.e. possible alternative packages).

Here are some resources that you might find useful:

• Visualise library dependencies:
• Analyse dependencies metadata online: , or locally: pnpm dlx node-modules-inspector
• Knip (remove unused dependencies):
• Erase unwanted node_modules with npkill: cd ~ && npx npkill

[!IMPORTANT] Remember, given the prevalence of npm packages, there are more node_modules folders in your system than you think! For example, VSCode extensions, browser extensions, desktop applications, CLIs, etc. Any of them could be a liability in the future.

8. Isolated development

Developing code in an isolated environment is a popular and effective way of preventing supply-chain attacks. Some wellknown local virtual machines (VMs) solutions are: VirtualBox, VMware Fusion, Parallels Desktop, and OrbStack.

Example of Mitchell Hashimoto running NixOS through VMware Fusion on macOS:

Cloud sandbox also offer an easier setup path and can be used directly within browsers, popular products are: CodeSandbox, Ona (prev Gitpod), GitHub Codespaces, and many more.

Container-based development are also gaining adoptions, especially with the Development Containers specification that is focused on enriching containers with development specific content and settings.

Great tutorial by CJ on setting up dev container:

If you know any great tips or feedback, join the discussion here!

For Maintainers

9. Enable 2FA

Two factor authentication (2FA) adds an extra layer of authentication to your npm account. 2FA is not required by default, but from December 2025, when you create a new package, 2FA will be enabled by default in the package settings.

# ensure that 2FA is enabled for auth and writes (this is the default)
npm profile enable-2fa auth-and-writes

[!IMPORTANT]

It is advised to configure a security-key that support WebAuthn, instead of time-based one-time password (TOTP)[^17]

10. Create Tokens with Limited Access

[!TIP]

Best practice: prefer trusted publishing over tokens if possible! See the “trusted publishing” section below for more details.

At the end of 2025, NPM announced the sunset of Legacy Tokens to improve security. Granular Access Tokens is the default going forward[^27].

Create granular access tokens via the website: or npm cli:

The npm login cli command enables a two-hour session token instead of long-lived tokens. During these sessions, 2FA is enforced for publishing operations, adding an extra layer of security.

Here are some best practices when creating tokens:

• Descriptive token names
• Restrict token to specific packages, scopes, and organizations
• Set a token expiration date (e.g., annually)
• Limit token access based on IP address ranges (CIDR notation)
• Select between read-only or read and write access
• Don’t use the same token for multiple purposes

11. Generate Provenance Statements

The provenance attestation is established by publicly providing a link to a package’s source code and build instructions from the build environment. This allows developers to verify where and how your package was built before they download it.

The publish attestations are generated by the registry when a package is published by an authorized user. When an npm package is published with provenance, it is signed by Sigstore public good servers and logged in a public transparency ledger, where users can view this information.

For example, here’s what a provenance statement look like on the vue package page:

To establish provenance, use a supported CI/CD provider (e.g., GitHub Actions) and publish with the correct flag:

npm publish --provenance

To publish without evoking the npm publish command, we can do one of the following:

• Set NPM_CONFIG_PROVENANCE to true in CI/CD environment
• Add provenance=true to .npmrc file
• Add publishConfig block to package.json

"publishConfig": {
  "provenance": true
}

For those interested in Reproducible Builds, check out OSS Rebuild () and the Supply-chain Levels for Software Artifacts (SLSA) framework ().

Trusted Publishing

Use trusted publishing over tokens whenever possible[^17]

When using OpenID Connect (OIDC) auth, one can publish packages without npm tokens, and get automatic provenance. This is called trusted publishing and read the GitHub announcement here:

See for instructions on how to configure trusted publishing.

Related tools:

• (CLI to setup Trusted Publisher for monorepo packages)
• (Userscript to fill the form for Trusted Publisher on npmjs.com)

12. Review Published Files

Limiting the files in an npm package helps prevent malware by reducing the attack surface, and it avoids accidental leaking of sensitive data

The files field in package.json is used to specify the files that should be included in the published package. Certain files are always included, see: for more details.

{
  "name": "my-package",
  "version": "1.0.0",
  "main": "dist/index.js",
  "files": ["dist", "LICENSE", "README.md"]
}

[!TIP]

The .npmignore file can also be used to exclude files from the published package. It will not override the "files" field, but in subdirectories it will.

The .npmignore file works just like a .gitignore. If there is a .gitignore file, and .npmignore is missing, .gitignore’s contents will be used instead.

Run npm pack --dry-run or npm publish --dry-run to see what would happen when we run the pack or publish command.

> npm pack --dry-run
npm notice Tarball Contents
npm notice 1.1kB LICENSE
npm notice 1.9kB README.md
npm notice 108B index.js
npm notice 700B package.json
npm notice Tarball Details

In deno.json, use the publish.include and publish.exclude fields to specify the files that should be included or excluded:

{
  "publish": {
    "include": ["dist/", "README.md", "deno.json"],
    "exclude": ["**/*.test.*"]
  }
}

Miscellaneous

13. NPM Organization

At the organization level, best practices are:

• Enable Require 2FA at the Organization Level
• Minimise the number of npm Organization members
• If multiple package teams in same organization, set the developers Team permission for all packages to READ
• Create separate Teams to manage permissions for each package

14. Alternative Registry

JSR is a modern JavaScript/TypeScript package registry with backwards compatibility with npm.

[!NOTE] Not all npm packages are on JSR!

Visit to see if the package is available and read the npm limitations documentation.

deno add jsr:
pnpm add jsr: # pnpm 10.9+
yarn add jsr: # yarn 4.9+
# npm, bun, and older versions of yarn or pnpm
npx jsr add  # replace npx with yarn dlx, pnpm dlx, or bunx

Private Registry

Private package registries are a great way for organizations to manage their own dependencies, acts as a proxy to the public npm registry, and enforce security policies before they are used in a project.

Here are some private registries that you might find useful:

• GitHub Packages

[!IMPORTANT] Currently, GitHub Packages only supports personal access token (classic), but classic PATs can be insecure as it has broad permissions and lacks of granular permissions![^24][^25] For this reason, you may want to pick an alternative package registry from below ⬇️

• Verdaccio
  • See Verdaccio best practices:
• Vlt
  • vlt’s Serverless Registry (VSR) can be deployed to Cloudflare Workers in minutes.
• JFrog Artifactory
• Sonatype:
• Cloudsmith:
• pnpr:

[!IMPORTANT] Private registries have the advantages of separating the supply chain from the public registry, and enforce custom security policies. But they also have the disadvantages of being more complex to setup and maintain, and can be more expensive (cost of storage and bandwidth) to use.

[!TIP] No Registry? If the usage of a public registry like npm is a real concern, it is also possible to build and import the library yourself as long as you have access to the source code. See for adding packages without npm but with pnpm workspace and git submodules.

15. Audit, Monitor and Security Tools

Audit

Many package managers provide audit functionality to scan your project’s dependencies for known security vulnerabilities, show a report and recommend the best way to fix them.

npm audit # audit dependencies
npm audit fix # automatically install any compatible updates
npm audit signatures # verify the signatures of the dependencies

pnpm audit
pnpm audit --fix

bun audit

deno audit
deno audit --socket

yarn npm audit
yarn npm audit --recursive # audit transitive dependencies

[!TIP] The npm sbom command () outputs SBOM which is often required for security auditing. Since pnpm v11+, there is a pnpm sbom command too.

SCA Tools

Package managers like npm audit only inspects package lockfiles. If a library was downloaded manually, copied into a public/js/ or vendor/ directory, or bundled directly into the codebase, npm audit will not see it. SCA (Software Composition Analysis) tools scans the actual filesystem and finds standalone JS files, vendor scripts, and client-side assets regardless of whether they exist in a package manifest. If your applications have standalone JS files, it is recommended to do both.

OWASP dependency-check

brew update && brew install dependency-check
dependency-check -h

retire.js

npx retire

Most of the premium services below offer SCA scanning too.

GitHub

GitHub offers several services that can help protect against npm malwares, including:

• Dependabot: This tool automatically scans your project’s dependencies, including npm packages, for known vulnerabilities.
• Software Bill of Materials (SBOMs): GitHub allows you to export an SBOM for your repository directly from its dependency graph. An SBOM provides a comprehensive list of all your project’s dependencies, including transitive ones (dependencies of your dependencies).
• Code Scanning: Code scanning can also help identify potential vulnerabilities or suspicious patterns that might arise from integrating compromised npm packages.

[!WARNING] If you spot vulnerabilities or issues in NPM or Github, please report them using the following links:

OpenSSF Scorecard

and

Free and open source automated tool that assesses a number of important heuristics (“checks”) associated with software security and assigns each check a score of 0-10. Several risks mentioned in this repository are included as part of the checks: Pinned Dependencies, Token Permissions, Packaging, Signed Releases,…

Run the checks:

1. automatically on code you own using the GitHub Action
2. manually on your (or somebody else’s) project via the Command Line

Socket.dev

Socket.dev is a security platform that protects code from both vulnerable and malicious dependencies. It offers various tools such as a GitHub App scans pull requests, CLI tool, web extension, VSCode extension and more. Here’s their talk on AI powered malware hunting at scale, Jan 2025. Plus the Socket Firewall sfw tool in the Preinstall Scanners section.

Snyk

Snyk offers a suite of tools to fix vulnerabilities in open source dependencies, including a CLI to run vulnerability scans on local machine, IDE integrations to embed into development environment, and API to integrate with Snyk programmatically. For example, you can test public npm packages before use or create automatic PRs for known vulnerabilities.

FOSSA

FOSSA is a compliance and security platform that helps organizations manage the complexities of their software supply chain. It achieves this by providing visibility into all software components, from packages and containers to binaries. By generating comprehensive SBOMs (Software Bill of Materials), companies reduce legal and IP risk, consolidate vulnerability management across their codebase, and comply with regulatory reporting requirements.

16. Support OSS

Maintainer burnout is a significant problem in the open-source community. Many popular npm packages are maintained by volunteers who work in their spare time, often without any compensation. Over time, this can lead to exhaustion and a lack of motivation, making them more susceptible to social engineering where a malicious actor pretends to be a helpful contributor and eventually injects malicious code.

In 2018, the event-stream package was compromised due to the maintainer giving access to a malicious actor[^13]. Another example outside the JavaScript ecosystem is the XZ Utils incident[^14] in 2024 where a malicious actor worked for over three years to attain a position of trust.

OSS donations also help create a more sustainable model for open-source development. Foundations can help support the business, marketing, legal, technical assistance and direct support behind hundreds of open source projects that so many rely upon[^15][^16].

In the JavaScript ecosystem, the OpenJS Foundation () was founded in 2019 from a merger of JS Foundation and Node.js Foundation to support some of the most important JS projects. And few other platforms are listed below where you can donate and support the OSS you use everyday:

• GitHub Sponsors
• Open Collective
• Thanks.dev
• Open Source Pledge
• Ecosystem Funds:

Star History

[^1]:

[^2]:

[^3]:

[^4]:

[^5]:

[^6]:

[^7]:

[^8]:

[^9]:

[^10]:

[^11]:

[^12]:

[^13]:

[^14]:

[^15]:

[^16]:

[^17]:

[^18]:

[^19]:

[^20]:

[^21]:

[^22]:

[^23]:

[^24]:

[^25]:

[^26]:

[^27]:

[^28]: