bwrap 1.1.1 → 1.2.0

data/lib/bwrap/args/mount.rb

@@ -6,19 +6,13 @@ require_relative "args"
 module Bwrap::Args::Mount
   # Arguments for readwrite-binding {Config#root} as /.
   private def root_mount
-    return unless @config.root
+    return unless @config&.root
 
     debug "Binding #{@config.root} as /"
     @args.add :root_mount, "--bind", @config.root, "/"
     @args.add :root_mount, "--chdir", "/"
   end
 
-  # Arguments for mounting devtmpfs to /dev.
-  private def dev_mount
-    debug "Mounting new devtmpfs to /dev"
-    @args.add :dev_mounts, "--dev", "/dev"
-  end
-
   # Arguments for mounting procfs to /proc.
   private def proc_mount
     debug "Mounting new procfs to /proc"

data/lib/bwrap/args/network.rb

@@ -17,7 +17,7 @@ class Bwrap::Args::Network
 
   # Arguments to set hostname to whatever is configured.
   def hostname
-    return unless @config.hostname
+    return unless @config&.hostname
 
     debug "Setting hostname to #{@config.hostname}"
     @args.add :hostname, %W{ --hostname #{@config.hostname} }
@@ -35,7 +35,7 @@ class Bwrap::Args::Network
 
   # Arguments to allow network connection inside sandbox.
   def share_net
-    return unless @config.share_net
+    return unless @config&.share_net
 
     verb "Sharing network"
     @args.add :network, %w{ --share-net }

data/lib/bwrap/args/user.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "bwrap/output"
+require_relative "args"
+
+# User related arguments.
+class Bwrap::Args::User
+  include Bwrap::Output
+
+  # Instance of {Config}.
+  attr_writer :config
+
+  # @param args [Args] Args created by {Construct}
+  def initialize args
+    @args = args
+  end
+
+  # Arguments to create `/run/user/#{uid}`.
+  def create_user_dir
+    trace "Creating directory /run/user/#{uid}"
+    @args.add :user_dir, %W{ --dir /run/user/#{uid} }
+  end
+
+  # Arguments to bind necessary pulseaudio data for audio support.
+  def read_only_pulseaudio
+    return unless @config&.audio&.include? :pulseaudio
+
+    debug "Binding pulseaudio"
+    @args.add :audio, %W{ --ro-bind /run/user/#{uid}/pulse /run/user/#{uid}/pulse }
+  end
+
+  # Returns current user id.
+  private def uid
+    Process.uid
+  end
+end

data/lib/bwrap/bwrap.rb

@@ -12,14 +12,27 @@ require "bwrap/execution"
 # using given configuration.
 #
 # @see ::Bwrap Bwrap module for usage example
+#
+# TODO: Add some means to validate what a command would actually bind.
+#   Like, create a method like Bwrap#wrapped_command which would just return the command instead of executing it.
+#   Then add some instructions about this feature, as for security it is important to know what a thing actually does.
+#
+# TODO: There should be a proper shell feature, which binds some always necessary things for shells.
+#   Maybe by default only enough to run a command using a shell, i.e. running “true” would work,
+#   instead of needing to specify its path.
 class Bwrap::Bwrap
   include Bwrap::Execution
 
+  # @note When config is not given, alternative root directory can be specified
+  #   with {#run_inside_root}.
+  #
   # @param config [Bwrap::Config] Configuration used to tailor bwrap
-  def initialize config
+  def initialize config = nil
     # TODO: Ensure that costruct.rb and utilities it uses does not enforce Config to be valid object.
     # Create a test for that also. Well, as long as that makes sense. If it doesn’t work, validate
     # Config object to be valid here.
+    #
+    # Related to above, it is now optional, but a test still needs to be done.
     @config = config
   end
 
@@ -38,35 +51,56 @@ class Bwrap::Bwrap
     Bwrap::Output.handle_output_options options
   end
 
+  # @todo Proper documentation.
+  #
+  # @param command [String, Array] Command to be executed inside bwrap along with necessary arguments
+  # @param config [Bwrap::Config|nil] Configuration to tailor bwrap sandbox.
+  #   Defaults to config given to {#initialize}
+  def build_bwrap_arguments command, config: nil
+    construct = Bwrap::Args::Construct.new
+    construct.command = command
+    construct.config = (config || @config)
+
+    construct.calculate
+    bwrap_args = construct.bwrap_arguments
+    @construct = construct
+
+    exec_command = [ "bwrap" ]
+    exec_command += bwrap_args
+    exec_command.append command
+    exec_command += @cli_args if @cli_args
+
+    exec_command
+  end
+
   # Binds and executes given command available on running system inside bwrap.
   #
   # If {Config#root} has been set, given executable is scanned for necessary
   # libraries and they are bound inside sandbox. This often reduces amount of
   # global binds, but some miscellaneous things may need custom handling.
   #
+  # `kwargs` are passed to {#execute}.
+  #
   # @see Config#features about binding bigger feature sets to sandbox.
   #
   # Executed command is constructed using configuration passed to constructor.
   # After execution has completed, bwrap will also shut down.
   #
   # @param command [String, Array] Command to be executed inside bwrap along with necessary arguments
+  # @option kwargs [Integer]
+  #   log_callback   (1)
+  #   Semi-internal variable used to tailor caller in debug messages
   # @see #run_inside_root to execute a command that already is inside sandbox.
-  def run command
-    construct = Bwrap::Args::Construct.new
-    construct.command = command
-    construct.config = @config
-
-    construct.calculate
-    bwrap_args = construct.bwrap_arguments
+  def run command, **kwargs
+    exec_command = build_bwrap_arguments command
 
-    exec_command = [ "bwrap" ]
-    exec_command += bwrap_args
-    exec_command.append command
-    exec_command += @cli_args if @cli_args
+    # add 1 to log_callback so executing is shown to where this method is called at.
+    kwargs[:log_callback] ||= 1
+    kwargs[:log_callback] += 1
 
-    execute exec_command
+    execute exec_command, **kwargs
 
-    construct.cleanup
+    @construct.cleanup
   end
 
   # Convenience method to executes a command that is inside bwrap.
@@ -75,12 +109,14 @@ class Bwrap::Bwrap
   #
   # Calling this method is equivalent to setting {Config#command_inside_root} to `true`.
   #
+  # `kwargs` are passed to {#execute}.
+  #
   # @note This may have a bit unintuitive usage, as most things are checked anyway, so this is not
   #   akin to running something inside a chroot, but rather for convenience.
   #
   # @param command [String, Array] Command to be executed inside bwrap along with necessary arguments
   # @see #run to execute a command that needs to be bound to the sandbox.
-  def run_inside_root command
+  def run_inside_root command, **kwargs
     if @config
       config = @config.dup
       config.command_inside_root = true
@@ -88,21 +124,15 @@ class Bwrap::Bwrap
       config = nil
     end
 
-    construct = Bwrap::Args::Construct.new
-    construct.command = command
-    construct.config = config
-
-    construct.calculate
-    bwrap_args = construct.bwrap_arguments
+    # add 1 to log_callback so executing is shown to where this method is called at.
+    kwargs[:log_callback] ||= 1
+    kwargs[:log_callback] += 1
 
-    exec_command = [ "bwrap" ]
-    exec_command += bwrap_args
-    exec_command.append command
-    exec_command += @cli_args if @cli_args
+    exec_command = build_bwrap_arguments command, config: config
 
-    execute exec_command
+    execute exec_command, **kwargs
 
-    construct.cleanup
+    @construct.cleanup
   end
 
   # Parses global bwrap flags using Optimist.

data/lib/bwrap/config.rb

@@ -17,6 +17,15 @@ require_relative "config/features"
 # Note that all attributes also have writers, even though they are not documented.
 #
 # @todo Add some documentation about syntax where necessary, like for #binaries_from.
+#
+# TODO: I don’t remember if I made bash feature, but maybe it should be done.
+#   It should automatically bind /bin and /usr/bin, with a flag to bind relevant sbin dirs.
+#   That is because most scripts needs stuff from there. Maybe my fish profile would give some
+#   useful basic stuff?
+#
+# TODO: Maybe I should have something like second-level configuration in variable “advanced” or similar,
+#   which allows controlling features that more directly maps to bwrap cli args? That way it would be easier
+#   to use only high-level features.
 class Bwrap::Config
   # Array of audio schemes usable inside chroot.
   #
@@ -31,6 +40,17 @@ class Bwrap::Config
   # @return [Boolean] `true` if executed command is inside sandbox
   attr_accessor :command_inside_root
 
+  # @return [Boolean] `true` if dummy devtmpfs should be mounted inside sandbox
+  attr_accessor :dev_mount
+
+  # Additional executables to bind to target.
+  #
+  # TODO: Implement this paragraph:
+  # If an executable given here is found from directory given to
+  # {#binaries_from=}, it is not bound to target, but only
+  # dependent libraries.
+  #
+  # @return [#each] Array of executables to bind
   attr_accessor :extra_executables
 
   # TODO: IIRC this doesn’t match the reality any more. So write correct documentation.
@@ -44,6 +64,10 @@ class Bwrap::Config
   # @return [Boolean] true if Linux library loaders are mounted inside chroot
   attr_accessor :full_system_mounts
 
+  # If set to `true`, things like /dev/dri is bound to sandbox to enable usage
+  # of hardware video acceleration, for example.
+  attr_accessor :graphics_acceleration
+
   attr_accessor :hostname
 
   # Set to true if basic system directories, like /usr/lib and /usr/lib64,
@@ -54,6 +78,9 @@ class Bwrap::Config
   # Often it is enough to use {#full_system_mounts=} instead of binding all
   # system libraries using this flag.
   #
+  # It may also make sense to bind specific library directories
+  # using {#ro_binds=}.
+  #
   # @return [Boolean] true if libdirs are mounted to the chroot
   attr_accessor :libdir_mounts
 
@@ -89,11 +116,11 @@ class Bwrap::Config
   #
   # Given paths are also added to PATH environment variable inside sandbox.
   #
-  # @hint At least on SUSE, many executables are symlinks to /etc/alternatives/*,
-  #   which in turn symlinks to versioned executable under the same bindir.
-  #   To use these executables, /etc/alternatives should also be bound:
+  # Hint: At least on SUSE, many executables are symlinks to /etc/alternatives/*,
+  # which in turn symlinks to versioned executable under the same bindir.
+  # To use these executables, /etc/alternatives should also be bound:
   #
-  #       config.ro_binds["/etc/alternatives"] = "/etc/alternatives"
+  #     config.ro_binds["/etc/alternatives"] = "/etc/alternatives"
   #
   # @return [Array] Paths to directories where binaries are looked from.
   attr_reader :binaries_from
@@ -113,10 +140,10 @@ class Bwrap::Config
 
   # @overload ro_binds
   #   `Hash`[`Pathname`] => `Pathname` containing custom read-only binds.
-  # @overload ro_binds=
-  #   Set given hash of paths to be bound with --ro-bind.
+  # @overload ro_binds= binds
+  #   Set given Hash of paths to be bound with --ro-bind.
   #
-  #   Key is source path, value is destination path.
+  #   Key of `binds` is source path, value is destination path.
   #
   #   Given source paths must exist.
   attr_reader :ro_binds

data/lib/bwrap/execution/exec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "execute"
+
+# Actually performs the execution.
+class Bwrap::Execution::Exec
+  # @param value [Boolean] True if execution should be skipped
+  attr_writer :dry_run
+
+  attr_writer :clear_env
+  attr_writer :config
+  attr_writer :direct_output
+  attr_writer :env
+  attr_writer :error
+  attr_writer :fail
+  attr_writer :log
+  attr_writer :rootcmd
+  attr_writer :wait
+
+  attr_reader :last_status
+
+  # @see Bwrap::Execution.do_execute
+  def initialize command
+    @command = command
+
+    @fail = true
+    @wait = true
+    @log = true
+    @direct_output = false
+    @env = nil
+    @clear_env = false
+    @error = nil
+    @config = nil
+    @rootcmd = nil
+  end
+
+  def log_callback= value
+    # Adds one since this is another method in the chain.
+    @log_callback = value + 1
+  end
+
+  def execute
+    # Default to two steps back in history. Hopefully this is correct amount...
+    log_callback = @log_callback || 1
+
+    command = Bwrap::Execution::Execute.format_command @command, rootcmd: @rootcmd, config: @config
+    Bwrap::Execution::Logging.handle_logging command, log_callback: log_callback, log: @log, dry_run: @dry_run
+    return if @dry_run || Bwrap::Execution::Execute.dry_run
+
+    Bwrap::Execution::Execute.open_pipes @direct_output
+
+    # If command is an array, there can’t be arrays inside the array.
+    # For convenience, the array is flattened here, so callers can construct commands more easily.
+    if command.respond_to? :flatten!
+      command.flatten!
+    end
+
+    env = @env || {}
+
+    # If command is string, splat operator (the *) does not do anything. If array, it expand the arguments.
+    # This causes spawning work correctly, as that’s how spawn() expects to have the arguments.
+    pid = spawn(env, *command, err: [ :child, :out ], out: Bwrap::Execution::Execute.w, unsetenv_others: @clear_env)
+
+    output = Bwrap::Execution::Execute.finish_execution(log: @log, wait: @wait, direct_output: @direct_output)
+    return pid unless @wait
+
+    # This is instant return, but allows us to have $?/$CHILD_STATUS set.
+    Process.wait pid
+    @last_status = $CHILD_STATUS
+
+    output = Bwrap::Execution::Execute.process_output output: output
+    Bwrap::Execution::Execute.handle_execution_fail fail: @fail, error: @error, output: output, command: command
+
+    output
+  ensure
+    Bwrap::Execution::Execute.clean_variables
+  end
+end

data/lib/bwrap/execution/execute.rb

@@ -22,24 +22,10 @@ class Bwrap::Execution::Execute
     attr_accessor :dry_run
   end
 
-  # Formats given command for logging, depending on dry-run flag.
-  def self.handle_logging command, log_callback:, log:, dry_run:
-    # The debug message contents will always be evaluated, so can just do it like this.
-    log_command = calculate_log_command command
-
-    if dry_run || Bwrap::Execution::Execute.dry_run
-      puts "Would execute “#{log_command.force_encoding("UTF-8")}” at #{caller_locations(log_callback, 1)[0]}"
-      return
-    end
-
-    return unless log
-
-    msg = "Executing “#{log_command.force_encoding("UTF-8")}” at #{caller_locations(log_callback, 1)[0]}"
-    Bwrap::Output.debug_output msg
-  end
-
-  # @return formatted command.
-  def self.format_command command, rootcmd:
+  # @param rootcmd [Array|Symbol|nil] Flags used to construct bubblewrap environment
+  # @param config [Bwrap::Config|nil] Configuration used to launch the command inside bubblewrap
+  # @return formatted command
+  def self.format_command command, rootcmd: nil, config: nil
     # Flatten the command if required, so nils can be converted in more of cases.
     # Flattenization is also done in executions, but they also take in account
     # for example rootcmd, so they probably should be done in addition to this one.
@@ -47,10 +33,16 @@ class Bwrap::Execution::Execute
       command.flatten!
     end
 
-    replace_nils command
-    return command if rootcmd.nil?
+    prepare_for_execution command
 
-    prepend_rootcmd command, rootcmd: rootcmd
+    if config
+      bwrap = Bwrap::Bwrap.new config
+      bwrap.build_bwrap_arguments command
+    elsif rootcmd
+      prepend_rootcmd command, rootcmd: rootcmd
+    else
+      command
+    end
   end
 
   # Opens pipes for command output handling.
@@ -80,7 +72,8 @@ class Bwrap::Execution::Execute
     exception = Bwrap::Execution::ExecutionFailed.new "Command execution failed",
                                                       command: command,
                                                       output: output
-    raise exception, caller
+
+    raise exception, exception.message, caller
   end
 
   # @note It makes sense for caller to just return if wait has been set and not check output.
@@ -119,31 +112,20 @@ class Bwrap::Execution::Execute
     $CHILD_STATUS.success?
   end
 
-  # Used by `#handle_logging`.
-  private_class_method def self.calculate_log_command command
-    return command.dup unless command.respond_to?(:join)
-
-    temp = command.dup
-
-    # Wrap multi word arguments to quotes, for convenience.
-    # NOTE: This is not exactly safe, but this is only a debugging aid anyway.
-    temp.map! do |argument|
-      if argument.include? " "
-        escaped = argument.gsub '"', '\"'
-        argument = %["#{escaped}"]
-      end
-      argument
-    end
-
-    temp.join(" ")
-  end
-
   # If command is an `Array`, Replaces nil values with "".
-  private_class_method def self.replace_nils command
+  #
+  # Also converts Pathnames to strings.
+  private_class_method def self.prepare_for_execution command
     return unless command.respond_to? :map!
 
     command.map! do |argument|
-      argument.nil? && "" || argument
+      if argument.is_a? Pathname
+        argument.to_s
+      elsif argument.nil?
+        ""
+      else
+        argument
+      end
     end
   end
 

data/lib/bwrap/execution/execution.rb

@@ -3,7 +3,9 @@
 require "bwrap/version"
 require "bwrap/output"
 require_relative "exceptions"
+require_relative "exec"
 require_relative "execute"
+require_relative "logging"
 require_relative "path"
 require_relative "popen2e"
 
@@ -36,68 +38,88 @@ module Bwrap::Execution
   #
   # fail == If true, an error is raised in case the command returns failure code.
   #
-  # @param error if :show, warn()s output of the command is shown if execution failed.
+  # @option kwargs [Boolean]
+  #   clear_env      (false)
+  #   If true, executed command will run with no environment variables
+  # @option kwargs [Bwrap::Config|nil]
+  #   config         (nil)
+  #   Configuration used to launch the command inside bubblewrap
+  # @option kwargs [Boolean]
+  #   direct_output  (false)
+  #   Instead of buffering output, it will be directly outputted to `$stdout`
+  # @option kwargs [Hash<String, String>]
+  #   env            ({})
+  #   Environment variables to add to the command. Also see `clear_env` option
+  # @option kwargs [:show|nil]
+  #   error          (nil)
+  #   if :show and execution failed, prints output of the command with {#warn}
+  # @option kwargs [Boolean]
+  #   fail           (true)
+  #   If true, {ExecutionFailed} is raised if process did not finish successfully
+  # @option kwargs [Boolean]
+  #   log            (true)
+  #   If true, prints output if verbose flag has been set.
+  #   And if a log file has been configured, also logs to that file
+  # @option kwargs [Integer]
+  #   log_callback   (1)
+  #   Semi-internal variable used to tailor caller in debug messages
+  # @option kwargs [Array|Symbol|nil]
+  #   rootcmd        (nil)
+  #   Flags used to construct bubblewrap environment
+  # @option kwargs [Boolean]
+  #   wait           (true)
+  #   If true, this method blocks until the command has finished.
+  #   Otherwise returns immediately. It is possible for user to
+  #   call `Process.wait` to wait for result at suitable place
+  #
+  # TODO: log kwarg could take log level as argument. Like :trace.
   #
   # @see #execute
-  def self.do_execute command,
-                      fail: true,
-                      wait: true,
-                      log: true,
-                      direct_output: false,
-                      env: {},
-                      clear_env: false,
-                      error: nil,
-                      log_callback: 2,
-                      rootcmd: nil
-    command = Execute.format_command command, rootcmd: rootcmd
-    Execute.handle_logging command, log_callback: log_callback, log: log, dry_run: @dry_run
-    return if @dry_run || Bwrap::Execution::Execute.dry_run
+  def self.do_execute command, **kwargs
+    executor = Exec.new command
+    executor.dry_run = @dry_run
 
-    Execute.open_pipes direct_output
+    executor.clear_env      = kwargs.key?(:clear_env)     ? kwargs.delete(:clear_env)     : false
+    executor.config         = kwargs.key?(:config)        ? kwargs.delete(:config)        : nil
+    executor.direct_output  = kwargs.key?(:direct_output) ? kwargs.delete(:direct_output) : false
+    executor.env            = kwargs.key?(:env)           ? kwargs.delete(:env)           : {}
+    executor.error          = kwargs.key?(:error)         ? kwargs.delete(:error)         : nil
+    executor.fail           = kwargs.key?(:fail)          ? kwargs.delete(:fail)          : true
+    executor.log            = kwargs.key?(:log)           ? kwargs.delete(:log)           : true
+    executor.log_callback   = kwargs.key?(:log_callback)  ? kwargs.delete(:log_callback)  : 1
+    executor.rootcmd        = kwargs.key?(:rootcmd)       ? kwargs.delete(:rootcmd)       : nil
+    executor.wait           = kwargs.key?(:wait)          ? kwargs.delete(:wait)          : true
 
-    # If command is an array, there can’t be arrays inside the array.
-    # For convenience, the array is flattened here, so callers can construct commands more easily.
-    if command.respond_to? :flatten!
-      command.flatten!
+    unless kwargs.empty?
+      raise ArgumentError, %{unknown keywords: #{kwargs.keys.join ","}}
     end
 
-    # If command is string, splat operator (the *) does not do anything. If array, it expand the arguments.
-    # This causes spawning work correctly, as that’s how spawn() expects to have the arguments.
-    pid = spawn(env, *command, err: [ :child, :out ], out: Execute.w, unsetenv_others: clear_env)
-    output = Execute.finish_execution(log: log, wait: wait, direct_output: direct_output)
-    return pid unless wait
-
-    # This is instant return, but allows us to have $?/$CHILD_STATUS set.
-    Process.wait pid
-    @last_status = $CHILD_STATUS
-
-    output = Execute.process_output output: output
-    Execute.handle_execution_fail fail: fail, error: error, output: output, command: command
-    output
+    executor.execute
   ensure
-    Execute.clean_variables
+    @last_status = executor.last_status if executor&.last_status
   end
 
-  # Works similarly to {Open3.popen2e}.
-  #
-  # TODO: If there will be any difference to input syntax, document those differences here.
-  # For now, rootcmd option has been implemented.
+  # Works similarly to Ruby’s official `Open3.popen2e`.
   #
-  # A block is accepted, as does {Open3.popen2e}. For now, at least.
-  #
-  # TODO: Implement this so that this uses same execution things as other things here.
-  # This way bwrap actually can be integrated to this...
+  # A block is accepted, as does `Open3.popen2e`. For now, at least.
   #
   # TODO: Verify default log_callback is correct
   #
   # @warning Only array style commands are accepted. For example, `ls /`
-  # is not ok, but `ls` or `%w{ ls / }` is ok.
-  def popen2e *cmd, rootcmd: nil, log_callback: 1, log: true, &block
-    popen = Bwrap::Execution::Popen2e.new
-    popen.dry_run = @dry_run
-    popen.popen2e(*cmd, rootcmd: rootcmd, log_callback: log_callback, log: log, &block)
+  #   is not ok, but `ls` or `%w{ ls / }` is ok.
+  #
+  # @param config [Bwrap::Config] Configuration used to launch the executable inside bubblewrap
+  # @param rootcmd [Array|Symbol|nil] A strange way to use bwrap. Probably no sense to use this
+  # @param log [Boolean]
+  #   If true, prints output if verbose flag has been set.
+  #   And if a log file has been configured, also logs to that file
+  # @option log_callback [Integer] Semi-internal variable used to tailor caller in debug messages
+  def popen2e *cmd, rootcmd: nil, config: nil, log_callback: 2, log: true, &block
+    popen = Bwrap::Execution::Popen2e.new rootcmd: rootcmd, config: config
+    popen.dry_run = @dry_run # TODO: Add a test that tests that this works as it works with execute().
+    popen.popen2e(*cmd, log_callback: log_callback, log: log, &block)
   ensure
-    @last_status = $CHILD_STATUS
+    @last_status = popen&.child_status
   end
   module_function :popen2e
 
@@ -115,13 +137,18 @@ module Bwrap::Execution
   # execute commands.
   #
   # @see .do_execute .do_execute for documentation of argument syntax
+  #
+  # TODO Default log_callback should be 2 or something, and callers should add one for each subsequent method.
   private def execute *args, **kwargs
     # Mangle proper location to error message.
     if kwargs.is_a? Hash
-      kwargs[:log_callback] = 3
+      kwargs[:log_callback] ||= 1
     else
-      kwargs = { log_callback: 3 }
+      kwargs = { log_callback: 1 }
     end
+    # Add 1 to log callback so execution is shown to be from caller.
+    kwargs[:log_callback] += 1
+
     Bwrap::Execution.do_execute(*args, **kwargs)
   end
 
@@ -162,7 +189,7 @@ module Bwrap::Execution
       Bundler.with_unbundled_env do
         yield 2
       end
-    elsif Bundler&.bundler_major_version == 1
+    elsif (Bundler&.bundler_major_version) == 1
       Bundler.with_clean_env do
         yield 1
       end