lirantal/npm-security-best-practices

Awesome npm Security Best Practices

A curated and practical list of security best practice for using npm packages.

Scope:

• safe-by-default npm package manager command-line options
• hardening against supply chain attacks
• deterministic and secure dependency resolution
• security vulnerabilities scanning and package health signals
• instructions for the pnpm and bun package managers where applicable

Context: Shai-Hulud, Nx and other incidents are a growing concern of supply chain security attacks and compromised npm packages. Follow these developer security best practices around npm, package maintenance and secure local development to mitigate security risks.

TL;DR: ✨ Copy/Paste package manager config

Expand below to access a quick copy/paste secure-by-default configuration for npm and pnpm package managers

# npm security best practices
# Source: https://github.com/lirantal/npm-security-best-practices

# SECURITY: do not run any lifecycle scripts (postinstall) etc
ignore-scripts=true

# SECURITY: reject git-source dependencies (git+ssh:// etc)
allow-git=none

# SECURITY: block packages newer than 30 days
min-release-age=30

# npm security best practices
# Source: https://github.com/lirantal/npm-security-best-practices

# SECURITY: block packages newer than 30 days (43200 minutes)
minimumReleaseAge: 43200

# SECURITY: reject a version whose publishing trust signals regressed
trustPolicy: no-downgrade

# SECURITY: keep strict overrides only when necessary and vetted
# trustPolicyExclude:
#   - '[email protected]'
#   - '[email protected] || 5.102.1'

# SECURITY: pnpm blocks install scripts by default, enabled explicitly for:
allowBuilds:
  esbuild: true
  rolldown: true
  unrs-resolver: true

# SECURITY: fail the install if a dependency wants to run a build
# script that isn't in the allow-list above
strictDepBuilds: true

# SECURITY: reject dependencies sourced from git URLs
blockExoticSubdeps: true

Table of Contents

npm Security Best Practices:

• 1 Disable Post-Install Scripts
  • 1.1. pnpm disable post-install scripts
  • 1.2. Bun disable post-install scripts
  • 1.3. Run the scripts you need
  • 1.4. pnpm trust policy
• 2 Block Git-Based Dependencies
  • 2.1. pnpm block exotic subdependencies
• 3 Install with Cooldown
  • 3.1. npm / pnpm / Bun / Yarn minimumReleaseAge cooldown
  • 3.2. Snyk automated dependency upgrades with cooldown
  • 3.3. Dependabot automated dependency upgrades with cooldown
  • 3.4. Renovate bot automated dependency upgrades with cooldown
• 4 Harden package installs with security tools
  • 4.1. Use npq for hardening package installs
  • 4.2. Use Socket Firewall (sfw) for blocking malicious packages
• 5 Prevent npm lockfile injection
• 6 Use npm ci
• 7 Avoid blind npm package upgrades
• 8 Harden npx execution

Secure Local Development Best Practices:

• 9 No plaintext secrets in .env files
• 10 Work in Dev Containers

npm Maintainer Security Best Practices:

• 11 Enable 2FA for npm accounts
• 12 Publish with Provenance Attestations
• 13 Publish with OIDC
• 14 Reduce your package dependency tree

npm Package Health Best Practices:

• 15 Consult the Snyk Security Database for package health
• 16 Do not trust the official npmjs.org registry
• 17 Prevent dependency confusion attacks

Resources:

• FAQ

1. Disable Post-Install Scripts

[!WARNING] Post-install scripts are a common and recurring attack vector for supply chain attacks.

Recent attacks like Shai-Hulud¹, Nx² and long-standing attacks like event-stream³ have all leveraged npm postinstall scripts to execute arbitrary code on a developer's machine during package installation in order to exfiltrate sensitive data, trigger a worm-like propagation, or perform other malicious activities.

By disabling post-install scripts, you can mitigate the risk of such attacks by preventing the execution of potentially harmful code during the installation process.

[!TIP] Security Best Practice: Configure npm to disable lifecycle scripts when installing packages so any npm package, direct or indirect, cannot execute arbitrary code or commands on your system during installation.

[!NOTE] How to implement?

It is highly recommended in your global configuration to set npm's ignore-scripts configuration to disable all post-install scripts for all projects on your machine:

$ npm config set ignore-scripts true

Or disable npm's post-install scripts when performing ad-hoc package install using the command line:

$ npm install --ignore-scripts <package-name>

1.1. pnpm disable post-install scripts

Beginning with version 10.0 pnpm disables postinstall scripts by default. pnpm allows an "escape hatch" to re-enable postinstall scripts or set an explicit allow-list of packages that are allowed to run postinstall scripts.

Use pnpm-workspace.yaml to control which packages are permitted to run build scripts:

# pnpm-workspace.yaml

# Allow only specific packages to run lifecycle scripts (pnpm 10+)
onlyBuiltDependencies:
  - esbuild
  - fsevents
  - [email protected] || 21.6.5   # pin allowed versions

# Silently block specific packages and suppress the warning
ignoredBuiltDependencies:
  - sharp

[!NOTE] As of pnpm 10.26+, allowBuilds is the preferred replacement for both onlyBuiltDependencies and ignoredBuiltDependencies (the earlier settings are deprecated). It provides a single map of package-name → true/false to allow or deny build scripts:

allowBuilds:
  esbuild: true
  core-js: false
  [email protected] || 21.6.5: true

To make unreviewed build scripts a hard error (rather than a warning), enable strictDepBuilds (pnpm 10.3+):

strictDepBuilds: true

With strictDepBuilds: true, pnpm install will exit with a non-zero code if any dependency tries to run a lifecycle script that has not been explicitly allowed, turning silent warnings into CI-blocking failures.

1.2. Bun disable post-install scripts

Bun disables postinstall scripts by default and maintains its own internal allow-list of packages that are allowed to run postinstall scripts. Bun allows an "escape hatch" to allow postinstall scripts for specific trusted packages via a trustedDependencies field in package.json.

1.3 Run the scripts you need

Some of the install scripts are there for a reason. If you need to run them, do it in an auditable way and avoid npm trusting the package name in package.json too much.

Use https://www.npmjs.com/package/@lavamoat/allow-scripts to create an allowlist of specific positions in your dependency graph where scripts are allowed.

1.4. pnpm trust policy

pnpm 10.21+ ships a trustPolicy setting that detects when a package's publish-time trust level has decreased compared to earlier releases — for example, when a package previously published via a Trusted Publisher (OIDC/GitHub Actions) is now published without provenance or signatures. This can be an early signal of an account compromise or supply chain attack.

[!TIP] Security Best Practice: Set trustPolicy: no-downgrade so that pnpm refuses to install any package version whose trust evidence is weaker than a previously published version of that package.

[!NOTE] How to implement?

In pnpm-workspace.yaml:

# Fail if a package's trust level has decreased (pnpm 10.21+)
trustPolicy: no-downgrade

# Allow specific packages or versions to bypass the check when needed
trustPolicyExclude:
  - '[email protected]'
  - '[email protected] || 5.102.1'

# Ignore the check for packages published more than 30 days ago (pnpm 10.27+)
# Useful for older packages that pre-date provenance support
trustPolicyIgnoreAfter: 43200  # minutes (30 days)

Trust levels pnpm recognises (strongest → weakest):

1. Trusted Publisher – published via a configured Trusted Publisher (e.g. GitHub Actions OIDC)
2. Provenance – published with an npm provenance attestation
3. Signatures – package registry signature present
4. No evidence – no trust signals at all

When trustPolicy: no-downgrade is enabled, if any previously published version of a package had a higher trust level than the version being installed, the install is aborted.

2. Block Git-Based Dependencies

[!WARNING] A dependency declared as a git URL (e.g. "pkg": "git+https://github.com/org/pkg") bypasses registry security controls entirely. The fetched repository can ship its own .npmrc that re-enables lifecycle scripts — silently undoing --ignore-scripts — and the code is never scanned by registry-side malware checks. Even with post-install scripts disabled, git-sourced dependencies can introduce unreviewed, unversioned code into your project.

Dependencies should be resolved from the npm registry using semver ranges, where packages are subject to registry security scanning, provenance attestations, and signature verification. Git-based dependency URLs sidestep all of these protections: the code comes directly from a repository, can change at any time (branches, tags, and even commits can be force-pushed), and can include files like .npmrc that alter the behaviour of the package manager itself.

[!TIP] Security Best Practice: Configure your package manager to block git-based dependency URLs so that all packages are resolved from the registry with full security controls applied.

[!NOTE] How to implement?

Set npm's allow-git configuration (npm CLI 11.10.0+) to prevent git-based dependency resolution:

$ npm config set allow-git none

Or use the flag for ad-hoc installs:

$ npm install --allow-git=none <package-name>

The allow-git setting accepts three values:

• all (default) — allows any git dependency
• none — blocks all git dependencies
• root — allows git dependencies only in your project's root package.json

See the official npm documentation for --allow-git for more details.

2.1. pnpm block exotic subdependencies

pnpm does not have a direct equivalent to npm's allow-git setting that blocks all git dependencies outright. However, pnpm 10.26+ provides blockExoticSubdeps to prevent transitive dependencies from pulling code from git repositories or raw tarball URLs — sources that bypass registry security scanning.

[!NOTE] How to implement?

In pnpm-workspace.yaml:

blockExoticSubdeps: true

When enabled, only direct dependencies (those declared in your root package.json) are allowed to use exotic sources such as git repositories or tarball URLs. All transitive dependencies must be resolved from the configured registry, local file paths, workspace links, or trusted GitHub repositories.

For full details on blockExoticSubdeps, see also section 5 — Prevent npm lockfile injection.

3. Install with Cooldown

[!WARNING] Newly released packages and versions may contain malicious code that are often-times quickly picked up by the community in matter of hours or days and subsequently unpublished.

Attackers build on the npm versioning and publishing model which prefers and resolves to latest semvar ranges to employ attacks by publishing new versions of packages. By implementing a "cooldown" period before installing or upgrading to new package versions, you reduce the risk of installing compromised packages that may be quickly discovered and removed from the registry.

[!TIP] Security Best Practice: Configure your package manager to delay installations of recently published packages, allowing time for the community to discover and report potential security issues or functional problems.

[!NOTE] How to implement?

Set a persistent minimum release age in npm's configuration so that every npm install skips any package version published less than the specified number of days ago:

$ npm config set min-release-age 3

Or use the --before flag for a one-off install to only consider packages published before a specific date:

$ npm install express --before=2025-01-01

Or use shell command evaluation with --before to make it dynamic with a 7-day cooldown:

$ npm install express --before="$(date -v -7d)"

Note: The --before approach requires manual date management and isn't ideal for automated workflows due to hardcoded dates. Prefer min-release-age for a persistent configuration.

3.1. npm / pnpm / Bun / Yarn minimumReleaseAge cooldown

Configure npm, pnpm, Bun, or Yarn to delay package installations by setting a minimum release age in your package manager's configuration file.

For npm, set min-release-age in your .npmrc (or via npm config set):

# .npmrc
min-release-age=3

Or set it globally so that all projects on your machine benefit:

$ npm config set min-release-age 3

For pnpm 10.16+, use pnpm-workspace.yaml:

minimumReleaseAge: 20160  # 2 weeks (in minutes)
# Allow instant upgrades for @types/react and typescript
minimumReleaseAgeExclude:
  - '@types/react'
  - typescript

For Bun 1.3+, use bunfig.toml:

# bunfig.toml
[install]
# Only install package versions published at least 3 days ago
minimumReleaseAge = 259200 # seconds - in #23162 it'll allow "3d" too

# These packages will bypass the 3-day minimum age requirement
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

For Yarn 4.10+, use .yarnrc.yml:

# .yarnrc.yml
# Only consider npm package versions published at least 3 days ago
npmMinimalAgeGate: "3d"

# These packages bypass the age gate (package descriptors or glob patterns)
npmPreapprovedPackages:
  - "@types/react"
  - "typescript"

These configurations prevent package managers from installing any package version that was published less than the specified time period ago.

3.2. Snyk automated dependency upgrades with cooldown

Snyk automatically includes a built-in cooldown period for dependency upgrade Pull Requests. Snyk does not recommend upgrades to versions that are less than 21 days old to avoid:

• Versions that introduce functional bugs and are subsequently unpublished
• Versions released from compromised accounts where the owner has lost control to malicious actors

3.3. Dependabot automated dependency upgrades with cooldown

Dependabot has a cooldown configuration option, for setting the number of days before a specific version of a dependency will be updated:

Defines a cooldown period for dependency updates, allowing updates to be delayed for a configurable number of days.

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: npm
    directory: /
    schedule:
      interval: daily
    cooldown:
      default-days: 7
      semver-major-days: 7
      semver-minor-days: 7
      semver-patch-days: 7

3.4. Renovate bot automated dependency upgrades with cooldown

Renovate bot has a minimumReleaseAge config option, for setting the minimum age of each package version before a pull request will be created for it:

Time required before a new release is considered stable.

4. Harden package installs with security tools

[!WARNING] You should never install npm packages without properly auditing their package health and security signals.

How do you know if an npm package is safe to install? maybe it was just published yesterday? maybe you have an accidental typo in the package name and land on a similarly named malicious package? maybe the package has known vulnerabilities or malicious post-install scripts? Malicious packages can execute arbitrary code during installation, exfiltrate sensitive data, or introduce vulnerabilities into your system without your knowledge.

Installing a new ad-hoc npm package can expose your system to supply chain attacks. Many attacks compromised trusted and popular npm packages, exploit typosquatting, or introduce malicious code in pre/post-install scripts that execute during the installation process.

4.1. Use npq for hardening package installs

[!TIP] Security Best Practice: Use npq as a proactive security control that audits npm packages before installation, providing comprehensive security checks, package health signals, and interactive warnings for potentially dangerous or high-risk packages.

[!NOTE] How to implement?

Install npq globally to audit packages before installation:

$ npm install -g npq

Use npq instead of npm for package installations:

$ npq install express

For seamless integration, alias npm to use npq automatically:

$ alias npm='npq-hero'

Note: installing npq provides both npq and npq-hero commands. or add it to your shell profile for persistence:

$ echo "alias npm='npq-hero'" >> ~/.zshrc  # or ~/.bashrc
$ source ~/.zshrc

What npq validates

npq performs comprehensive security audits using "marshalls" - specialized security validators that check for:

• Vulnerability scanning: Consults Snyk's database for known CVE vulnerabilities
• Package age analysis: Flags packages less than 22 days old (new package detection)
• Typosquatting detection: Identifies packages with names similar to popular packages
• Registry signature verification: Validates npm registry signatures using published keys
• Provenance attestation: Verifies package build provenance metadata
• Pre/post-install scripts: Warns about potentially malicious installation scripts
• Package health indicators: Checks for README, LICENSE, repository URL, and download metrics
• Version maturity: Flags package versions published less than 7 days ago
• Binary introduction: Warns when new command-line binaries are added
• Deprecation status: Alerts for deprecated packages
• Maintainer domain validation: Checks for expired domains in maintainer emails

pnpm and Bun compatibility

npq works with different package managers through environment variables:

# Use with pnpm
NPQ_PKG_MGR=pnpm npq install fastify

# Use with Bun  
NPQ_PKG_MGR=bun npq install fastify

# Set permanent aliases
alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"

Advanced usage options

Run security checks without installing packages:

$ npq install express --dry-run

Disable specific security marshalls when needed:

$ MARSHALL_DISABLE_SNYK=1 npq install express

4.2. Use Socket Firewall (sfw) for blocking malicious packages

[!TIP] Security Best Practice: Use Socket Firewall (sfw) as a real-time firewall that intercepts supported package manager commands and blocks packages flagged for malicious behavior, using Socket's deep package analysis and threat intelligence.

[!NOTE] How to implement?

Install sfw globally:

$ npm install -g sfw

Socket Firewall Free runs in wrapper mode. Prefix your package manager command with sfw:

$ sfw npm install express

Examples with other supported package managers:

$ sfw pnpm add express
$ sfw yarn add express
$ sfw pip install requests
$ sfw uv pip install flask
$ sfw cargo fetch

Socket Firewall will block the package fetch/install if a package is flagged, and prompt you with details so you can make an informed decision.

What Socket Firewall checks

Socket Firewall performs deep analysis on packages using Socket's threat intelligence, checking for:

• Malicious code detection: Identifies packages that contain known malware or obfuscated code
• Install script risks: Flags packages with suspicious pre/post-install scripts
• Typosquatting detection: Catches packages with names similar to popular packages
• Dependency confusion: Detects potential dependency confusion attacks
• Known vulnerabilities: Cross-references CVE databases for disclosed vulnerabilities
• Protestware and env variable access: Warns about packages that access environment variables or exhibit protestware behavior
• Network and filesystem access: Highlights packages that perform unexpected network or disk operations

Comparison with npq

Both npq and sfw intercept package installations and provide security warnings, but they differ in approach:

5. Prevent npm lockfile injection

[!WARNING] Malicious actors can inject compromised packages into your lockfiles through pull requests, potentially compromising your entire application during the next installation.

In September 2019, Liran Tal disclosed security research about inherent security risks with package lockfiles in developer workflows. Both JavaScript package managers, Yarn and npm, were found to be susceptible to lockfile injection attacks.

The security threat occurs when malicious actors gain the ability to contribute source code changes via mechanisms such as pull requests. If they update a lockfile such as package-lock.json or yarn.lock to include a new npm package dependency, or modify the source URL of an existing package, then any invocation of package install commands would fetch the malicious code.

Furthermore, JavaScript package managers allow users to install packages from unconventional sources, such as GitHub gists or directly from source code repositories. Attackers can update the lockfile to specify a new source location (in the resolved key) that they control, and set the SHA512 integrity value accordingly to avoid detection.

[!TIP] Security Best Practice: Use lockfile-lint to validate that your lockfiles adhere to security policies, ensuring that package sources come from trusted registries and that no malicious modifications have been introduced.

[!NOTE] How to implement?

Install lockfile-lint to validate your lockfiles:

npm install --save-dev lockfile-lint

Validate package-lock.json with multiple allowed sources:

npx lockfile-lint --path package-lock.json --type npm --allowed-hosts npm yarn --validate-https

Lockfile-lint validation options

The lockfile-lint CLI provides comprehensive validation to ensure lockfile integrity:

• Host validation: Restrict packages to trusted registry hosts (npm, yarn, verdaccio)
• HTTPS enforcement: Ensure all package sources use secure HTTPS protocol
• Scheme validation: Control allowed URI schemes (https:, git+https:, git+ssh:)
• Package name validation: Verify resolved URLs match declared package names
• Integrity validation: Ensure integrity hashes use secure SHA-512 algorithm

CI/CD integration

Integrate lockfile-lint into your development workflow, such as the following lint:lockfile script in package.json that runs before every install:

{
  "scripts": {
    "lint:lockfile": "lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https",
    "preinstall": "npm run lint:lockfile"
  }
}

pnpm lockfile injection security

pnpm is not susceptible to the same lockfile injection vulnerabilities as npm and yarn because:

• It doesn't maintain tarball sources that can be maliciously modified
• It won't install packages listed in the lockfile that aren't declared in package.json
• The pnpm-lock.yaml format is more resistant to injection attacks

pnpm blockExoticSubdeps

Even with a clean lockfile, a transitive dependency can pull in code from an arbitrary git repository or a raw tarball URL — sources that are opaque to typical registry security scanning. pnpm 10.26+ introduces blockExoticSubdeps to prevent this.

[!TIP] Security Best Practice: Enable blockExoticSubdeps: true so that only your direct dependencies (those declared in package.json) are allowed to use exotic sources such as git repositories or direct tarball URLs. All transitive dependencies must be resolved from the configured registry, local file paths, workspace links, or trusted GitHub repositories.

[!NOTE] How to implement?

In pnpm-workspace.yaml:

blockExoticSubdeps: true

Exotic sources that are blocked for transitive dependencies include:

• Git repositories (git+ssh://..., git+https://...)
• Direct URL links to tarballs (https://.../package.tgz)

Direct dependencies listed in your root package.json are still permitted to use exotic sources.

Bun lockfile linting

Bun uses its own lockfile format - either bun.lock (text-based, default since v1.2) or bun.lockb (binary format). Currently, lockfile-lint does not support Bun's lockfile formats.

[!NOTE] If you are using Bun as your package manager, lockfile-lint is not currently available for validating bun.lock or bun.lockb files. Users should:

• Monitor the lockfile-lint GitHub repository for future Bun support
• Check for alternative security tools that may support Bun lockfiles
• Follow Bun's security best practices, including using minimumReleaseAge cooldown (see section 3.1)

6. Use npm ci

[!WARNING] Using npm install in production can lead to inconsistent installations when lockfiles and package.json files are out of sync, potentially introducing unintended package versions and security vulnerabilities that are resolved during install-time.

Package managers like npm and yarn compensate for inconsistencies between package.json and lockfiles by installing different versions than those recorded in the lockfile. This behavior can be hazardous for build and production environments as they could pull in unintended package versions, rendering the entire benefit of lockfile determinism futile. Developers should also favor deterministic package resolution in their local development workflows.

[!TIP] Security Best Practice: Use deterministic installation command npm ci that enforce strict lockfile adherence, ensuring that only the exact versions specified in the lockfile are installed, and abort installation if inconsistencies are detected.

[!NOTE] How to implement?

Use npm ci instead of npm install for deterministic installations:

$ npm ci

For automated environments like CI/CD, always use the deterministic installation command:

# In your CI/CD pipeline
$ npm ci --only=production

Ensure lockfiles are committed and up-to-date in your repository.

Yarn, Bun, Deno and pnpm Package manager deterministic installations

Different package managers provide specific commands for enforcing lockfile adherence:

yarn: Validate the lockfile (and local cache) did not mutate:

$ yarn install --immutable --immutable-cache

pnpm: Use frozen lockfile installation:

$ pnpm install --frozen-lockfile

Bun: Use frozen lockfile mode:

$ bun install --frozen-lockfile

Deno: Use frozen installation:

$ deno install --frozen

Lockfile management best practices

Ensure proper lockfile management across your development workflow:

Commit all lockfiles to version control:

• package-lock.json (npm)
• pnpm-lock.yaml (pnpm)
• yarn.lock (yarn)
• bun.lock (Bun)
• deno.lock (Deno)

7. Avoid blind npm package upgrades

[!WARNING] Blindly upgrading all dependencies to their latest versions can expose your application to security vulnerabilities, dependency confusion attacks, and malicious packages released from compromised accounts.

Some developers automatically upgrade all dependencies to the latest versions as part of continuous integration processes or local development practices, aiming to ensure forward compatibility or stay at "bleeding edge". Blind dependency upgrades can pull in malicious packages from compromised accounts, introduce functional bugs, or expose applications to supply chain attacks like the colors⁴ and node-ipc⁵ security incidents.

[!TIP] Security Best Practice: Use automated dependency management tools with security policies and manual review processes instead of blindly upgrading all packages to their latest versions.

[!CAUTION] Anti-pattern: Avoid dependency upgrades commands without review:

$ npm update
$ npx npm-check-updates -u
$ pnpm update
$ yarn up
$ bun update

[!NOTE] How to implement?

1. Use controlled dependency management: npx npm-check-updates --interactive
2. Use Snyk Automated Dependency Update PRs
3. Use Dependabot Dependency Update PRs

8. Harden npx execution

[!WARNING] npx resolves, downloads, and executes packages from the npm registry in a single step — with no lockfile, no hash verification, and no cooldown. Every invocation can silently pull in a newly published, potentially malicious version of a package. The Axios supply chain compromise⁶ demonstrated this risk when a compromised maintainer account published backdoored versions of a package with 70+ million weekly downloads, delivering a cross-platform RAT through a malicious post-install dependency.

MCP servers, linters, formatters, and other developer tools are commonly launched via npx (e.g., npx @modelcontextprotocol/server-filesystem). Each invocation is an uncontrolled package resolution — if a package is compromised between two runs, the malicious version is fetched and executed immediately. This is especially dangerous for MCP servers which typically have access to your filesystem, environment variables, and other sensitive resources.

[!TIP] Security Best Practice: Pre-install packages in a dedicated workspace with a lockfile, then force npx to run in offline mode using only pre-vetted, lockfile-verified packages. Never allow npx to fetch and execute arbitrary code from the registry in unsupervised contexts.

[!CAUTION] Anti-pattern: Avoid running npx without version pinning or offline enforcement:

$ npx some-package        # Downloads and executes latest version
$ npx @scope/mcp-server   # No lockfile, no hash check

[!NOTE] How to implement?

Step 1: Create a workspace for your npx packages and install them with a lockfile:

$ mkdir -p $HOME/mcp && cd $HOME/mcp
$ npm init -y
$ npm install @modelcontextprotocol/server-filesystem

Step 2: Run npx with offline mode, forcing it to use only pre-installed packages:

$ npx --include-workspace-root --workspace $HOME/mcp --no --offline @modelcontextprotocol/server-filesystem /path/to/dir

The --no flag refuses to download packages not already installed. The --offline flag prevents any network requests. Together with --workspace, npx will only execute code from your pre-vetted, lockfile-verified workspace.

MCP server configuration

When configuring MCP servers for AI coding tools, include the offline flags in every npx invocation:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "--include-workspace-root",
        "--workspace", "$HOME/mcp",
        "--no",
        "--offline",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  }
}

To update your pre-vetted packages, explicitly run npm update in the workspace directory and review the lockfile changes before your next npx invocation.

9. No plaintext secrets in .env files

[!WARNING] Storing secrets in plaintext environment variables or .env files creates a significant security risk, making sensitive data easily accessible to attackers who successfully launch supply chain attacks or gain access to your system.

Environment variables and .env files are commonly used to store configuration and sensitive data like API keys, database passwords, and tokens. However, these secrets are stored in plaintext and can be easily exfiltrated by malicious npm packages, compromised dependencies, or attackers who gain access to your development environment.

Even if .env files are not committed to version control, they remain vulnerable targets during supply chain attacks where malicious code can read process environment variables or scan the filesystem to locate known configuration files containing secrets.

[!TIP] Security Best Practice: Use secrets management solutions that only store references in environment variable data and require additional authentication (like Touch ID on macOS) to access the actual secret values just-in-time.

[!CAUTION] Anti-pattern: Avoid storing plaintext secrets in .env files:

DATABASE_PASSWORD=my-secret-password
API_KEY=sk-1234567890abcdef

[!NOTE] How to implement?

Step 1: Use secret references in .env files:

DATABASE_PASSWORD=op://vault/database/password
API_KEY=infisical://project/env/api-key

Step 2: Use the secret manager CLI to inject secrets at runtime:

$ op run -- npm start

# or more verbosely: 

$ op run --env-file="./.env" -- node --env-file="./.env" server.js

Follow-up secure secrets resources

• Liran Tal's Do Not Use Secrets in Environment Variables
• 1Password's Secrets Automation with 1Password CLI
• Infisical's Getting Started with Infisical CLI

10. Work in Dev Containers

[!WARNING] Running npm packages directly on your host development machine exposes your entire system to potential malware, allowing malicious packages to access sensitive files, spawning agentic coding CLIs, agent environment variables, and system resources.

Development containers (dev containers) provide an isolated, sandboxed environment that limits the blast radius of supply chain attacks. When malicious npm packages execute during installation or runtime, they are confined to the container environment rather than having access to your entire host system where you may have running other projects, sensitive files, or personal data.

[!TIP] Security Best Practice: Use dev containers to isolate your project's local development workflows from your host system so that npm package execution and other project development practices are limiting the potential impact of supply chain attacks and malicious package behavior.

[!NOTE] How to implement?

Step 1. Create a .devcontainer/devcontainer.json file in your project:

{
  "name": "Node.js Dev Container",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:18",
  "features": {
    "ghcr.io/devcontainers/features/1password:1": {}
  },
  "postCreateCommand": "npm ci"
}

Step 2. Use VS Code to open your project in the dev container

Follow-up resources

• Step-by-step guide on Setting up Dev Containers and 1Password Secrets for Node.js Local Development
• Consider further hardening of the Dev Container:

  "runArgs": [
    "--security-opt=no-new-privileges:true",
    "--cap-drop=ALL",
    "--cap-add=CHOWN",
    "--cap-add=SETUID",
    "--cap-add=SETGID"
  ],
  "containerEnv": {
    "NODE_OPTIONS": "--disable-proto=delete"
  },

• Consider a Custom Dockerfile for enhanced security

11. Enable 2FA for npm accounts

[!WARNING] npm accounts without two-factor authentication are vulnerable to credential theft and account takeover attacks, potentially allowing malicious actors to publish compromised versions of your packages.

The eslint-scope⁷ incident in 2018 demonstrated the risks of compromised npm accounts when attackers published malicious code after stealing developer credentials. Two-factor authentication provides essential protection against such attacks by requiring additional verification beyond just username and password.

[!TIP] Security Best Practice: Enable two-factor authentication on all npm accounts, especially for package maintainers, to prevent unauthorized access and malicious package publications.

[!NOTE] How to implement?

Enable 2FA for authentication and publishing:

$ npm profile enable-2fa auth-and-writes

For login and profile changes only:

$ npm profile enable-2fa auth-only

12. Publish with Provenance Attestations

[!WARNING] Packages without provenance attestations cannot be verified for their build origin or authenticity, making it difficult for users to trust the integrity of your published packages in order to determine if they were built from the intended source code on GitHub or by malicious actors who may have compromised your npm account.

Provenance statements provide cryptographic proof of where and how your packages were built, establishing a verifiable link between your source code and published packages. This transparency helps users verify package authenticity and detect tampering.

[!TIP] Security Best Practice: Generate provenance attestations for your packages using supported CI/CD platforms to provide users with verifiable build information and enhance supply chain security.

[!NOTE] How to implement?

Publish with provenance in GitHub Actions:

permissions:
  id-token: write
steps:
  - run: npm publish --provenance

Note: publishing to npm with provenance requires npm CLI 9.5.0+ and GitHub Actions or GitLab CI/CD with cloud-hosted runners.

13. Publish with OIDC

[!WARNING] Long-lived npm tokens can be compromised, accidentally exposed in logs, or provide persistent unauthorized access if stolen, posing significant security risks to your packages.

Trusted publishing eliminates the need for long-lived npm tokens by using OpenID Connect (OIDC) authentication from your CI/CD environment. This approach uses short-lived, cryptographically-signed tokens that are specific to your workflow and cannot be extracted or reused. This npm package release method is tightly scoped to only allow publishing from your trusted CI environment (GitHub Actions or GitLab) and your specifically authorized workflow files.

[!TIP] Security Best Practice: Configure trusted publishing for your packages to eliminate token-based authentication risks and automatically generate provenance attestations.

[!NOTE] How to implement?

Configure trusted publisher on npmjs.com for your package, then update your CI/CD:

GitHub Actions:

permissions:
  id-token: write
steps:
  - run: npm publish

Trusted publishing supports GitHub Actions and GitLab CI/CD, and automatically generates provenance attestations which complies with OpenSSF standards.

14. Reduce your package dependency tree

[!WARNING] Each dependency in your package increases the attack surface and potential for supply chain vulnerabilities, as users inherit all transitive dependencies when installing your package.

Minimizing dependencies reduces security risks, improves performance, and decreases the likelihood of supply chain attacks. Fewer dependencies mean fewer potential points of failure and reduced exposure to malicious packages in the dependency tree.

[!TIP] Security Best Practice: Design packages with minimal or zero dependencies by leveraging modern JavaScript features and standard library capabilities instead of external packages.

[!NOTE] How to implement?

Replace common dependencies with native JavaScript:

// Instead of lodash
const unique = [...new Set(array)];

// Instead of axios for simple requests
const response = await fetch(url);

// Instead of utility libraries
const isEmpty = obj => Object.keys(obj).length === 0;

Modern JavaScript provides many built-in capabilities that previously required external libraries. Consider the maintenance burden, security implications, and bundle size impact before adding any dependency.

15. Consult the Snyk Security Database for package health

[!WARNING] Installing npm packages without reviewing their health signals can expose your project to unmaintained, insecure, or low-quality dependencies.

Package health encompasses more than just known vulnerabilities — it includes maintenance activity, community adoption, popularity trends, and security posture. A package that is rarely maintained or has a shrinking community may be at greater risk of future compromise or abandonment.

[!TIP] Security Best Practice: Before adopting a new npm package, consult the Snyk Security Database to review its health score, including maintenance, popularity, security, and community signals.

[!NOTE] How to implement?

Visit the Snyk Security Database and search for the npm package you are evaluating. For example, here is the health score for lodash: https://security.snyk.io/package/npm/lodash

The package health page provides:

• Security: known vulnerabilities and CVEs
• Popularity: download trends and adoption metrics
• Maintenance: release frequency and activity
• Community: contributor activity and issue responsiveness

16. Do not trust the official npmjs.org registry

[!WARNING] The npmjs.org website presents an incomplete and potentially misleading view of npm package metadata, which can create a false sense of security when evaluating packages.

The official npmjs.org registry website does not represent npm package information in full completeness. For example, the npmjs.org website omits Git and HTTPS-based dependencies even when they are declared in a package's package.json file. This means a package may have non-registry dependencies that are invisible to users browsing the registry website.

Furthermore, it has been demonstrated that the source code displayed on the npmjs.org website can drift from the actual tarball that gets installed when running npm install. This means the code you review on the website may not be what ends up on your machine.

[!TIP] Security Best Practice: Do not rely solely on the npmjs.org website to evaluate a package's dependencies or source code. Always inspect the actual installed package contents and use dedicated security tools to audit packages before use.

[!NOTE] How to implement?

Inspect the actual contents of a published tarball before installation:

$ npm pack <package-name> --dry-run

Or review the unpacked tarball contents:

$ npm pack <package-name>
$ tar -tzf <package-name>-<version>.tgz

Use npq (see section 4.1) to audit packages before installation, as it consults multiple security data sources beyond what npmjs.org displays.

17. Prevent dependency confusion attacks

[!WARNING] If your organisation uses a private npm registry alongside the public npmjs.org registry, an attacker can publish a same-named package to the public registry with a higher version number, causing your package manager to install the malicious public version instead of your internal package.

In 2021, security researcher Alex Birsan demonstrated⁸ how dependency confusion attacks could compromise major companies including Apple, Microsoft, and PayPal by publishing public npm packages with the same names as internal private packages. When a package manager resolves an unscoped name, it checks the public registry by default — and prefers the highest available semver version, regardless of source.

This attack remains viable because npm has no protocol-level mechanism linking private registry namespaces to public registry namespaces. Any unscoped private package name can be claimed on the public registry by anyone.

[!TIP] Security Best Practice: Use scoped package names (@yourorg/package-name) for all internal packages and configure your .npmrc to route your organisation's scope exclusively to your private registry.

[!NOTE] How to implement?

Step 1: Use scoped names for all internal packages. In each internal package's package.json:

{
  "name": "@yourcompany/my-internal-tool"
}

Step 2: Configure .npmrc at the project root (and commit it to version control) to route your scope to your private registry:

@yourcompany:registry=https://npm.yourcompany.com/

This ensures that @yourcompany/* packages are only ever resolved from your private registry, while all other packages resolve from the public registry as normal.

Important: Only put registry URLs in the committed .npmrc. Never commit authentication tokens — keep credentials in a user-level ~/.npmrc or inject them via environment variables (e.g. NPM_TOKEN) in CI. See section 9 for broader guidance on secrets management.

Why scoped names are essential

Unscoped private package names (e.g. my-company-utils) are inherently vulnerable because:

• Anyone can publish that exact name to the public npm registry
• npm will resolve the highest semver version across all configured registries
• There is no way to "reserve" an unscoped name on the public registry without publishing to it

Scoped packages (@yourcompany/utils) mitigate this because scopes on npmjs.org are tied to npm organisations, preventing others from publishing under your scope.

pnpm and Yarn registry scoping

The .npmrc registry scoping approach works across package managers:

pnpm: Reads .npmrc and supports the same per-scope registry configuration.

Yarn (v2+): Uses .yarnrc.yml instead:

npmScopes:
  yourcompany:
    npmRegistryServer: "https://npm.yourcompany.com/"

Additional mitigations

• Claim your internal package names on the public registry: Publish placeholder packages to npmjs.org for any unscoped internal names you cannot immediately migrate to scoped names.
• Use lockfile-lint (see section 5) to verify that resolved package URLs point to expected registries.
• Enable blockExoticSubdeps in pnpm (see section 5) to prevent transitive dependencies from pulling packages from unexpected sources.

FAQ

Q. How to reconcile security fixes with minimum release age?

Question: The scenario is where a project enforces a package freshness policy such as pnpm's minimumReleaseAge or npm's min-release-age directives. Yet, some of the packages used in a project may receive security fixes that need to be rushed (and shouldn't wait the time threshold such as 7 days or more until a new version for the package is installed). What is the recommended workflow to support that?

Answer: The following workflows are supported to address this issue:

1. pnpm has built-in capabilities to address this by running pnpm audit --fix which maintains the package freshness policy but allows exception for where a fix is required to upgrade a package, which then updates the pnpm-workspace.yaml file with specific exclusions for the package with the freshness override.
2. Renovate has support for pnpm's package freshness policy and when packages are upgraded for a fix, the pnpm-workspace.yaml file will get updated with exclusions for the updated package.

Contributing

Please consult CONTRIBUTING for guidelines on contributing to this project.

Author

npm Security Best Practices © Liran Tal, Released under Apache 2.0 License.