Add Linux Bubblewrap sandbox

- Use `bwrap` to translate shared sandbox rules into rootless
  namespace execution.
- Gate the backend behind `HOMEBREW_SANDBOX_LINUX` while the Linux
  policy is still experimental.
- Auto-install `bubblewrap` from `homebrew/core` when the sandbox is
  enabled and no system or brewed binary is found.
- Prefer a system `bwrap` (from `ORIGINAL_PATHS`) over a brewed one so
  distribution-provided binaries are used when available.
- Install `bubblewrap` in Linux CI and Docker images so test-bot
  exercises the sandbox path.

Author: MikeMcQuaid

.github/workflows/tests.yml

@@ -290,6 +290,7 @@ jobs:
           HOMEBREW_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           # These cannot be queried at the macOS level on GitHub Actions.
           HOMEBREW_LANGUAGES: en-GB
+          HOMEBREW_SANDBOX_LINUX: ${{ matrix.name == 'tests (Linux)' && '1' || '' }}
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
       - name: Get RSpec JUnit XML filenames
@@ -339,6 +340,7 @@ jobs:
           - name: test-bot (macOS arm64)
             runs-on: macos-26
     env:
+      HOMEBREW_SANDBOX_LINUX: ${{ startsWith(matrix.name, 'test-bot (Linux') && '1' || '' }}
       HOMEBREW_TEST_BOT_ANALYTICS: 1
     steps:
       - name: Install Homebrew and Homebrew's dependencies
@@ -349,6 +351,7 @@ jobs:
           # Slimmed down version from the Homebrew Dockerfile
           apt-get update
           apt-get install -y --no-install-recommends \
+            bubblewrap \
             bzip2 \
             ca-certificates \
             curl \

Dockerfile

@@ -29,6 +29,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
   && retry apt-get update --error-on=any \
   && apt-get install -y --no-install-recommends \
   acl \
+  bubblewrap \
   bzip2 \
   ca-certificates \
   curl \

Library/Homebrew/env_config.rb

@@ -487,6 +487,10 @@ module EnvConfig
         description: "If set, use Pry for the `brew irb` command.",
         boolean:     true,
       },
+      HOMEBREW_SANDBOX_LINUX:                    {
+        description: "If set, use a Linux sandbox for formula installation and testing.",
+        boolean:     true,
+      },
       HOMEBREW_SBOM:                             {
         # odeprecated: edit in 5.2.0
         description: "If set, Homebrew will write SBOM files and run SBOM-related installation logic. " \

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

@@ -0,0 +1,205 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "fileutils"
+require "env_config"
+
+module OS
+  module Linux
+    module Sandbox
+      extend T::Helpers
+
+      requires_ancestor { ::Sandbox }
+
+      BUBBLEWRAP = "bwrap"
+      TIOCSCTTY = 0x540E
+      READ_ONLY_PATHS = T.let(%w[
+        /bin
+        /etc
+        /lib
+        /lib64
+        /opt
+        /sbin
+        /usr
+      ].freeze, T::Array[String])
+      private_constant :BUBBLEWRAP, :TIOCSCTTY, :READ_ONLY_PATHS
+
+      sig { void }
+      def allow_write_temp_and_cache
+        allow_write_path "/tmp"
+        allow_write_path "/var/tmp"
+        allow_write_path HOMEBREW_TEMP
+        allow_write_path HOMEBREW_CACHE
+      end
+
+      sig { void }
+      def allow_cvs
+        cvspass = ::Pathname.new("#{Dir.home(ENV.fetch("USER"))}/.cvspass")
+        allow_write path: cvspass, type: :literal if cvspass.exist?
+      end
+
+      sig { void }
+      def allow_fossil
+        [".fossil", ".fossil-journal"].each do |file|
+          fossil_file = ::Pathname.new("#{Dir.home(ENV.fetch("USER"))}/#{file}")
+          allow_write path: fossil_file, type: :literal if fossil_file.exist?
+        end
+      end
+
+      module ClassMethods
+        extend T::Helpers
+
+        requires_ancestor { T.class_of(::Sandbox) }
+
+        sig { returns(T.nilable(::Pathname)) }
+        def bubblewrap_executable
+          which(BUBBLEWRAP, ORIGINAL_PATHS) || which(BUBBLEWRAP)
+        end
+
+        sig { void }
+        def ensure_bubblewrap_installed!
+          return if ENV["HOMEBREW_INSTALLING_BUBBLEWRAP"]
+          return if bubblewrap_executable
+          return unless CoreTap.instance.installed?
+
+          require "formula"
+          with_env(HOMEBREW_INSTALLING_BUBBLEWRAP: "1") do
+            ::Formula["bubblewrap"].ensure_installed!(reason: "Linux sandboxing")
+          end
+        rescue FormulaUnavailableError
+          nil
+        end
+
+        sig { returns(T::Boolean) }
+        def available?
+          return false unless Homebrew::EnvConfig.sandbox_linux?
+
+          ensure_bubblewrap_installed!
+
+          return false unless (bubblewrap = bubblewrap_executable)
+          return false if bubblewrap.stat.setuid?
+
+          system(
+            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
+          ) == true
+        end
+
+        sig { returns(Integer) }
+        def terminal_ioctl_request
+          TIOCSCTTY
+        end
+      end
+
+      private
+
+      sig { params(args: T::Array[T.any(String, ::Pathname)], tmpdir: String).returns(T::Array[T.any(String, ::Pathname)]) }
+      def sandbox_command(args, tmpdir)
+        bubblewrap = T.must(which(BUBBLEWRAP, ORIGINAL_PATHS) || which(BUBBLEWRAP))
+        [bubblewrap, *bubblewrap_args(tmpdir), "--", *args]
+      end
+
+      sig { params(_tmpdir: String).returns(T::Array[String]) }
+      def bubblewrap_args(_tmpdir)
+        args = T.let([
+          "--unshare-user",
+          "--unshare-ipc",
+          "--unshare-pid",
+          "--unshare-uts",
+          "--unshare-cgroup-try",
+          "--die-with-parent",
+          "--new-session",
+          "--dev", "/dev",
+          "--proc", "/proc",
+          "--dir", "/var",
+          "--chdir", "/"
+        ], T::Array[String])
+        args << "--unshare-net" if deny_all_network?
+
+        read_only_paths.each do |path|
+          args += ["--ro-bind", path, path]
+        end
+
+        writable_paths.each do |path, type|
+          prepare_writable_path(path, type)
+          args += ["--bind", path, path]
+        end
+
+        denied_write_paths.each do |path|
+          next unless File.exist?(path)
+
+          args += ["--ro-bind", path, path]
+        end
+
+        args
+      end
+
+      sig { returns(T::Boolean) }
+      def deny_all_network?
+        profile.rules.any? do |rule|
+          !rule.allow && rule.operation == "network*" && rule.filter.nil?
+        end
+      end
+
+      sig { returns(T::Array[String]) }
+      def read_only_paths
+        (READ_ONLY_PATHS + [HOMEBREW_PREFIX.to_s, HOMEBREW_REPOSITORY.to_s])
+          .select { |path| File.exist?(path) }
+          .uniq
+      end
+
+      sig { returns(T::Hash[String, Symbol]) }
+      def writable_paths
+        profile.rules.each_with_object({}) do |rule, paths|
+          next if !rule.allow || !rule.operation.start_with?("file-write")
+          next unless (filter = rule.filter)
+
+          case filter.type
+          when :literal, :subpath
+            paths[filter.path] ||= filter.type
+          when :regex
+            raise ArgumentError, "Linux sandbox does not support regex path filters: #{filter.path}"
+          else
+            raise ArgumentError, "Invalid path filter type: #{filter.type}"
+          end
+        end
+      end
+
+      sig { returns(T::Array[String]) }
+      def denied_write_paths
+        profile.rules.filter_map do |rule|
+          next if rule.allow || !rule.operation.start_with?("file-write")
+
+          filter = rule.filter
+          filter.path if filter && [:literal, :subpath].include?(filter.type)
+        end.uniq
+      end
+
+      sig { params(path: String, type: Symbol).void }
+      def prepare_writable_path(path, type)
+        pathname = ::Pathname.new(path)
+        return if pathname.exist?
+
+        if type == :literal
+          FileUtils.mkdir_p(pathname.dirname)
+          FileUtils.touch(pathname)
+        else
+          FileUtils.mkdir_p(pathname)
+        end
+      end
+    end
+  end
+end
+
+Sandbox.prepend(OS::Linux::Sandbox)
+Sandbox.singleton_class.prepend(OS::Linux::Sandbox::ClassMethods)

Library/Homebrew/extend/os/sandbox.rb

@@ -2,3 +2,4 @@
 # frozen_string_literal: true
 
 require "extend/os/mac/sandbox" if OS.mac?
+require "extend/os/linux/sandbox" if OS.linux?

Library/Homebrew/sorbet/rbi/dsl/homebrew/env_config.rbi

@@ -0,0 +1,119 @@
+# typed: false
+# frozen_string_literal: true
+
+require "sandbox"
+
+RSpec.describe Sandbox, :needs_linux do
+  subject(:sandbox) { described_class.new }
+
+  around do |example|
+    with_env(HOMEBREW_SANDBOX_LINUX: "1") { example.run }
+  end
+
+  describe "::available?" do
+    let(:bubblewrap) { mktmpdir/"bwrap" }
+
+    before do
+      FileUtils.touch bubblewrap
+      FileUtils.chmod "+x", bubblewrap
+      allow(described_class).to receive(:bubblewrap_executable).and_return(bubblewrap)
+      allow(described_class).to receive(:ensure_bubblewrap_installed!)
+    end
+
+    it "returns false unless Linux sandboxing is enabled" do
+      with_env(HOMEBREW_SANDBOX_LINUX: nil) do
+        expect(described_class).not_to receive(:system)
+
+        expect(described_class.available?).to be(false)
+      end
+    end
+
+    it "returns false when bubblewrap is unavailable" do
+      allow(described_class).to receive(:bubblewrap_executable).and_return(nil)
+
+      expect(described_class.available?).to be(false)
+    end
+
+    it "probes unprivileged namespace support" do
+      expect(described_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(true)
+
+      expect(described_class.available?).to be(true)
+    end
+  end
+
+  describe "#bubblewrap_args" do
+    let(:dir) { mktmpdir }
+    let(:denied_dir) { mktmpdir }
+    let(:args) { sandbox.send(:bubblewrap_args, mktmpdir.to_s) }
+
+    it "maps allowed and denied writes to bind mounts" do
+      sandbox.allow_write_path dir
+      sandbox.deny_write_path denied_dir
+      sandbox.deny_all_network
+
+      expect(args).to include("--unshare-user", "--unshare-ipc", "--unshare-pid", "--unshare-net", "--new-session")
+      expect(args.each_cons(3)).to include(["--bind", dir.to_s, dir.to_s])
+      expect(args.each_cons(3)).to include(["--ro-bind", denied_dir.to_s, denied_dir.to_s])
+    end
+
+    it "uses Linux temp paths instead of macOS temp paths" do
+      sandbox.allow_write_temp_and_cache
+
+      expect(args).to include("/tmp", "/var/tmp", HOMEBREW_TEMP.to_s, HOMEBREW_CACHE.to_s)
+      expect(args).not_to include("/private/tmp", "/private/var/tmp")
+    end
+
+    it "does not add Xcode write paths" do
+      sandbox.allow_write_xcode
+
+      expect(sandbox.send(:writable_paths)).to be_empty
+    end
+
+    it "rejects regex path filters" do
+      sandbox.allow_write path: "^/tmp/homebrew-[^/]+$", type: :regex
+
+      expect { args }.to raise_error(ArgumentError, /Linux sandbox does not support regex path filters/)
+    end
+  end
+
+  describe "#run" do
+    before do
+      skip "Sandbox not implemented." unless described_class.available?
+    end
+
+    it "allows writing to an allowed path" do
+      file = mktmpdir/"foo"
+      sandbox.allow_write path: file
+      sandbox.run "touch", file
+
+      expect(file).to exist
+    end
+
+    it "fails when writing to a path that has not been allowed" do
+      file = mktmpdir/"foo"
+
+      expect do
+        sandbox.run "touch", file
+      end.to raise_error(ErrorDuringExecution)
+
+      expect(file).not_to exist
+    end
+
+    it "returns the command exit status" do
+      expect { sandbox.run "false" }.to raise_error(ErrorDuringExecution)
+    end
+  end
+end