Join our Newsletter — 33% off our NHI Course
Home› Guides› npm Install-Time Security Guide: Script Allowlists, Release Cooldowns,…
Guide Software & AI Supply Chain

npm Install-Time Security Guide: Script Allowlists, Release Cooldowns, Lockfiles and Registry Config

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 27 October 2026 14 min read
On this page

Running npm install executes code from every package in the dependency tree that declares an install script, with the full permissions of the developer or CI job that ran it, before anyone has imported a line. That is how the Shai-Hulud worm and its successors stole npm, GitHub and cloud credentials from laptops and runners and then used them to republish more packages. The defences have improved sharply in 2026: npm 12 blocks dependency install scripts unless the project approves them, pnpm, Yarn and Bun ship similar allowlists, and all four can refuse versions that are too new. This guide covers what runs at install time, how to configure script allowlists and release-age cooldowns in each package manager, lockfile discipline, registry and dependency source settings, and how to keep credentials out of reach of install-time code. It is for developers, build engineers and platform teams who install JavaScript dependencies, and reflects package manager documentation read on 27 October 2026.

Key takeaways

  • Install scripts are remote code execution by design. preinstall, install and postinstall run arbitrary commands, and a binding.gyp file triggers a native build even without a declared script.
  • Default-deny is now available everywhere. npm 12's allowScripts, pnpm's allowBuilds with strictDepBuilds, Yarn's enableScripts and Bun's trustedDependencies all let only reviewed packages run scripts. Use them, and pin approvals to versions.
  • A cooldown stops most worms. Malicious versions are usually found and removed within hours to days, so min-release-age, minimumReleaseAge or npmMinimalAgeGate keep you from installing them while they are live.
  • Frozen lockfiles stop drift, not poisoning. npm ci installs exactly what the lockfile says, so review lockfile changes as code, and prefer tools that re-verify lockfile entries.
  • Keep secrets away from installs. Run dependency installs in a step with no publish tokens, cloud credentials or write-capable CI tokens in its environment or files.

What runs when you install a package

npm's scripts documentation lists the lifecycle events that run during npm install and npm ci. Each one can execute any command the package author chooses.

TriggerWhen it runsSecurity note
preinstallBefore dependencies are fetched or unpackedRuns earliest, with the job's environment; the usual first stage for credential stealers
install, postinstallAfter the package is placed in node_modulesMost common hook in malicious packages; also legitimately used to download or build native binaries
binding.gyp with no install scriptnpm defaults install to node-gyp rebuildCompiles native code, so it counts as install-time execution
prepare for git dependenciesnpm installs the git package's dependencies and devDependencies, runs prepare, then packs itPulls a second dependency tree and runs its code; npm 12 blocks git dependencies by default
Explicit npm run, npm test, npxWhen invokedNot covered by install-script controls; npx and global installs need their own allowlist

Install scripts receive the full process environment, so anything in environment variables, ~/.npmrc, cloud CLI configuration, SSH agents or the CI workspace is readable. The Shai-Hulud npm Worm, First Wave ran a bundled script at install time that collected environment variables, cloud secret manager contents and tokens found on disk, then used each npm token to publish infected versions of the owner's other packages. In ATT&CK terms this is T1195.001 Compromise Software Dependencies and Development Tools followed by T1552.001 Credentials In Files. See the Shai-Hulud npm Worm Guide for the campaign.

Script allowlists by package manager

The old advice was to set ignore-scripts=true and live with broken native modules. Every major client now offers an allowlist instead, and most deny by default.

ClientDefault for dependency scriptsAllowlist mechanismNotes
npm 12 (12.0.0 released 8 July 2026)Blocked unless approvedallowScripts in the root package.json, maintained with npm approve-scripts and npm deny-scriptsApprovals are pinned to pkg@version by default; denials (false) always win; run npm rebuild after approving
npm 11 and earlierRunignore-scripts=true in .npmrc, or a plugin such as @lavamoat/allow-scripts as OWASP describesUpgrade path: install npm 12 explicitly if your Node.js release bundles an older npm
pnpm (current docs, v12)Disallowed and treated as unreviewed; strictDepBuilds defaults to true, so the install failsallowBuilds map in pnpm-workspace.yaml with true or false per package or version range; pnpm approve-buildsonlyBuiltDependencies and neverBuiltDependencies were removed in v11 and replaced by allowBuilds; git dependencies need URL or commit keys
Yarn (Berry)Current documentation lists enableScripts default false for third-party packages; workspace scripts still rundependenciesMeta to control scripts per packageCheck the default on your Yarn version before relying on it
BunNot run, except a curated default list of popular npm packagestrustedDependencies array in package.jsonThe default list applies only to registry packages; file: and git: sources must be listed explicitly to prevent name spoofing

Operating an allowlist well

  • Review before approving: npm approve-scripts --allow-scripts-pending lists packages whose scripts were skipped without changing anything. Read what each script does; many packages only need their script for optional features.
  • Keep approvals pinned: npm writes [email protected] entries by default, so a new version of an approved package must be reviewed again. Name-only approvals (--no-allow-scripts-pin) let a hijacked future version run.
  • Record denials: a false entry stops the package being offered for approval again and documents the decision. pnpm's allowBuilds and newer permissions map work the same way.
  • Do not make the escape hatch permanent: npm's --dangerously-allow-all-scripts and pnpm's dangerouslyAllowAllBuilds exist for migration; npm describes its use as "strongly discouraged".
  • Cover one-off contexts: npx, npm exec and npm install -g have no project package.json, so npm uses the allow-scripts config (for example npm config set allow-scripts=sharp --location=user). Passing --allow-scripts on a project install is an error by design.
  • Remember what allowlists do not cover: malicious code in a package's runtime files still runs when your application or tests import it. Allowlists move execution from install time to a point where other controls (sandboxing, tests, review) can act.

Release-age cooldowns

Worms depend on speed: a compromised version is published and installed by thousands of pipelines before anyone notices. The OpenSSF Concise Guide recommends a cooldown of typically around three days for updates without known vulnerabilities, and pnpm's documentation notes that most malicious releases are discovered and removed within an hour.

ClientSettingDefaultExceptions
npmmin-release-age=<days> or before=<date>Not setmin-release-age-exclude (names or globs)
pnpmminimumReleaseAge (minutes)1440 (one day), applied to transitive dependencies; strict only when you set it explicitlyminimumReleaseAgeExclude by name, pattern or exact version
YarnnpmMinimalAgeGateDocumented as 1wPer-package configuration
  • Pick a window you can live with: three to seven days catches most campaigns we have recorded while keeping dependencies reasonably fresh.
  • Plan for urgent security fixes: npm notes that a cooldown can stop npm audit fix installing a patched version, in which case it warns and exits non-zero. Add the package to the exclude list for that fix rather than disabling the cooldown.
  • Exempt your own scope carefully: excluding @yourorg/* is common, but it means a compromise of your own publishing path is installed immediately.
  • Align automated update tools: configure Dependabot or Renovate with a matching minimum age so bots do not open, and auto-merge, pull requests for versions your installer would reject. See the Dependency Update Automation Guide.

Lockfiles and frozen installs

A lockfile records the exact version, resolved location and integrity hash (an SRI sha512 string) of every package. It only protects you if installs are forced to follow it.

  • Use frozen installs in CI: npm ci requires a package-lock.json, fails if it does not match package.json, deletes any existing node_modules and never writes either file. The equivalents are pnpm install --frozen-lockfile and Yarn's immutable installs, which Yarn documents as the default on CI.
  • Review lockfile diffs: a pull request that changes resolved URLs to an unfamiliar host, adds git or tarball sources, or bumps many transitive packages at once deserves scrutiny. Lockfiles are large and rarely read, which makes them a good hiding place.
  • Prefer clients that re-verify: pnpm re-applies minimumReleaseAge and trustPolicy to every lockfile entry unless trustLockfile is true, and its documentation says to leave that false whenever outside collaborators can edit the lockfile. Yarn's enableHardenedMode validates lockfile content against the registry and turns on automatically for pull requests from public repositories.
  • Keep resolved fields: npm cannot pin script approvals for entries without a resolved URL, so avoid lockfile options that strip it.
  • Do not commit node_modules or rely on caches across trust boundaries: a cache written by an untrusted job can feed a trusted one.

Registry configuration and dependency sources

Where packages come from matters as much as what runs. npm 12 tightened defaults for non-registry sources.

npm settingDefault (npm 12)What it controlsRecommendation
allow-gitnoneDependencies from git references, which run git against remote repositoriesKeep none; use root only if your own package.json needs a git dependency
allow-remotenoneTarball URL dependencies on hosts other than the configured registryKeep none; use replace-registry-host if your registry serves tarballs from another host
allow-file, allow-directoryallLocal tarballs and directoriesSet root in CI so transitive packages cannot point at local paths
@yourorg:registry=Not setWhich registry serves a scopeMap every internal scope to your private registry to prevent dependency confusion
strict-ssltrueTLS validation to registriesNever disable; add corporate CAs with cafile instead
  • pnpm equivalent: blockExoticSubdeps (default true) allows git and tarball URL sources only for direct dependencies; transitive packages must come from the registry or other trusted sources.
  • Dependency confusion: OWASP's npm cheat sheet advises scoped names for internal packages, scope-to-registry mapping in .npmrc, and reserving internal names on the public registry. See the Malicious Package and Dependency Confusion Guide.
  • Use a proxy registry with policy: a repository manager in front of the public registry can enforce age gates, block known-malicious versions and keep an audit trail of what was fetched.
  • Typosquats and hallucinated names: allowlists do not help if you approve the wrong package. See the Slopsquatting and Package Hallucination Guide.

Where identity fits: keeping credentials out of reach

Install-time malware is a credential thief first. The question is what it can find.

  1. Separate install from privileged steps: run npm ci in a job or container with no publish tokens, cloud credentials or write-capable GITHUB_TOKEN. Pass built artefacts to later jobs that hold credentials.
  2. Use read-only tokens for private registries: scope them to the packages needed, inject them only for the install step, and never write them to a persistent ~/.npmrc. See the npm Tokens Security Guide.
  3. Remove publish tokens entirely: trusted publishing removes the most valuable thing a worm can steal. See the npm Trusted Publishing and Provenance Guide.
  4. Use ephemeral runners and restrict egress so stolen data has nowhere to go and nothing persists between jobs.
  5. Protect developer machines: install in dev containers or VMs for untrusted projects, keep cloud credentials short-lived, and avoid long-lived tokens in shell profiles. See the Developer Workstation and IDE Security Guide.

Rolling out install-time controls

  1. Inventory: list projects, package managers and versions, and which dependencies declare install scripts (npm approve-scripts --allow-scripts-pending or pnpm's ignored builds report).
  2. Pilot in audit mode: on npm 11, run CI once with --ignore-scripts to see what breaks; on npm 12 or pnpm, the install output lists skipped scripts. Fix or approve each.
  3. Commit the policy: allowScripts, allowBuilds, trustedDependencies and cooldown settings go into the repository so every developer and runner shares them.
  4. Enforce in CI: frozen installs, the cooldown, strict build checks and source restrictions, with the install step isolated from secrets.
  5. Extend to developers: user-level .npmrc settings for npx and global installs.
  6. Rollback: if a legitimate package breaks, approve it with a pinned entry rather than turning the policy off; keep the previous lockfile and configuration in version control so a revert is one commit.

Decision guidance: on npm, upgrading to npm 12 gives default-deny with the least effort; teams that cannot upgrade yet should use ignore-scripts=true plus explicit npm rebuild for the few packages that need it. pnpm suits monorepos that want strict failure on unreviewed builds and lockfile re-verification. Small teams can rely on client defaults plus a cooldown; large organisations should add a proxy registry with central policy and a shared configuration package.

Detection and measurement

SignalSourceMeaning
New entries in skipped-script or ignored-build reportsInstall output in CI logsA dependency newly added or updated an install script
Outbound connections during dependency installRunner egress logs, network policy denialsExfiltration or second-stage download
Processes reading ~/.npmrc, cloud credential files or running secret scanners during installEDR on developer machines and self-hosted runnersCredential harvesting
New public repositories or workflows created by a developer's tokenGitHub audit logWorm behaviour seen in Shai-Hulud
Lockfile changes adding git, tarball or new registry hostsPull request diff checksSource manipulation or dependency confusion
  • Allowlist coverage: share of repositories with a committed default-deny script policy. Target 100%.
  • Approved scripts per project: trend downwards as packages that do not need scripts are denied.
  • Cooldown coverage: share of CI pipelines enforcing a minimum release age of at least three days.
  • Secret-free install steps: share of pipelines where the install step has no publish or cloud credentials.
  • Frozen install rate: share of CI installs using npm ci or an equivalent.

Common failure patterns

  • Approving everything to unblock a build: npm approve-scripts --all or a permanent dangerouslyAllowAllBuilds turns default-deny back into default-allow.
  • Name-only approvals: an approval that covers any future version runs the hijacked version too.
  • Installing in the same job that publishes or deploys: install-time code inherits every secret the job holds, which is how worms obtain publish tokens.
  • Cooldowns with broad exclusions: excluding popular frameworks or your whole organisation scope removes protection where compromise is most likely.
  • Trusting the lockfile from an untrusted pull request: frozen installs faithfully install whatever a poisoned lockfile specifies.
  • Forgetting npx and global tools: one-off executions bypass project policy unless user-level configuration covers them.

Lessons from incidents

The 2025 and 2026 npm worms share a pattern: a stolen maintainer token publishes a version with an install-time payload, the payload steals more tokens from whoever installs it, and the cycle repeats within hours. Campaigns recorded in our breach database, including the first Shai-Hulud wave and the Shai-Hulud npm Worm 2025 follow-up, whose preinstall script launched a payload on developer machines and CI runners and created more than 25,000 exfiltration repositories, relied on three things this guide addresses: install scripts that ran without review, fresh versions installed immediately, and credentials available to the installing process. Removing any one of the three breaks the chain for your organisation.

Framework mapping

FrameworkReferenceInstall-time control
NIST SP 800-53 Rev. 5CM-7 Least Functionality, CM-11 User-installed SoftwareDefault-deny install scripts, restricted dependency sources
NIST SP 800-53 Rev. 5SR-3 Supply Chain Controls and Processes, SR-11 Component Authenticity, SI-7Cooldowns, proxy registry policy, lockfile integrity hashes
NIST CSF 2.0ID.RA-09, PR.PS-02Assess components before use; maintain dependencies with risk-based timing
MITRE ATT&CK v20T1195.001, T1195.002, T1059.007, T1552.001Malicious dependencies, JavaScript execution at install, credential theft from files
OWASPNPM Security Cheat SheetLockfile enforcement, script control, dependency confusion defences

Practitioner checklist

  • Upgrade to npm 12 or configure an equivalent default-deny script policy in pnpm, Yarn or Bun.
  • Commit the script allowlist with version-pinned approvals and explicit denials, and review pending scripts before approving.
  • Set a release-age cooldown of three to seven days in the client and in dependency update bots, with narrow, documented exclusions.
  • Use frozen installs (npm ci, --frozen-lockfile, immutable installs) in every CI pipeline.
  • Review lockfile changes and enable lockfile re-verification where your client supports it.
  • Keep allow-git and allow-remote at none, set allow-file and allow-directory to root in CI, and map internal scopes to your private registry.
  • Run installs in steps with no publish tokens, cloud credentials or write-capable CI tokens, on ephemeral runners with restricted egress.
  • Configure user-level allowlists for npx and global installs on developer machines.
  • Alert on network activity and credential file access during installs, and on lockfile source changes.

Standards and references

Related NHI Mgmt Group resources: Node.js Security Guide · Shai-Hulud npm Worm Guide · Malicious Open Source Package Response Playbook · Software Supply Chain Security Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 27 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.