Sandbox cask completions

MikeMcQuaid · MikeMcQuaid · commit bc6d9cb49497 · 2026-05-24T14:47:47.000+01:00
- Avoid unsandboxed upstream code when generating cask completions.
- Keep installer scripts on `SystemCommand` because most run installers.
- Document why cask installers and packages are not sandboxed.
- Note that flight blocks are expected to be sandboxed later.
- Keep `HOMEBREW_NO_SANDBOX_CASK` as a temporary escape hatch.
- Preserve completion output by discarding stderr unless requested.
diff --git a/Library/Homebrew/cask/artifact/abstract_artifact.rb b/Library/Homebrew/cask/artifact/abstract_artifact.rb
@@ -2,6 +2,9 @@
 # frozen_string_literal: true
 
 require "extend/object/deep_dup"
+require "env_config"
+require "sandbox"
+require "tempfile"
 require "utils/output"
 
 module Cask
@@ -19,7 +22,6 @@ class AbstractArtifact
       # T.anything or the union of all possible argument types would be better choice, but it's convenient to be
       # able to invoke `.inspect`, `.to_s`, etc. without the overhead of type guards.
       DirectivesType = T.type_alias { Object }
-
       sig { overridable.returns(String) }
       def self.english_name
         @english_name ||= T.let(T.must(name).sub(/^.*:/, "").gsub(/(.)([A-Z])/, '\1 \2'), T.nilable(String))
@@ -183,6 +185,55 @@ def config
         cask.config
       end
 
+      sig { returns(T.nilable(Sandbox)) }
+      def cask_sandbox
+        return if Homebrew::EnvConfig.no_sandbox_cask?
+
+        Sandbox.ensure_sandbox_installed!
+        return unless Sandbox.available?
+
+        Sandbox.new.tap do |sandbox|
+          sandbox.allow_read(path: cask.staged_path, type: :subpath)
+          sandbox.allow_write_temp_and_cache
+          sandbox.deny_all_network
+        end
+      end
+
+      sig {
+        params(
+          env:  T::Hash[String, T.any(String, T::Boolean, PATH)],
+          args: T::Array[T.any(String, Pathname)],
+        ).returns(T::Array[T.any(String, Pathname)])
+      }
+      def cask_sandbox_command(env, args)
+        ["/usr/bin/env", *env.map { |key, value| "#{key}=#{value}" }, *args]
+      end
+
+      sig {
+        params(
+          sandbox: Sandbox,
+          args:    T::Array[T.any(String, Pathname)],
+          input:   T.any(String, T::Array[String]),
+        ).void
+      }
+      def run_cask_sandbox(sandbox, args, input: [])
+        return sandbox.run(*args) if Array(input).empty?
+
+        Tempfile.create("homebrew-cask-script-input", HOMEBREW_TEMP) do |input_file|
+          input_file.write(Array(input).join)
+          input_file.close
+          sandbox.allow_read(path: input_file.path)
+          sandbox.run(
+            "/bin/sh",
+            "-c",
+            "input=$1; shift; exec \"$@\" < \"$input\"",
+            "sh",
+            input_file.path,
+            *args,
+          )
+        end
+      end
+
       sig { returns(String) }
       def to_s
         "#{summarize} (#{self.class.english_name})"
diff --git a/Library/Homebrew/cask/artifact/generated_completion.rb b/Library/Homebrew/cask/artifact/generated_completion.rb
@@ -6,6 +6,7 @@
 require "cask/artifact/fishcompletion"
 require "cask/artifact/zshcompletion"
 require "extend/hash/keys"
+require "tempfile"
 require "utils/shell_completion"
 
 module Cask
@@ -100,11 +101,7 @@ def install_phase(**_options)
 
           script_path = completion_script_path(shell)
           script_path.dirname.mkpath
-          script_path.write(::Utils::ShellCompletion.generate_completion_output(
-                              [executable, *commands[1..]],
-                              shell_parameter,
-                              popen_read_env,
-                            ))
+          script_path.write(generate_completion_output([executable, *commands[1..]], shell_parameter, popen_read_env))
         rescue => e
           opoo "Failed to generate #{shell} completions from #{executable}: #{e}"
         end
@@ -124,6 +121,38 @@ def uninstall_phase(command: SystemCommand, **_options)
 
       private
 
+      sig {
+        params(
+          completion_commands: T::Array[T.any(Pathname, String)],
+          shell_parameter:     T.nilable(T.any(String, T::Array[String])),
+          env:                 T::Hash[String, String],
+        ).returns(String)
+      }
+      def generate_completion_output(completion_commands, shell_parameter, env)
+        sandbox = cask_sandbox
+        unless sandbox
+          return ::Utils::ShellCompletion.generate_completion_output(completion_commands, shell_parameter,
+                                                                     env)
+        end
+
+        Tempfile.create("homebrew-cask-completions", HOMEBREW_TEMP) do |output|
+          sandbox.run(
+            *cask_sandbox_command(
+              env,
+              [
+                "/bin/sh",
+                "-c",
+                "output=$1; shift; exec \"$@\" > \"$output\"#{" 2>/dev/null" unless ENV["HOMEBREW_STDERR"]}",
+                "sh",
+                output.path,
+                *(completion_commands + Array(shell_parameter)),
+              ],
+            ),
+          )
+          output.read
+        end
+      end
+
       sig { returns(String) }
       def resolved_base_name
         @resolved_base_name ||= T.let(begin
diff --git a/Library/Homebrew/env_config.rb b/Library/Homebrew/env_config.rb
@@ -474,6 +474,11 @@ module EnvConfig
                      "shadowed by other commands earlier on `$PATH`.",
         boolean:     true,
       },
+      HOMEBREW_NO_SANDBOX_CASK:                  {
+        # odeprecated: make cask executable sandboxing mandatory in a future release.
+        description: "If set, disable sandboxing for cask artifacts that generate files by running executables.",
+        boolean:     true,
+      },
       HOMEBREW_NO_SANDBOX_LINUX:                 {
         description: "If set, disable the Linux sandbox.",
         boolean:     true,
diff --git a/Library/Homebrew/sorbet/rbi/dsl/homebrew/env_config.rbi b/Library/Homebrew/sorbet/rbi/dsl/homebrew/env_config.rbi
diff --git a/Library/Homebrew/test/cask/artifact/generated_completion_spec.rb b/Library/Homebrew/test/cask/artifact/generated_completion_spec.rb
@@ -35,8 +35,16 @@
     it "generates completion scripts for default shells" do
       artifact = cask.artifacts.grep(klass).first
 
-      allow(Utils).to receive(:safe_popen_read) do |env, *_args, **_opts|
-        "#{env.fetch("SHELL")} completion output"
+      allow(Sandbox).to receive_messages(ensure_sandbox_installed!: nil, available?: true)
+      allow(Sandbox).to receive(:new) do
+        instance_double(Sandbox).tap do |sandbox|
+          allow(sandbox).to receive(:allow_read)
+          allow(sandbox).to receive(:allow_write_temp_and_cache)
+          allow(sandbox).to receive(:deny_all_network)
+          allow(sandbox).to receive(:run) do |*args|
+            Pathname(args.fetch(6)).write("#{args.fetch(1).delete_prefix("SHELL=")} completion output")
+          end
+        end
       end
 
       artifact.install_phase
@@ -49,14 +57,57 @@
       expect((fish_dir/"foo.fish").read).to eq("fish completion output")
     end
 
+    it "sandboxes completion generation" do
+      artifact = cask.artifacts.grep(klass).first
+      sandboxes = []
+
+      allow(Sandbox).to receive_messages(ensure_sandbox_installed!: nil, available?: true)
+      allow(Sandbox).to receive(:new) do
+        instance_double(Sandbox).tap do |sandbox|
+          expect(sandbox).to receive(:allow_read).with(path: staged_path, type: :subpath)
+          expect(sandbox).to receive(:allow_write_temp_and_cache)
+          expect(sandbox).to receive(:deny_all_network)
+          allow(sandbox).to receive(:run) { |*args| Pathname(args.fetch(6)).write("completion") }
+          sandboxes << sandbox
+        end
+      end
+
+      artifact.install_phase
+
+      expect(sandboxes.length).to eq(3)
+    end
+
+    it "does not sandbox when HOMEBREW_NO_SANDBOX_CASK is set" do
+      artifact = cask.artifacts.grep(klass).first
+
+      ENV["HOMEBREW_NO_SANDBOX_CASK"] = "1"
+      allow(Sandbox).to receive(:available?).and_return(true)
+      allow(Utils).to receive(:safe_popen_read) { |env, *_args, **_opts| "#{env.fetch("SHELL")} completion" }
+      expect(Sandbox).not_to receive(:new)
+
+      artifact.install_phase
+
+      expect((bash_dir/"foo").read).to eq("bash completion")
+    ensure
+      ENV["HOMEBREW_NO_SANDBOX_CASK"] = nil
+    end
+
     context "when generation fails for one shell" do
       it "warns and continues generating other shells" do
         artifact = cask.artifacts.grep(klass).first
 
-        allow(Utils).to receive(:safe_popen_read) do |env, *_args, **_opts|
-          raise "boom" if env.fetch("SHELL") == "bash"
-
-          "zsh completion"
+        allow(Sandbox).to receive_messages(ensure_sandbox_installed!: nil, available?: true)
+        allow(Sandbox).to receive(:new) do
+          instance_double(Sandbox).tap do |sandbox|
+            allow(sandbox).to receive(:allow_read)
+            allow(sandbox).to receive(:allow_write_temp_and_cache)
+            allow(sandbox).to receive(:deny_all_network)
+            allow(sandbox).to receive(:run) do |*args|
+              raise "boom" if args.fetch(1) == "SHELL=bash"
+
+              Pathname(args.fetch(6)).write("zsh completion")
+            end
+          end
         end
 
         expect { artifact.install_phase }
@@ -103,14 +154,23 @@
       artifact = cask.artifacts.grep(klass).first
       captured_args = nil
 
-      allow(Utils).to receive(:safe_popen_read) do |_env, *args, **_opts|
-        captured_args = args
-        "zsh completion"
+      allow(Sandbox).to receive_messages(ensure_sandbox_installed!: nil, available?: true)
+      allow(Sandbox).to receive(:new) do
+        instance_double(Sandbox).tap do |sandbox|
+          allow(sandbox).to receive(:allow_read)
+          allow(sandbox).to receive(:allow_write_temp_and_cache)
+          allow(sandbox).to receive(:deny_all_network)
+          allow(sandbox).to receive(:run) do |*args|
+            captured_args = args
+            Pathname(args.fetch(6)).write("zsh completion")
+          end
+        end
       end
 
       artifact.install_phase
 
       expect(captured_args).to include("--shell=zsh")
+      expect(captured_args.fetch(4)).to end_with(" 2>/dev/null")
       expect(zsh_dir/"_bar").to be_a_file
       expect(bash_dir/"bar").not_to exist
       expect(fish_dir/"bar.fish").not_to exist
diff --git a/Library/Homebrew/test/cask/artifact/installer_spec.rb b/Library/Homebrew/test/cask/artifact/installer_spec.rb
@@ -39,6 +39,14 @@
 
         installer.install_phase(command:)
       end
+
+      it "does not sandbox the executable" do
+        allow(Sandbox).to receive(:available?).and_return(true)
+        expect(Sandbox).not_to receive(:new)
+        expect(command).to receive(:run!)
+
+        installer.install_phase(command:)
+      end
     end
   end
 end
diff --git a/Library/Homebrew/test/env_config_spec.rb b/Library/Homebrew/test/env_config_spec.rb
@@ -179,6 +179,15 @@
     end
   end
 
+  describe ".no_sandbox_cask?" do
+    it "returns true if HOMEBREW_NO_SANDBOX_CASK is set" do
+      ENV["HOMEBREW_NO_SANDBOX_CASK"] = "1"
+      expect(env_config.no_sandbox_cask?).to be(true)
+    ensure
+      ENV["HOMEBREW_NO_SANDBOX_CASK"] = nil
+    end
+  end
+
   describe ".use_internal_api?" do
     it "returns true if HOMEBREW_USE_INTERNAL_API is set" do
       ENV["HOMEBREW_USE_INTERNAL_API"] = "1"
diff --git a/docs/Cask-Cookbook.md b/docs/Cask-Cookbook.md
@@ -142,6 +142,7 @@ Each cask must declare one or more [artifacts](/rubydoc/Cask/Artifact.html) (i.e
 | `bash_completion`                | yes                           | Relative path to a Bash completion file that should be linked into the `$(brew --prefix)/etc/bash_completion.d` folder on installation. |
 | `fish_completion`                | yes                           | Relative path to a fish completion file that should be linked into the `$(brew --prefix)/share/fish/vendor_completions.d` folder on installation. |
 | `zsh_completion`                 | yes                           | Relative path to a Zsh completion file that should be linked into the `$(brew --prefix)/share/zsh/site-functions` folder on installation. |
+| `generate_completions_from_executable` | yes                      | Command and arguments used to generate shell completions from an executable at installation time. |
 | `colorpicker`                    | yes                           | Relative path to a ColorPicker plugin that should be moved into the `~/Library/ColorPickers` folder on installation. |
 | `dictionary`                     | yes                           | Relative path to a Dictionary that should be moved into the `~/Library/Dictionaries` folder on installation. |
 | `font`                           | yes                           | Relative path to a Font that should be moved into the `~/Library/Fonts` folder on installation. |
@@ -158,6 +159,16 @@ Each cask must declare one or more [artifacts](/rubydoc/Cask/Artifact.html) (i.e
 | `artifact`                       | yes                           | Relative path to an arbitrary path that should be moved on installation. Must provide an absolute path as a `target`. (Example: [free-gpgmail.rb](https://github.com/Homebrew/homebrew-cask/blob/b3c438d608d9702380edf10d5495e0727cf17108/Casks/f/free-gpgmail.rb#L44)) This is only for unusual cases; the `app` stanza is strongly preferred when moving `.app` bundles. |
 | `stage_only`                     | no                            | `true`. Asserts that the cask contains no activatable artifacts. |
 
+### Cask artifact trust and sandboxing
+
+Homebrew treats cask installation artifacts as trusted vendor installation actions once the cask has been accepted. Artifact stanzas such as [`app`](#stanza-app), [`pkg`](#stanza-pkg) and [`installer script`](#installer-script) are expected to install software and may write outside the Caskroom through Homebrew-managed moves, macOS installer services or vendor installer code.
+
+Generated completion artifacts are different: `generate_completions_from_executable` runs an installed executable only to produce shell completion text. That execution is sandboxed where Homebrew has an available sandbox. The sandbox allows reading the staged cask, writing temporary/cache files and blocks network access. This limits side effects from commands that should only print completion data.
+
+`installer script:` is not sandboxed. Many installer scripts are vendor installers that require broad filesystem writes, macOS services or `sudo`; macOS sandboxing does not work for root processes, and narrowing the write allowlist to the Caskroom plus uninstall or zap paths would break installers that legitimately write elsewhere. It would also change documented `SystemCommand` behaviours such as `sudo:`, `must_succeed:` and output handling.
+
+`pkg` artifacts are not run in the cask sandbox either. They are installed by macOS `/usr/sbin/installer`, which applies package payloads, scripts and receipts according to the package metadata.
+
 ### Optional stanzas
 
 | name                                       | multiple occurrences allowed? | value |
@@ -544,6 +555,8 @@ Refer to [Deprecating, Disabling and Removing](Deprecating-Disabling-and-Removin
 
 The stanzas `preflight`, `postflight`, `uninstall_preflight`, and `uninstall_postflight` define operations to be run before or after installation or uninstallation.
 
+Flight blocks are not currently run in the cask sandbox. They should be written as though they may be sandboxed in the future: prefer the mini-DSL helpers below and keep filesystem writes limited to paths owned by the cask.
+
 #### Evaluation of blocks is always deferred
 
 The Ruby blocks defined by these stanzas are not evaluated until install time or uninstall time. Within a block you may refer to the `@cask` instance variable, and invoke [any method available on `@cask`](/rubydoc/Cask/Cask.html).
@@ -589,6 +602,8 @@ installer manual: "RubyMotion Installer.app"
 | `print_stdout:` | set to `false` to suppress `stdout` output |
 | `sudo:`         | set to `true` if the script needs *sudo* |
 
+Installer scripts run without the cask sandbox. Use them only when the vendor provides an installer command that cannot be represented by a more specific artifact stanza such as [`app`](#stanza-app) or [`pkg`](#stanza-pkg).
+
 The path may be absolute, or relative to the cask. Example (from [miniforge.rb](https://github.com/Homebrew/homebrew-cask/blob/864f623e2cd17dbde5987a7b3923fdb0b4ac9ee5/Casks/m/miniforge.rb#L23-L26)):
 
 ```ruby
