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 usable brewed binary is found.
- Prefer a usable system `bwrap` from `ORIGINAL_PATHS` over a brewed
  one so distribution-provided binaries are used when available.
- Find brewed `bwrap` from `HOMEBREW_ORIGINAL_BREW_FILE` so integration
  subprocesses still use the Linux sandbox.
- Preserve `Sandbox#run`'s tmpdir cwd inside the `bwrap` namespace and
  ignore PTY EOF after sandboxed children exit.
- Expose formula and Homebrew library paths as read-only binds so
  sandboxed local formula builds can run with vendored Ruby.
- Keep synthetic test formula installs off the API so sandbox CI does
  not require network during local formula setup.
- Avoid creating optional prefix `var` directories just to configure a
  test sandbox and remove empty Linux bind placeholders after runs.
- Install `bubblewrap` and document namespace sysctls in Linux CI so
  test-bot exercises the sandbox path.

Author: MikeMcQuaid

.github/workflows/tests.yml

@@ -274,6 +274,20 @@ jobs:
           workflow-key: tests-tests-macos
           uninstall: true
 
+      - name: Install brew tests Linux dependencies
+        if: runner.os == 'Linux'
+        run: |
+          # Allow unprivileged user namespace cloning; rootless `bwrap` needs this
+          # to create its user namespace.
+          sudo sysctl -w kernel.unprivileged_userns_clone=1
+          # Ensure the runner can allocate user namespaces instead of hitting a
+          # per-user namespace limit.
+          sudo sysctl -w user.max_user_namespaces=28633
+          # Ubuntu runners may additionally restrict unprivileged user namespaces
+          # through AppArmor; older kernels may not expose this sysctl.
+          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 || true
+          brew install bubblewrap
+
         # brew tests doesn't like world writable directories
       - name: Cleanup permissions
         if: runner.os == 'Linux'
@@ -286,6 +300,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: 1
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
       - name: Get RSpec JUnit XML filenames
@@ -335,6 +350,7 @@ jobs:
           - name: test-bot (macOS arm64)
             runs-on: macos-26
     env:
+      HOMEBREW_SANDBOX_LINUX: 1
       HOMEBREW_TEST_BOT_ANALYTICS: 1
     steps:
       - name: Install Homebrew and Homebrew's dependencies
@@ -345,6 +361,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/dev-cmd/test.rb

@@ -37,6 +37,7 @@ def run
         require "formula_free_port"
         require "utils/fork"
 
+        optional_prefix_var_dirs = %w[var/cache var/log var/run]
         args.named.to_resolved_formulae.each do |f|
           # Cannot test uninstalled formulae
           unless f.latest_version_installed?
@@ -81,17 +82,19 @@ def run
 
             exec_args << "--HEAD" if f.head?
 
+            Sandbox.ensure_sandbox_installed!
             if Sandbox.available?
               sandbox = Sandbox.new
               f.logs.mkpath
               sandbox.record_log(f.logs/"test.sandbox.log")
               sandbox.allow_write_temp_and_cache
               sandbox.allow_write_log(f)
               sandbox.allow_write_xcode
-              sandbox.allow_write_path(HOMEBREW_PREFIX/"var/cache")
               sandbox.allow_write_path(HOMEBREW_PREFIX/"var/homebrew/locks")
-              sandbox.allow_write_path(HOMEBREW_PREFIX/"var/log")
-              sandbox.allow_write_path(HOMEBREW_PREFIX/"var/run")
+              optional_prefix_var_dirs.each do |dir|
+                path = HOMEBREW_PREFIX/dir
+                sandbox.allow_write_path(path) if path.exist?
+              end
               sandbox.deny_all_network unless f.class.network_access_allowed?(:test)
               sandbox.run(*exec_args)
             else

Library/Homebrew/dev-cmd/tests.rb

@@ -66,6 +66,8 @@ def run
           # `return false`.
           require "extend/os/dev-cmd/tests"
 
+          check_test_environment!
+
           parallel = !args.no_parallel?
 
           only = args.only
@@ -210,6 +212,9 @@ def non_linux_bundle_args(bundle_args)
         bundle_args << "--tag" << "~needs_linux" << "--tag" << "~needs_systemd"
       end
 
+      sig { void }
+      def check_test_environment!; end
+
       sig { params(files: T::Array[String]).returns(T::Array[String]) }
       def os_files(files)
         # for generic tests, remove macOS or Linux specific files
@@ -256,6 +261,7 @@ def setup_environment!
           HOMEBREW_GITHUB_API_TOKEN
           HOMEBREW_CACHE
           HOMEBREW_LOGS
+          HOMEBREW_SANDBOX_LINUX
           HOMEBREW_TEMP
         ]
         allowed_test_env << "HOMEBREW_USE_RUBY_FROM_PATH" if Homebrew::EnvConfig.developer?

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 the `bwrap`(1) sandbox for formula installation and testing on Linux.",
+        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/dev-cmd/tests.rb

@@ -20,6 +20,66 @@ def os_bundle_args(bundle_args)
         def os_files(files)
           non_macos_files(files)
         end
+
+        sig { void }
+        def check_test_environment!
+          super
+          return unless ENV["CI"]
+
+          require "sandbox"
+          with_env(HOMEBREW_SANDBOX_LINUX: "1") do
+            return if ::Sandbox.available?
+
+            message = +"Linux tests require a working rootless Bubblewrap sandbox.\n"
+            message << "HOMEBREW_SANDBOX_LINUX=#{ENV.fetch("HOMEBREW_SANDBOX_LINUX", nil).inspect}\n"
+            message << "PATH=#{ENV.fetch("PATH", nil).inspect}\n"
+            message << "HOMEBREW_PATH=#{ENV.fetch("HOMEBREW_PATH", nil).inspect}\n"
+            message << "ORIGINAL_PATHS=#{ORIGINAL_PATHS.join(File::PATH_SEPARATOR)}\n"
+
+            candidates = OS::Linux::Sandbox.bubblewrap_candidate_paths.filter_map do |path|
+              candidate = begin
+                ::Pathname.new(File.expand_path("bwrap", path))
+              rescue ArgumentError => e
+                next "#{path}/bwrap error=#{e.class}: #{e.message}"
+              end
+              next unless candidate.exist?
+
+              stat = File.stat(candidate)
+              "#{candidate} file=#{candidate.file?} executable=#{candidate.executable?} setuid=#{stat.setuid?}"
+            rescue SystemCallError => e
+              "#{candidate} error=#{e.class}: #{e.message}"
+            end
+            message << "bwrap candidates=#{candidates.presence&.join(", ") || "(none)"}\n"
+
+            if (bubblewrap = OS::Linux::Sandbox.bubblewrap_executable)
+              message << "selected bwrap=#{bubblewrap}\n"
+              message << "selected bwrap setuid=#{File.stat(bubblewrap).setuid?}\n"
+              result = system_command(
+                bubblewrap,
+                args:         [
+                  "--unshare-user",
+                  "--unshare-ipc",
+                  "--unshare-pid",
+                  "--unshare-uts",
+                  "--unshare-cgroup-try",
+                  "--ro-bind", "/", "/",
+                  "--proc", "/proc",
+                  "--dev", "/dev",
+                  "true"
+                ],
+                print_stderr: false,
+                must_succeed: false,
+              )
+              message << "bwrap probe exit_status=#{result.exit_status.inspect}\n"
+              message << "bwrap probe stdout=#{result.stdout.presence || "(empty)"}\n"
+              message << "bwrap probe stderr=#{result.stderr.presence || "(empty)"}"
+            else
+              message << "selected bwrap=(none)"
+            end
+
+            raise UsageError, message
+          end
+        end
       end
     end
   end