Class: Sandbox Private

Inherits:
Object show all
Defined in:
extend/os/mac/sandbox.rb,
sandbox.rb

Overview

This class is part of a private API. This class may only be used in the Homebrew/brew repository. Third parties should avoid using this class if possible, as it may be removed or changed without warning.

Helper class for running a sub-process inside of a sandboxed environment.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



20
21
22
23
 
# File 'sandbox.rb', line 20

def initialize
  @profile = T.let(SandboxProfile.new, SandboxProfile)
  @failed = T.let(false, T::Boolean)
end

Class Method Details

.available? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


6
7
8
 
# File 'extend/os/mac/sandbox.rb', line 6

def self.available?
  File.executable?(SANDBOX_EXEC)
end

Instance Method Details

#add_rule(allow:, operation:, filter: nil, modifier: nil) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:

  • allow (Boolean)
  • operation (String)
  • filter (String, nil) (defaults to: nil)
  • modifier (String, nil) (defaults to: nil) 


31
32
33
34
 
# File 'sandbox.rb', line 31

def add_rule(allow:, operation:, filter: nil, modifier: nil)
  rule = SandboxRule.new(allow:, operation:, filter:, modifier:)
  @profile.add_rule(rule)
end

#allow_all_network ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.



118
119
120
 
# File 'sandbox.rb', line 118

def allow_all_network
  add_rule allow: true, operation: "network*"
end

#allow_cvs ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.



67
68
69
 
# File 'sandbox.rb', line 67

def allow_cvs
  allow_write_path "#{Dir.home(ENV.fetch("USER"))}/.cvspass"
end

#allow_fossil ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.



72
73
74
75
 
# File 'sandbox.rb', line 72

def allow_fossil
  allow_write_path "#{Dir.home(ENV.fetch("USER"))}/.fossil"
  allow_write_path "#{Dir.home(ENV.fetch("USER"))}/.fossil-journal"
end

#allow_network(path:, type: :literal) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



108
109
110
 
# File 'sandbox.rb', line 108

def allow_network(path:, type: :literal)
  add_rule allow: true, operation: "network*", filter: path_filter(path, type)
end

#allow_write(path:, type: :literal) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



37
38
39
40
 
# File 'sandbox.rb', line 37

def allow_write(path:, type: :literal)
  add_rule allow: true, operation: "file-write*", filter: path_filter(path, type)
  add_rule allow: true, operation: "file-write-setugid", filter: path_filter(path, type)
end

#allow_write_cellar(formula) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



78
79
80
81
82
 
# File 'sandbox.rb', line 78

def allow_write_cellar(formula)
  allow_write_path formula.rack
  allow_write_path formula.etc
  allow_write_path formula.var
end

#allow_write_log(formula) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



92
93
94
 
# File 'sandbox.rb', line 92

def allow_write_log(formula)
  allow_write_path formula.logs
end

#allow_write_path(path) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



48
49
50
 
# File 'sandbox.rb', line 48

def allow_write_path(path)
  allow_write path:, type: :subpath
end

#allow_write_temp_and_cache ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.



58
59
60
61
62
63
64
 
# File 'sandbox.rb', line 58

def allow_write_temp_and_cache
  allow_write_path "/private/tmp"
  allow_write_path "/private/var/tmp"
  allow_write path: "^/private/var/folders/[^/]+/[^/]+/[C,T]/", type: :regex
  allow_write_path HOMEBREW_TEMP
  allow_write_path HOMEBREW_CACHE
end

#allow_write_xcode ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Xcode projects expect access to certain cache/archive dirs.



86
87
88
89
 
# File 'sandbox.rb', line 86

def allow_write_xcode
  allow_write_path "#{Dir.home(ENV.fetch("USER"))}/Library/Developer"
  allow_write_path "#{Dir.home(ENV.fetch("USER"))}/Library/Caches/org.swift.swiftpm"
end

#deny_all_network ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.



123
124
125
 
# File 'sandbox.rb', line 123

def deny_all_network
  add_rule allow: false, operation: "network*"
end

#deny_all_network_except_pipe(path) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



128
129
130
131
 
# File 'sandbox.rb', line 128

def deny_all_network_except_pipe(path)
  deny_all_network
  allow_network path:, type: :literal
end

#deny_network(path:, type: :literal) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



113
114
115
 
# File 'sandbox.rb', line 113

def deny_network(path:, type: :literal)
  add_rule allow: false, operation: "network*", filter: path_filter(path, type)
end

#deny_write(path:, type: :literal) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



43
44
45
 
# File 'sandbox.rb', line 43

def deny_write(path:, type: :literal)
  add_rule allow: false, operation: "file-write*", filter: path_filter(path, type)
end

#deny_write_homebrew_repository ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.



97
98
99
100
101
102
103
104
105
 
# File 'sandbox.rb', line 97

def deny_write_homebrew_repository
  deny_write path: HOMEBREW_BREW_FILE
  if HOMEBREW_PREFIX.to_s == HOMEBREW_REPOSITORY.to_s
    deny_write_path HOMEBREW_LIBRARY
    deny_write_path HOMEBREW_REPOSITORY/".git"
  else
    deny_write_path HOMEBREW_REPOSITORY
  end
end

#deny_write_path(path) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



53
54
55
 
# File 'sandbox.rb', line 53

def deny_write_path(path)
  deny_write path:, type: :subpath
end

#exec(*args) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'sandbox.rb', line 134

def exec(*args)
  seatbelt = Tempfile.new(["homebrew", ".sb"], HOMEBREW_TEMP)
  seatbelt.write(@profile.dump)
  seatbelt.close
  @start = T.let(Time.now, T.nilable(Time))

  begin
    command = [SANDBOX_EXEC, "-f", seatbelt.path, *args]
    # Start sandbox in a pseudoterminal to prevent access of the parent terminal.
    PTY.spawn(*command) do |r, w, pid|
      # Set the PTY's window size to match the parent terminal.
      # Some formula tests are sensitive to the terminal size and fail if this is not set.
      winch = proc do |_sig|
        w.winsize = if $stdout.tty?
          # We can only use IO#winsize if the IO object is a TTY.
          $stdout.winsize
        else
          # Otherwise, default to tput, if available.
          # This relies on ncurses rather than the system's ioctl.
          [Utils.popen_read("tput", "lines").to_i, Utils.popen_read("tput", "cols").to_i]
        end
      end

      write_to_pty = proc do
        # Don't hang if stdin is not able to be used - throw EIO instead.
        old_ttin = trap(:TTIN, "IGNORE")

        # Update the window size whenever the parent terminal's window size changes.
        old_winch = trap(:WINCH, &winch)
        winch.call(nil)

        stdin_thread = Thread.new do
          IO.copy_stream($stdin, w)
        rescue Errno::EIO
          # stdin is unavailable - move on.
        end

        r.each_char { |c| print(c) }

        Process.wait(pid)
      ensure
        stdin_thread&.kill
        trap(:TTIN, old_ttin)
        trap(:WINCH, old_winch)
      end

      if $stdin.tty?
        # If stdin is a TTY, use io.raw to set stdin to a raw, passthrough
        # mode while we copy the input/output of the process spawned in the
        # PTY. After we've finished copying to/from the PTY process, io.raw
        # will restore the stdin TTY to its original state.
        begin
          # Ignore SIGTTOU as setting raw mode will hang if the process is in the background.
          old_ttou = trap(:TTOU, "IGNORE")
          $stdin.raw(&write_to_pty)
        ensure
          trap(:TTOU, old_ttou)
        end
      else
        write_to_pty.call
      end
    end
    raise ErrorDuringExecution.new(command, status: $CHILD_STATUS) unless $CHILD_STATUS.success?
  rescue
    @failed = true
    raise
  ensure
    seatbelt.unlink
    sleep 0.1 # wait for a bit to let syslog catch up the latest events.
    syslog_args = [
      "-F", "$((Time)(local)) $(Sender)[$(PID)]: $(Message)",
      "-k", "Time", "ge", @start.to_i.to_s,
      "-k", "Message", "S", "deny",
      "-k", "Sender", "kernel",
      "-o",
      "-k", "Time", "ge", @start.to_i.to_s,
      "-k", "Message", "S", "deny",
      "-k", "Sender", "sandboxd"
    ]
    logs = Utils.popen_read("syslog", *syslog_args)

    # These messages are confusing and non-fatal, so don't report them.
    logs = logs.lines.grep_v(/^.*Python\(\d+\) deny file-write.*pyc$/).join

    unless logs.empty?
      if @logfile
        File.open(@logfile, "w") do |log|
          log.write logs
          log.write "\nWe use time to filter sandbox log. Therefore, unrelated logs may be recorded.\n"
        end
      end

      if @failed && Homebrew::EnvConfig.verbose?
        ohai "Sandbox Log", logs
        $stdout.flush # without it, brew test-bot would fail to catch the log
      end
    end
  end
end

#record_log(file) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



26
27
28
 
# File 'sandbox.rb', line 26

def record_log(file)
  @logfile = T.let(file, T.nilable(T.any(String, Pathname)))
end