Mehdi Akiki
Published on

npm Install Scripts: What Runs and How to Disable It

Authors
  • Mehdi Akiki avatar
    Name
    Mehdi Akiki
    Twitter

Reference · Through the layers

The CI log says “installing dependencies.” That sounds like copying files. A package can also ask npm to run a program during installation.

Sometimes the program builds a native addon or prepares required files. Sometimes it does much more than you expected. It runs with the permissions and credentials available to the install process.

Before adding another security scanner, I would check one ordinary install. Which scripts execute, and what is available to them at that moment?

Find the package behind the hidden step

Use a disposable CI workspace with the repository's pinned npm version and no deployment credentials. For a normal installation whose lifecycle steps you need to inspect, capture:

npm --version
npm ci --foreground-scripts

The foreground-scripts option makes install scripts share npm's input and output. That makes their package and command easier to spot in the job log. It still executes them, with the permissions of that job. It isn't a harmless preview mode.

When a log points to a package, find its resolved version in the lockfile. A package name alone isn't enough when two versions are installed. Match the location as well, then inspect that exact artifact using the metadata step below. Keep logs access-controlled too: an install script can print available environment values.

Look at the package being installed

npm's lifecycle documentation describes hooks such as preinstall, install, and postinstall. A small package declaration can start a separate program:

{
  "scripts": {
    "postinstall": "node scripts/setup.cjs"
  }
}

The interesting file is now scripts/setup.cjs. Its small entry point might import another file or download a binary. Read far enough to know which work happens, where downloaded data comes from, and whether a checksum is checked.

For one locked package version, a CI inspection can request its metadata without running the package:

npm view "$PACKAGE_SPEC" scripts dist.integrity --json

Set PACKAGE_SPEC to the exact name and version from the lockfile. A result for the current latest release may describe different code. Metadata is a starting point; inspect the actual installed artifact and any files the script loads too.

An empty scripts field isn't the whole check. If a package contains binding.gyp and defines neither install nor preinstall, npm can supply an implicit node-gyp rebuild step. Inspect the package files too; the lifecycle documentation describes that default.

You don't need to read every dependency in one sitting. Start with packages added or updated by the change, then find the ones with lifecycle scripts or binary downloads. Follow the dependency tree so a small direct dependency doesn't hide a much larger install chain.

Try a clean install with scripts disabled

In a disposable CI job without deployment credentials, compare the normal installation with:

npm ci --ignore-scripts

Use the repository's lockfile and npm version. npm ci removes an existing node_modules directory itself. Use a fresh workspace as well so files generated elsewhere in the project and external build caches don't hide what the scripts normally produce.

Some packages will stop working. That can be expected: the script may produce a native library the application needs. Identify that package and the required operation before deciding how to allow it. Turning every script back on avoids the investigation.

The npm ci options also make an important distinction: ignore-scripts doesn't turn an explicitly requested command such as npm run build into a no-op. If your build command runs repository code, that code still runs. This flag is not a general-purpose sandbox.

Keep installation and release authority apart. A package that can execute during installation shouldn't automatically receive a token capable of publishing a release or changing infrastructure. Bring in narrowly scoped credentials only for the step that needs them.

If installation happens inside an agent environment, check that job's sandbox permissions as well. Disabling a hook and limiting the process's access solve different parts of the problem.

A lockfile can pin a harmful version too

A lockfile helps keep versions and integrity information consistent. It doesn't decide whether the selected package should have been trusted. You can faithfully reinstall a harmful version.

During review, look at what changed in the lockfile as well as the application import. Did an update add an install script? Did a binary download move to another host? Did a package name or source unexpectedly change?

Keep a clean record of the artifact used by a release. If an incident is reported later, “we used version 4” is less useful than the exact package version, integrity value, and build that consumed it.

None of this means every install script is suspicious. It means executing it is a permission decision. A required compiler step deserves a known environment and review, just like your own build script.

Read provenance for what it proves

npm provenance links a package to source and build information. The documentation explicitly says it doesn't guarantee the absence of malicious code. A genuine maintainer or authorized workflow can still publish a bad change.

Trusted publishing can reduce reliance on long-lived publishing tokens where the runner and registry support it. Check those requirements against your existing infrastructure. Changing runner policy just to copy an example isn't a security improvement by itself.

These controls answer different questions. Provenance helps establish where an artifact came from. Installation policy decides which code executes. Credential isolation limits what that code can do.

For the next dependency update, inspect the changed package in the same install environment CI uses. Find the programs it starts and which files or credentials they can access. If you allow a required native build, record that decision beside the dependency update so the next reviewer doesn't have to rediscover it.