Class: Sandbox::Landlock

Inherits:
LinuxBackend show all
Includes:
Utils::Output::Mixin
Defined in:
extend/os/linux/sandbox/landlock.rb

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Utils::Output::Mixin

#issue_reporting_message, #odebug, #odeprecated, #odie, #odisabled, #ofail, #oh1, #oh1_title, #ohai, #ohai_title, #onoe, #opoo, #opoo_once, #opoo_outside_github_actions, #opoo_without_github_actions_annotation, #pretty_cannot_install, #pretty_deprecated, #pretty_disabled, #pretty_duration, #pretty_incompatible, #pretty_install_status, #pretty_installed, #pretty_removed, #pretty_uninstalled, #pretty_unmarked, #pretty_upgradable, #pretty_warning

Methods inherited from LinuxBackend

#cleanup, #writable_paths

Constructor Details

#initialize(profile) ⇒ 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.

Parameters:

  • profile (SandboxProfile)


275
276
277
278
279
280
281
282
283
# File 'extend/os/linux/sandbox/landlock.rb', line 275

def initialize(profile)
  super
  @writable_paths = T.let([], T::Array[String])
  @readable_paths = T.let([], T::Array[String])
  @socket_directory = T.let(nil, T.nilable(String))
  @deny_all_network = T.let(false, T::Boolean)
  @warn_incomplete_network = T.let(false, T::Boolean)
  @deny_read = T.let(false, T::Boolean)
end

Class Method Details

.abi_version ⇒ Integer?

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:



112
113
114
115
# File 'extend/os/linux/sandbox/landlock.rb', line 112

def abi_version
  state
  @abi_version
end

.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)


102
103
104
# File 'extend/os/linux/sandbox/landlock.rb', line 102

def available?
  state == :available
end

.close_file_descriptor(file_descriptor) ⇒ Integer

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.

Parameters:

Returns:



218
219
220
221
222
223
224
225
226
227
# File 'extend/os/linux/sandbox/landlock.rb', line 218

def close_file_descriptor(file_descriptor)
  @close ||= T.let(
    libc_function(
      "close",
      [Fiddle::TYPE_INT],
    ),
    T.nilable(Fiddle::Function),
  )
  @close.call(file_descriptor)
end

.failure_reason ⇒ String?

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:



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
# File 'extend/os/linux/sandbox/landlock.rb', line 130

def failure_reason
  case state
  when :available
    nil
  when :config_disabled
    "Landlock cannot be used because Linux sandboxing is disabled."
  when :missing_fiddle
    "Landlock requires Ruby's bundled Fiddle library."
  when :unsupported
    "Landlock is not supported by this Linux kernel."
  when :disabled
    "Landlock is disabled by this Linux kernel."
  when :unsupported_abi
    abi = @abi_version
    if abi
      "Landlock ABI #{MINIMUM_ABI} or later is required; found ABI #{abi}."
    else
      "Landlock ABI #{MINIMUM_ABI} or later is required."
    end
  else
    "Landlock is not available."
  end
end

.full_write_isolation? ⇒ 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.

Landlock cannot restrict chmod, chown, extended attributes or timestamp changes. Callers requiring full write isolation must compensate for these limitations: https://www.kernel.org/doc/html/latest/userspace-api/landlock.html#filesystem-flags

Returns:

  • (Boolean)


99
# File 'extend/os/linux/sandbox/landlock.rb', line 99

def full_write_isolation? = false

.kernel_abi_version ⇒ Integer?

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.

The Landlock ABI version provided by the running kernel, regardless of whether Homebrew's Linux sandbox is enabled or usable.

Returns:



120
121
122
123
124
125
126
127
# File 'extend/os/linux/sandbox/landlock.rb', line 120

def kernel_abi_version
  require "fiddle"

  version = landlock_create_ruleset(nil, 0, CREATE_RULESET_VERSION)
  version if version.positive?
rescue LoadError, Fiddle::DLError
  nil
end

.landlock_add_rule(ruleset_fd, type, attributes, flags) ⇒ Integer

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.

Parameters:

Returns:



172
173
174
175
176
177
178
179
180
# File 'extend/os/linux/sandbox/landlock.rb', line 172

def landlock_add_rule(ruleset_fd, type, attributes, flags)
  @landlock_add_rule ||= T.let(
    syscall_function(
      [Fiddle::TYPE_LONG, Fiddle::TYPE_INT, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT],
    ),
    T.nilable(Fiddle::Function),
  )
  @landlock_add_rule.call(ADD_RULE_SYSCALL, ruleset_fd, type, attributes, flags)
end

.landlock_create_ruleset(attributes, size, flags) ⇒ Integer

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.

Parameters:

Returns:



161
162
163
164
165
166
167
168
169
# File 'extend/os/linux/sandbox/landlock.rb', line 161

def landlock_create_ruleset(attributes, size, flags)
  @landlock_create_ruleset ||= T.let(
    syscall_function(
      [Fiddle::TYPE_LONG, Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_UINT],
    ),
    T.nilable(Fiddle::Function),
  )
  @landlock_create_ruleset.call(CREATE_RULESET_SYSCALL, attributes, size, flags)
end

.landlock_restrict_self(ruleset_fd, flags) ⇒ Integer

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.

Parameters:

Returns:



183
184
185
186
187
188
189
190
191
# File 'extend/os/linux/sandbox/landlock.rb', line 183

def landlock_restrict_self(ruleset_fd, flags)
  @landlock_restrict_self ||= T.let(
    syscall_function(
      [Fiddle::TYPE_LONG, Fiddle::TYPE_INT, Fiddle::TYPE_UINT],
    ),
    T.nilable(Fiddle::Function),
  )
  @landlock_restrict_self.call(RESTRICT_SELF_SYSCALL, ruleset_fd, flags)
end

.last_error ⇒ Integer

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:



230
231
232
# File 'extend/os/linux/sandbox/landlock.rb', line 230

def last_error
  Fiddle.last_error
end

.open_path(path) ⇒ Integer

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.

Parameters:

Returns:



206
207
208
209
210
211
212
213
214
215
# File 'extend/os/linux/sandbox/landlock.rb', line 206

def open_path(path)
  @open ||= T.let(
    libc_function(
      "open",
      [Fiddle::TYPE_CONST_STRING, Fiddle::TYPE_INT],
    ),
    T.nilable(Fiddle::Function),
  )
  @open.call(path, O_PATH | O_CLOEXEC)
end

.reset_state! ⇒ 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.



155
156
157
158
# File 'extend/os/linux/sandbox/landlock.rb', line 155

def reset_state!
  @state = T.let(nil, T.nilable(Symbol))
  @abi_version = T.let(nil, T.nilable(Integer))
end

.set_no_new_privileges ⇒ Integer

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:



194
195
196
197
198
199
200
201
202
203
# File 'extend/os/linux/sandbox/landlock.rb', line 194

def set_no_new_privileges
  @prctl ||= T.let(
    libc_function(
      "prctl",
      [Fiddle::TYPE_INT, Fiddle::TYPE_ULONG, Fiddle::TYPE_ULONG, Fiddle::TYPE_ULONG, Fiddle::TYPE_ULONG],
    ),
    T.nilable(Fiddle::Function),
  )
  @prctl.call(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)
end

.state ⇒ Symbol

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:



107
108
109
# File 'extend/os/linux/sandbox/landlock.rb', line 107

def state
  @state ||= T.let(compute_state, T.nilable(Symbol))
end

Instance Method Details

#apply! ⇒ 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.



303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
# File 'extend/os/linux/sandbox/landlock.rb', line 303

def apply!
  abi = self.class.abi_version
  if !abi || abi < MINIMUM_ABI
    raise self.class.failure_reason || "Landlock ABI #{MINIMUM_ABI} or later is required."
  end

  if @warn_incomplete_network
    network_restrictions = if abi >= MINIMUM_NETWORK_ABI
      "Applying the network restrictions supported by this kernel."
    else
      "This kernel cannot restrict network access."
    end
    opoo "Landlock ABI #{MINIMUM_FULL_NETWORK_ABI} or later is required to deny all network access; " \
         "found ABI #{abi}. #{network_restrictions}"
  end

  attributes, handled_access_fs, allowed_write_access_fs = ruleset_attributes(abi)
  ruleset_fd = self.class.landlock_create_ruleset(attributes, attributes.bytesize, 0)
  raise_system_call_error("landlock_create_ruleset") if ruleset_fd.negative?

  begin
    # PTY allocation opens `/dev/ptmx` read-write, then configures its
    # dynamically allocated `/dev/pts/*` endpoint with device ioctls:
    # https://github.com/torvalds/linux/blob/master/drivers/tty/pty.c
    # https://www.kernel.org/doc/html/latest/userspace-api/landlock.html#ioctl-support
    pty_access = ACCESS_FS_WRITE_FILE
    pty_access |= ACCESS_FS_IOCTL_DEV if abi >= 5
    pty_access |= ACCESS_FS_READ_FILE if @deny_read

    # `/dev/full` is Linux's standard ENOSPC test device. Opening it with
    # `fopen(..., "w")` also requires Landlock's truncate right:
    # https://github.com/torvalds/linux/blob/master/drivers/char/mem.c
    # POSIX shared memory and message queues use `/dev/shm` and
    # `/dev/mqueue`. These grants retain normal kernel permissions but do
    # not provide a private IPC namespace:
    # https://github.com/bminor/glibc/blob/master/sysdeps/posix/shm-directory.c
    # https://www.kernel.org/doc/html/latest/filesystems/mqueue.html
    device_path_rules = {
      "/dev/full"   => FILE_WRITE_ACCESS_FS,
      "/dev/mqueue" => allowed_write_access_fs | (@deny_read ? ACCESS_FS_READ_FILE : 0),
      "/dev/ptmx"   => pty_access,
      "/dev/pts"    => pty_access,
      "/dev/shm"    => allowed_write_access_fs,
      "/dev/tty"    => pty_access,
    }
    device_path_rules.each do |path, allowed_access|
      next unless File.exist?(path)

      add_path_rule(ruleset_fd, path, allowed_access & handled_access_fs)
    end

    socket_directory = @socket_directory
    if @deny_all_network && abi >= 9 && socket_directory
      add_path_rule(ruleset_fd, socket_directory, ACCESS_FS_RESOLVE_UNIX)
    end
    @readable_paths.each do |path|
      allowed_access = File.directory?(path) ? READ_ACCESS_FS : FILE_READ_ACCESS_FS
      add_path_rule(ruleset_fd, path, allowed_access)
    rescue Errno::ENOENT
      nil
    end
    @writable_paths.each do |path|
      allowed_access = if File.directory?(path)
        allowed_write_access_fs
      else
        allowed_write_access_fs & FILE_WRITE_ACCESS_FS
      end
      add_path_rule(ruleset_fd, path, allowed_access & handled_access_fs)
    end

    raise_system_call_error("prctl") if self.class.set_no_new_privileges.negative?
    if self.class.landlock_restrict_self(ruleset_fd, 0).negative?
      raise_system_call_error("landlock_restrict_self")
    end
  ensure
    close_file_descriptor(ruleset_fd)
  end
end

#command(args, tmpdir) ⇒ Array<String, ::Pathname>

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.

Parameters:

Returns:



286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
# File 'extend/os/linux/sandbox/landlock.rb', line 286

def command(args, tmpdir)
  paths = writable_paths
  @writable_paths = paths.keys | [File::NULL, tmpdir]
  @writable_paths.each { |path| prepare_writable_path(path, paths.fetch(path, :subpath)) }
  denied_read_paths = self.denied_read_paths
  @readable_paths = readable_paths(denied_read_paths)
  @deny_read = denied_read_paths.any?
  @deny_all_network = deny_all_network?
  # Children cannot update the parent's cache, so reserve the warning before forking.
  abi = self.class.abi_version
  @warn_incomplete_network = @deny_all_network && !abi.nil? && abi < MINIMUM_FULL_NETWORK_ABI &&
                             Utils::Output.claim_warning("Landlock incomplete network denial")
  @socket_directory = tmpdir
  args
end

#readable_paths(denied_paths) ⇒ Array<String>

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.

Parameters:

Returns:



409
410
411
412
413
414
415
416
417
418
419
420
421
422
# File 'extend/os/linux/sandbox/landlock.rb', line 409

def readable_paths(denied_paths)
  return [] if denied_paths.empty? || denied_paths.include?(root_path)

  paths = profile_paths(allow: true, operation: "file-read").select { |path| File.exist?(path) }
  root_path.children.sort.each { |path| add_readable_path(path, denied_paths, paths) }
  paths.uniq
rescue Errno::EACCES
  raise <<~EOS
    Cannot set up the Linux sandbox: permission denied when listing #{root_path}.
    Homebrew needs this listing to build its sandbox rules.
    If running inside another sandbox, allow directory listings of #{root_path}
    in its policy or run Homebrew outside it.
  EOS
end

#ruleset_attributes(abi) ⇒ Array<(String, Integer, Integer)>

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.

Parameters:

Returns:



383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
# File 'extend/os/linux/sandbox/landlock.rb', line 383

def ruleset_attributes(abi)
  allowed_access_fs = WRITE_ACCESS_FS
  allowed_access_fs |= ACCESS_FS_REFER if abi >= MINIMUM_ABI
  allowed_access_fs |= ACCESS_FS_TRUNCATE if abi >= MINIMUM_TRUNCATE_ABI
  handled_access_fs = allowed_access_fs
  # IOCTL_DEV is available from ABI 5 and deliberately remains absent from
  # allowed path rules, denying device ioctls opened inside the sandbox:
  # https://www.kernel.org/doc/html/latest/userspace-api/landlock.html#ioctl-support
  handled_access_fs |= ACCESS_FS_IOCTL_DEV if abi >= 5
  handled_access_fs |= READ_ACCESS_FS if @deny_read
  handled_access_fs |= ACCESS_FS_RESOLVE_UNIX if @deny_all_network && abi >= 9

  # Optional ruleset fields are appended as `__u64` members, so only pass
  # the prefix needed for features supported by the running kernel.
  attributes = [handled_access_fs]
  if @deny_all_network && abi >= MINIMUM_NETWORK_ABI
    handled_access_net = ACCESS_NET_BIND_TCP | ACCESS_NET_CONNECT_TCP
    handled_access_net |= ACCESS_NET_BIND_UDP | ACCESS_NET_CONNECT_SEND_UDP if abi >= MINIMUM_FULL_NETWORK_ABI
    attributes << handled_access_net
    attributes << SCOPE_ABSTRACT_UNIX_SOCKET if abi >= 6
  end

  [attributes.pack("Q*"), handled_access_fs, allowed_access_fs]
end