Fix Linux Bubblewrap setup

- Prefer an existing `bubblewrap` before installing anything.
- Use Homebrew before `apt-get` so local and container installs stay
  consistent.
- Keep `apt-get` as a final GitHub-hosted Ubuntu fallback for missing
  or unusable `bwrap` executables.
- Symbolise API dependency bounds before runtime casts so the
  Homebrew fallback can load `bubblewrap` from API data.
- Document the temporary `test-bot` default until Linux sandboxing is
  forced on in a later release.

Author: MikeMcQuaid

.github/workflows/tests.yml

@@ -265,16 +265,9 @@ jobs:
         if: matrix.name == 'tests (online)'
         uses: Homebrew/actions/cache-homebrew-prefix@main
         with:
-          install: bubblewrap curl subversion
+          install: curl subversion
           workflow-key: tests-tests-online
 
-      - name: Install brew tests Linux dependencies
-        if: matrix.name == 'tests (Linux)'
-        uses: Homebrew/actions/cache-homebrew-prefix@main
-        with:
-          install: bubblewrap
-          workflow-key: tests-tests-linux
-
       - name: Install brew tests macOS dependencies
         if: runner.os != 'Linux'
         uses: Homebrew/actions/cache-homebrew-prefix@main
@@ -357,7 +350,6 @@ jobs:
           # Slimmed down version from the Homebrew Dockerfile
           apt-get update
           apt-get install -y --no-install-recommends \
-            bubblewrap \
             bzip2 \
             ca-certificates \
             curl \

Library/Homebrew/api/formula/formula_struct_generator.rb

@@ -223,8 +223,11 @@ def symbolize_dependency_hash(hash)
           hash = hash.dup
 
           if (uses_from_macos_bounds = hash["uses_from_macos_bounds"])
-            uses_from_macos_bounds = T.cast(uses_from_macos_bounds, T::Array[T::Hash[Symbol, Symbol]])
-            hash["uses_from_macos_bounds"] = uses_from_macos_bounds.map(&:deep_symbolize_keys)
+            uses_from_macos_bounds =
+              T.cast(uses_from_macos_bounds, T::Array[T::Hash[T.any(String, Symbol), T.any(String, Symbol)]])
+            hash["uses_from_macos_bounds"] = uses_from_macos_bounds.map do |bound|
+              bound.to_h { |key, value| [key.to_sym, value.to_sym] }
+            end
           end
 
           hash.transform_values do |deps|

Library/Homebrew/extend/os/linux/sandbox.rb

@@ -28,6 +28,9 @@ module Sandbox
         /usr/bin
         /bin
       ].freeze, T::Array[String])
+      HOMEBREW_BUBBLEWRAP_PATHS = T.let([
+        "#{HOMEBREW_PREFIX}/bin",
+      ].freeze, T::Array[String])
       class SysctlSetting < T::Struct
         const :assignment, String
         const :description, T::Array[String]
@@ -60,7 +63,7 @@ class SysctlSetting < T::Struct
       ].freeze, T::Array[SysctlSetting])
       # `TIOCSCTTY` from `<asm-generic/ioctls.h>`; Ruby does not expose it.
       TIOCSCTTY = 0x540E
-      private_constant :BUBBLEWRAP, :BUBBLEWRAP_TEST_ARGS, :SYSTEM_BUBBLEWRAP_PATHS,
+      private_constant :BUBBLEWRAP, :BUBBLEWRAP_TEST_ARGS, :SYSTEM_BUBBLEWRAP_PATHS, :HOMEBREW_BUBBLEWRAP_PATHS,
                        :SysctlSetting, :SANDBOX_SYSCTL_SETTINGS, :TIOCSCTTY
 
       sig { returns(::PATH) }
@@ -123,7 +126,7 @@ def system_bubblewrap_paths
 
         sig { returns(::PATH) }
         def executable_candidate_paths
-          PATH.new(system_bubblewrap_paths, super)
+          PATH.new(HOMEBREW_BUBBLEWRAP_PATHS, system_bubblewrap_paths, super)
         end
 
         sig { returns(::PATH) }
@@ -148,14 +151,27 @@ def ensure_sandbox_installed!(install_from_tests: false)
           return if ENV["HOMEBREW_INSTALLING_BUBBLEWRAP"]
           return if bubblewrap_executable
 
-          require "exceptions"
-          require "formula"
-          with_env(HOMEBREW_INSTALLING_BUBBLEWRAP: "1") do
-            ::Formula["bubblewrap"].ensure_installed!(reason: "Linux sandboxing")
+          begin
+            require "exceptions"
+            require "formula"
+            with_env(HOMEBREW_INSTALLING_BUBBLEWRAP: "1") do
+              ::Formula["bubblewrap"].ensure_installed!(reason: "Linux sandboxing")
+            end
+            reset_state!
+            return if bubblewrap_executable
+          rescue ::FormulaUnavailableError
+            nil
           end
+
+          return unless GitHub::Actions.env_set?
+          return unless ENV.fetch("HOMEBREW_GITHUB_HOSTED_RUNNER", nil)
+          return unless which("apt-get")
+
+          ohai "Installing Bubblewrap..."
+          command = ["apt-get", "install", "--yes", "bubblewrap"]
+          command.unshift("sudo") unless Process.euid.zero?
+          system(*command)
           reset_state!
-        rescue ::FormulaUnavailableError
-          nil
         end
 
         sig { returns(T::Boolean) }
@@ -197,21 +213,9 @@ def configuration_command_messages
 
         sig { void }
         def configure!
-          unless (bubblewrap = bubblewrap_executable)
-            if GitHub::Actions.env_set? &&
-               ENV["RUNNER_ENVIRONMENT"] == "github-hosted" &&
-               ENV.fetch("ImageOS", "").start_with?("ubuntu")
-              ohai "Installing Bubblewrap..."
-              system "sudo", "apt-get", "install", "--yes", "bubblewrap"
-              reset_state!
-              bubblewrap = bubblewrap_executable
-            end
-
-            unless bubblewrap
-              ensure_sandbox_installed!(install_from_tests: true)
-              bubblewrap = bubblewrap_executable
-            end
-            unless bubblewrap
+          unless bubblewrap_executable
+            ensure_sandbox_installed!(install_from_tests: true)
+            unless bubblewrap_executable
               reset_state!
               return
             end
@@ -259,10 +263,10 @@ def compute_state
           bubblewraps = bubblewrap_executables
           return :missing if bubblewraps.empty?
 
-          bubblewrap = bubblewraps.find { |candidate| executable_usable?(candidate) }
-          return :setuid if bubblewrap.nil?
+          bubblewraps = bubblewraps.select { |candidate| executable_usable?(candidate) }
+          return :setuid if bubblewraps.empty?
 
-          return :available if bubblewrap_sandbox_available?(bubblewrap)
+          return :available if bubblewraps.any? { |candidate| bubblewrap_sandbox_available?(candidate) }
 
           :unavailable
         end

Library/Homebrew/test/sandbox_linux_spec.rb

@@ -38,7 +38,8 @@ def executable_candidate_paths = test_executable_candidate_paths
       allow(File).to receive(:stat).with(setuid_bubblewrap).and_return(instance_double(File::Stat, setuid?: true))
     end
 
-    it "skips setuid bubblewrap candidates" do
+    it "searches Homebrew Bubblewrap before system Bubblewrap and skips setuid candidates" do
+      expect(klass.executable_candidate_paths.to_a).to start_with("#{HOMEBREW_PREFIX}/bin", "/usr/bin", "/bin")
       expect(sandbox_class.bubblewrap_executable).to eq(usable_bubblewrap)
     end
 
@@ -62,6 +63,8 @@ def executable_candidate_paths = test_executable_candidate_paths
     end
     let(:bubblewrap_dir) { mktmpdir }
     let(:bubblewrap) { bubblewrap_dir/"bwrap" }
+    let(:fallback_bubblewrap_dir) { mktmpdir }
+    let(:fallback_bubblewrap) { fallback_bubblewrap_dir/"bwrap" }
 
     before do
       FileUtils.touch bubblewrap
@@ -103,6 +106,43 @@ def executable_candidate_paths = test_executable_candidate_paths
       expect(sandbox_class.failure_reason).to be_nil
     end
 
+    it "probes later usable Bubblewrap candidates if earlier candidates fail" do
+      FileUtils.touch fallback_bubblewrap
+      FileUtils.chmod "+x", fallback_bubblewrap
+      sandbox_class.test_executable_candidate_paths = PATH.new(bubblewrap_dir, fallback_bubblewrap_dir)
+
+      expect(sandbox_class).to receive(:system).with(
+        bubblewrap.to_s,
+        "--unshare-user",
+        "--unshare-ipc",
+        "--unshare-pid",
+        "--unshare-uts",
+        "--unshare-cgroup-try",
+        "--ro-bind", "/", "/",
+        "--proc", "/proc",
+        "--dev", "/dev",
+        "true",
+        out: File::NULL,
+        err: File::NULL
+      ).and_return(false)
+      expect(sandbox_class).to receive(:system).with(
+        fallback_bubblewrap.to_s,
+        "--unshare-user",
+        "--unshare-ipc",
+        "--unshare-pid",
+        "--unshare-uts",
+        "--unshare-cgroup-try",
+        "--ro-bind", "/", "/",
+        "--proc", "/proc",
+        "--dev", "/dev",
+        "true",
+        out: File::NULL,
+        err: File::NULL
+      ).and_return(true)
+
+      expect(sandbox_class.available?).to be(true)
+    end
+
     it "reports setuid bubblewrap candidates" do
       allow(File).to receive(:stat).and_call_original
       allow(File).to receive(:stat).with(bubblewrap).and_return(instance_double(File::Stat, setuid?: true))
@@ -125,7 +165,7 @@ def executable_candidate_paths = test_executable_candidate_paths
     let(:sandbox_class) { Class.new(klass) }
 
     around do |example|
-      with_env(GITHUB_ACTIONS: nil, ImageOS: nil, RUNNER_ENVIRONMENT: nil) { example.run }
+      with_env(GITHUB_ACTIONS: nil, HOMEBREW_GITHUB_HOSTED_RUNNER: nil) { example.run }
     end
 
     def expect_sandbox_configuration_command(sandbox_class, assignment, result:)
@@ -164,39 +204,130 @@ def expect_sandbox_configuration_command(sandbox_class, assignment, result:)
       sandbox_class.configure!
     end
 
-    it "installs Bubblewrap with apt-get on default GitHub Actions Ubuntu runners" do
+    it "installs Bubblewrap and configures Linux sandbox sysctls" do
       expect(sandbox_class).to receive(:bubblewrap_executable)
         .twice
-        .and_return(nil, Pathname("/usr/bin/bwrap"))
-      expect(sandbox_class).to receive(:ohai).with("Installing Bubblewrap...")
-      expect(sandbox_class).to receive(:system)
-        .with("sudo", "apt-get", "install", "--yes", "bubblewrap")
-        .and_return(true)
-      expect(sandbox_class).not_to receive(:ensure_sandbox_installed!)
+        .and_return(nil, Pathname(HOMEBREW_PREFIX/"bin/bwrap"))
+      expect(sandbox_class).to receive(:ensure_sandbox_installed!)
+        .with(install_from_tests: true)
       expect(sandbox_class).to receive(:ohai).with("Configuring Bubblewrap...").ordered
       expect_sandbox_configuration_command(sandbox_class, "kernel.unprivileged_userns_clone=1", result: true)
       expect_sandbox_configuration_command(sandbox_class, "user.max_user_namespaces=28633", result: true)
       expect_sandbox_configuration_command(sandbox_class, "kernel.apparmor_restrict_unprivileged_userns=0",
                                            result: false)
 
-      with_env(GITHUB_ACTIONS: "true", ImageOS: "ubuntu24", RUNNER_ENVIRONMENT: "github-hosted") do
-        sandbox_class.configure!
-      end
+      sandbox_class.configure!
     end
+  end
 
-    it "installs Bubblewrap and configures Linux sandbox sysctls" do
+  describe "::ensure_sandbox_installed!" do
+    let(:sandbox_class) { Class.new(klass) }
+
+    around do |example|
+      with_env(GITHUB_ACTIONS: nil, HOMEBREW_GITHUB_HOSTED_RUNNER: nil,
+               HOMEBREW_INSTALLING_BUBBLEWRAP: nil, HOMEBREW_TESTS: nil) { example.run }
+    end
+
+    before do
+      allow(Homebrew::EnvConfig).to receive(:sandbox_linux?).and_return(true)
+    end
+
+    it "does nothing when Homebrew Bubblewrap is already available" do
+      expect(sandbox_class).to receive(:bubblewrap_executable)
+        .once
+        .and_return(Pathname(HOMEBREW_PREFIX/"bin/bwrap"))
+      expect(Formula).not_to receive(:[])
+      expect(sandbox_class).not_to receive(:which)
+      expect(sandbox_class).not_to receive(:system)
+
+      sandbox_class.ensure_sandbox_installed!
+    end
+
+    it "does nothing when system Bubblewrap is already available" do
+      expect(sandbox_class).to receive(:bubblewrap_executable)
+        .once
+        .and_return(Pathname("/usr/bin/bwrap"))
+      expect(Formula).not_to receive(:[])
+      expect(sandbox_class).not_to receive(:which)
+      expect(sandbox_class).not_to receive(:system)
+
+      sandbox_class.ensure_sandbox_installed!
+    end
+
+    it "installs Bubblewrap with Homebrew before trying apt-get on GitHub Actions" do
       expect(sandbox_class).to receive(:bubblewrap_executable)
         .twice
         .and_return(nil, Pathname(HOMEBREW_PREFIX/"bin/bwrap"))
-      expect(sandbox_class).to receive(:ensure_sandbox_installed!)
-        .with(install_from_tests: true)
-      expect(sandbox_class).to receive(:ohai).with("Configuring Bubblewrap...").ordered
-      expect_sandbox_configuration_command(sandbox_class, "kernel.unprivileged_userns_clone=1", result: true)
-      expect_sandbox_configuration_command(sandbox_class, "user.max_user_namespaces=28633", result: true)
-      expect_sandbox_configuration_command(sandbox_class, "kernel.apparmor_restrict_unprivileged_userns=0",
-                                           result: false)
+      expect(Formula).to receive(:[]).with("bubblewrap")
+                                     .and_return(instance_double(Formula, ensure_installed!: nil))
+      expect(sandbox_class).not_to receive(:which)
+      expect(sandbox_class).not_to receive(:system)
 
-      sandbox_class.configure!
+      with_env(GITHUB_ACTIONS: "true", HOMEBREW_GITHUB_HOSTED_RUNNER: "1") do
+        sandbox_class.ensure_sandbox_installed!
+      end
+    end
+
+    it "falls back to sudo apt-get on GitHub Actions Ubuntu when Homebrew Bubblewrap is unavailable" do
+      expect(sandbox_class).to receive(:bubblewrap_executable)
+        .twice
+        .and_return(nil)
+      expect(Formula).to receive(:[]).with("bubblewrap")
+                                     .and_return(instance_double(Formula, ensure_installed!: nil))
+      expect(sandbox_class).to receive(:which).with("apt-get").and_return(Pathname("/usr/bin/apt-get"))
+      expect(Process).to receive(:euid).and_return(1000)
+      expect(sandbox_class).to receive(:ohai).with("Installing Bubblewrap...")
+      expect(sandbox_class).to receive(:system)
+        .with("sudo", "apt-get", "install", "--yes", "bubblewrap")
+        .and_return(true)
+
+      with_env(GITHUB_ACTIONS: "true", HOMEBREW_GITHUB_HOSTED_RUNNER: "1") do
+        sandbox_class.ensure_sandbox_installed!
+      end
+    end
+
+    it "falls back to apt-get as root on GitHub Actions Ubuntu when Homebrew Bubblewrap is unavailable" do
+      expect(sandbox_class).to receive(:bubblewrap_executable)
+        .twice
+        .and_return(nil)
+      expect(Formula).to receive(:[]).with("bubblewrap")
+                                     .and_return(instance_double(Formula, ensure_installed!: nil))
+      expect(sandbox_class).to receive(:which).with("apt-get").and_return(Pathname("/usr/bin/apt-get"))
+      expect(Process).to receive(:euid).and_return(0)
+      expect(sandbox_class).to receive(:ohai).with("Installing Bubblewrap...")
+      expect(sandbox_class).to receive(:system)
+        .with("apt-get", "install", "--yes", "bubblewrap")
+        .and_return(true)
+
+      with_env(GITHUB_ACTIONS: "true", HOMEBREW_GITHUB_HOSTED_RUNNER: "1") do
+        sandbox_class.ensure_sandbox_installed!
+      end
+    end
+
+    it "does not fall back to apt-get outside GitHub Actions Ubuntu" do
+      expect(sandbox_class).to receive(:bubblewrap_executable)
+        .twice
+        .and_return(nil, nil)
+      expect(Formula).to receive(:[]).with("bubblewrap")
+                                     .and_return(instance_double(Formula, ensure_installed!: nil))
+      expect(sandbox_class).not_to receive(:which)
+      expect(sandbox_class).not_to receive(:system)
+
+      with_env(GITHUB_ACTIONS: "true") do
+        sandbox_class.ensure_sandbox_installed!
+      end
+    end
+
+    it "does not fall back to apt-get outside GitHub Actions" do
+      expect(sandbox_class).to receive(:bubblewrap_executable)
+        .twice
+        .and_return(nil, nil)
+      expect(Formula).to receive(:[]).with("bubblewrap")
+                                     .and_return(instance_double(Formula, ensure_installed!: nil))
+      expect(sandbox_class).not_to receive(:which)
+      expect(sandbox_class).not_to receive(:system)
+
+      sandbox_class.ensure_sandbox_installed!
     end
   end
 

Library/Homebrew/test/test_bot_spec.rb

@@ -17,6 +17,15 @@
       allow(Homebrew::EnvConfig).to receive(:sandbox_linux?).and_return(true)
     end
 
+    it "enables the Linux sandbox for GitHub Actions developers" do
+      allow(Homebrew::EnvConfig).to receive(:sandbox_linux?).and_call_original
+      expect(klass).to receive(:configure_sandbox!).and_return(true)
+
+      with_env(HOMEBREW_DEVELOPER: "1", HOMEBREW_SANDBOX_LINUX: nil) do
+        klass.setup_github_actions_sandbox!
+      end
+    end
+
     it "configures the Linux sandbox for GitHub Actions" do
       expect(klass).to receive(:configure_sandbox!).and_return(true)
 

Library/Homebrew/test_bot.rb

@@ -38,6 +38,10 @@ def local?(args)
     sig { void }
     def setup_github_actions_sandbox!
       return unless GitHub::Actions.env_set?
+
+      # TODO: odeprecated: force Linux sandbox support on when using `test-bot`.
+      ENV["HOMEBREW_SANDBOX_LINUX"] = "1" if ENV["HOMEBREW_DEVELOPER"].present? &&
+                                             ENV["HOMEBREW_SANDBOX_LINUX"].blank?
       return unless Homebrew::EnvConfig.sandbox_linux?
 
       return if configure_sandbox!