bwrap 1.0.0.pre.alpha3 → 1.0.0.pre.beta2

data/lib/bwrap/config/features.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+class Bwrap::Config
+  # Methods to enable or disable feature sets to control various aspects of sandboxing.
+  class Features
+    # @abstract
+    #
+    # Base of all features.
+    class Base
+      # @param features [Bwrap::Config::Features] Instance of features object in {Config}
+      def initialize features
+        @features = features
+      end
+
+      # Checks if the feature has been enabled.
+      #
+      # @return [Boolean] whether feature is enabled
+      def enabled?
+        @enabled
+      end
+
+      # Enable the feature.
+      def enable
+        @enabled = true
+      end
+
+      # Disable the feature.
+      def disable
+        @enabled = false
+      end
+    end
+
+    # Defines Bash feature set.
+    class Bash < Base
+      # Nya.
+    end
+
+    # Defines Nscd feature set.
+    #
+    # nscd is short of name service cache daemon. It may make sense to
+    # have this class under another name, but I don’t know how nscd specific
+    # this feature can be, so this name it is for now.
+    class Nscd < Base
+      # Nya.
+    end
+
+    # Defines Ruby feature set.
+    #
+    # Implies {Nscd} feature.
+    class Ruby < Base
+      # Extra libraries to be loaded from `RbConfig::CONFIG["rubyarchdir"]`.
+      #
+      # @note This is only required to be called if extra dependencies are necessary.
+      #     For example, psych.so requires libyaml.so.
+      #
+      # @return [Array] list of needed libraries.
+      #
+      # @overload stdlib
+      # @overload stdlib=(libs)
+      attr_reader :stdlib
+
+      def initialize features
+        super features
+
+        @gem_env_paths = true
+        @stdlib = []
+      end
+
+      # @return true if bindirs from “gem environment” should be added to sandbox.
+      def gem_env_paths?
+        @gem_env_paths
+      end
+
+      # Enable Ruby feature set.
+      #
+      # Among others, binds `RbConfig::CONFIG["sitedir"]` so scripts works.
+      #
+      # @note This does not allow development headers needed for compilation for now.
+      #   I’ll look at it after I have an use for it.
+      #
+      # @note Also enables {Nscd} feature.
+      def enable
+        super
+
+        @features.nscd.enable
+      end
+
+      # @see #stdlib
+      def stdlib= libs
+        # Just a little check to have error earlier.
+        libs.each do |lib|
+          unless File.exist? "#{RbConfig::CONFIG["rubyarchdir"]}/#{lib}.so"
+            raise "Library “#{lib}” passed to Bwrap::Config::Ruby.stdlib= does not exist."
+          end
+        end
+
+        @stdlib = libs
+      end
+    end
+
+    # @return [Bash] Instance of feature class for Bash
+    def bash
+      @bash ||= Bash.new self
+    end
+
+    # @return [Nscd] Instance of feature class for nscd
+    def nscd
+      @nscd ||= Nscd.new self
+    end
+
+    # @return [Ruby] Instance of feature class for Ruby
+    def ruby
+      @ruby ||= Ruby.new self
+    end
+  end
+end

data/lib/bwrap/config.rb

@@ -3,13 +3,60 @@
 require "bwrap/output"
 require "bwrap/version"
 
-# Represents configuration set by user for bwrap execution.
+# Features classes, used through {Config#features}.
+require_relative "config/features"
+
+# Represents configuration used to tailor bwrap execution.
+#
+# @developer_note
+#   Logger methods (debug, warn and so on) can’t be used here as logger
+#   isn’t initialized before this class.
+#
+#   For same reason, it’s not advised to execute anything here.
 #
-# Implementation NOTE: logger methods (debug, warn and so on) can’t be used here as logger
-# isn’t initialized before this class.
+# 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.
 class Bwrap::Config
+  # Array of audio schemes usable inside chroot.
+  #
+  # Currently supports:
+  #   - :pulseaudio
+  #
+  attr_accessor :audio
+
+  # Set to `true` if command given to {Bwrap::Bwrap#run} is expected to
+  # be inside sandbox, and not bound from host.
+  #
+  # @return [Boolean] `true` if executed command is inside sandbox
+  attr_accessor :command_inside_root
+
+  attr_accessor :extra_executables
+
+  # TODO: IIRC this doesn’t match the reality any more. So write correct documentation.
+  #
+  # Causes libraries required by the executable given to {Bwrap#run} to be
+  # mounted inside sandbox.
+  #
+  # Often it is enough to use this flag instead of binding all system libraries
+  # using {#libdir_mounts=}
+  #
+  # @return [Boolean] true if Linux library loaders are mounted inside chroot
+  attr_accessor :full_system_mounts
+
   attr_accessor :hostname
 
+  # Set to true if basic system directories, like /usr/lib and /usr/lib64,
+  # should be bound inside chroot.
+  #
+  # /usr/bin can be mounted using {Config#binaries_from=}.
+  #
+  # Often it is enough to use {#full_system_mounts=} instead of binding all
+  # system libraries using this flag.
+  #
+  # @return [Boolean] true if libdirs are mounted to the chroot
+  attr_accessor :libdir_mounts
+
   # What should be used as /etc/machine_id file.
   #
   # If not specified, no /etc/machine_id handling is done.
@@ -24,6 +71,12 @@ class Bwrap::Config
   #   Given file as bound as /etc/machine_id.
   attr_accessor :machine_id
 
+  # @return [Boolean] true if network should be shared from host.
+  attr_accessor :share_net
+
+  # Name of the user inside chroot.
+  #
+  # This is optional and defaults to no user.
   attr_accessor :user
 
   # Set to true to indicate we’re running a X.org application, meaning we need to do some extra holes,
@@ -32,21 +85,59 @@ class Bwrap::Config
   # @return [Boolean] Whether Xorg specific binds are used.
   attr_accessor :xorg_application
 
-  # Array of directories to be bind mounted and used to construct PATH environment variable.
+  # Array of directories to be bind mounted in sandbox.
+  #
+  # 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:
+  #
+  #       config.ro_binds["/etc/alternatives"] = "/etc/alternatives"
+  #
+  # @return [Array] Paths to directories where binaries are looked from.
   attr_reader :binaries_from
 
+  # Paths to be added to sandbox instance’s PATH environment variable.
+  #
+  # @see #add_env_path
+  attr_reader :env_paths
+
+  # TODO: Document this.
+  # TODO: I wonder if this should just be removed. I don’t know, this is a bit ...
+  # Well, I can see it can have some merit, but very hard to say.
   attr_reader :sandbox_directory
 
-  # `Hash`[`Pathname`] => `Pathname` containing custom read-only binds.
+  # Use given directory as root. End result is similar to classic chroot.
+  attr_reader :root
+
+  # @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.
+  #
+  #   Key is source path, value is destination path.
+  #
+  #   Given source paths must exist.
   attr_reader :ro_binds
 
-  # Path to temporary directory.
+  # @overload tmpdir
+  #   Path to temporary directory.
+  #
+  #   Defaults to Dir.tmpdir.
+  # @overload tmpdir=(dir)
+  #   Sets given directory as temporary directory for certain operations.
   #
-  # Defaults to Dir.tmpdir.
+  #   @note Requires `dir` to be path to existing directory.
+  #   @raise [RuntimeError] If given directory does not exist
+  #   @param dir Path to temporary directory
   attr_reader :tmpdir
 
   def initialize
+    @audio = []
     @binaries_from = []
+    @env_paths = []
+    @ro_binds = {}
     @tmpdir = Dir.tmpdir
   end
 
@@ -61,6 +152,17 @@ class Bwrap::Config
     end
   end
 
+  # Enable or disable feature sets to control various aspects of sandboxing.
+  #
+  # @example To enable Ruby feature set
+  #     @config.features.ruby = true
+  #
+  # @see {Features} List of available features
+  # @return [Features] Object used to toggle features
+  def features
+    @features ||= ::Bwrap::Config::Features.new
+  end
+
   def sandbox_directory= directory
     unless Dir.exist? directory
       raise "Given sandbox directory #{directory} does not exist. Please create it beforehand and setup to your needs."
@@ -69,14 +171,22 @@ class Bwrap::Config
     @sandbox_directory = directory
   end
 
-  # Set given hash of paths to be bound with --ro-bind.
-  #
-  # Key is source path, value is destination path.
-  #
-  # Given source paths must exist.
+  # Directory used as writable root, akin to classic chroot.
+  def root= directory
+    unless Dir.exist? directory
+      raise "Given root directory #{directory} does not exist. Please create it beforehand and set up to your needs."
+    end
+
+    @root = directory
+  end
+
   def ro_binds= binds
     @ro_binds = {}
     binds.each do |source_path, destination_path|
+      if destination_path.nil?
+        raise "binds should be key-value storage of Strings, for example a Hash."
+      end
+
       source_path = Pathname.new source_path
       unless source_path.exist?
         raise "Given read only bind does not exist. Please check path “#{source_path}” is correct."
@@ -88,14 +198,17 @@ class Bwrap::Config
     end
   end
 
-  # Sets given directory as temporary directory for certain operations.
-  #
-  # @note Requires `dir` to be path to existing directory.
-  # @raise [RuntimeError] If given directory does not exist
-  # @param dir Path to temporary directory
+  # See attr_accessor :tmpdir for documentation.
   def tmpdir= dir
     raise "Directory to be set as a temporary directory, “#{dir}”, does not exist." unless Dir.exist? dir
 
     @tmpdir = dir
   end
+
+  # Add a path to sandbox instance’s PATH environment variable.
+  #
+  # @param path [String] Path to be added added to PATH environment variable
+  def add_env_path path
+    @env_paths << path
+  end
 end

data/lib/bwrap/execution/exceptions.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Bwrap::Execution
+  # Unspecified execution related error.
+  class CommandError < StandardError
+  end
+
+  # Signifies that command execution has failed.
+  class ExecutionFailed < CommandError
+  end
+
+  # Thrown if given command was not found.
+  class CommandNotFound < CommandError
+    # Command that was looked at.
+    attr_reader :command
+
+    def initialize command:
+      @command = command
+      msg = "Failed to find #{command} from PATH."
+
+      super msg
+    end
+  end
+end

data/lib/bwrap/execution/execute.rb

@@ -3,11 +3,14 @@
 # force_encoding modifies string, so can’t freeze strings.
 
 require "bwrap/output"
+require_relative "exceptions"
 require_relative "execution"
 
 # Methods that performs actual execution logic.
 #
-# @api internal
+# @note This is kind of pseudo-internal API. Hopefully there won’t be breaking changes.
+#   But please use {Bwrap::Execution} instead of relying functionality of this class,
+#   outside of {.prepend_rootcmd}.
 class Bwrap::Execution::Execute
   include Bwrap::Output
 
@@ -95,7 +98,7 @@ class Bwrap::Execution::Execute
   # Stub to instruct implementation in subclass.
   def self.prepend_rootcmd command, rootcmd:
     raise NotImplementedError, "If rootcmd execution is necessary, monkey patch Bwrap::Execution::Execute " \
-          "to add “self.prepend_rootcmd(command, rootcmd:)” method."
+                               "to add “self.prepend_rootcmd(command, rootcmd:)” method."
   end
 
   # Used by `#handle_logging`.

data/lib/bwrap/execution/execution.rb

@@ -1,8 +1,152 @@
 # frozen_string_literal: true
 
 require "bwrap/version"
+require "bwrap/output"
+require_relative "exceptions"
+require_relative "execute"
+require_relative "path"
 
-# Generic execution functionality.
+# Provides methods to execute commands and handle its output.
+#
+# Output can be controlled by using log levels of Output module.
+#
+# @example Executing a command
+#   class MyClass
+#     include Bwrap::Execution
+#
+#     def my_method
+#       execute %w{ ls /dev/null }
 module Bwrap::Execution
-  # Nyan.
-end
+  include Bwrap::Output
+  include Bwrap::Execution::Path
+
+  # Actual implementation of execution command. Can be used when static method is needed.
+  #
+  # @note When an array is given as a command, empty strings are passed as empty arguments.
+  #
+  #   This means that `[ "foo", "bar" ]` passes one argument to "foo" command, when
+  #   `[ "foo", "", "bar" ]` passes two arguments.
+  #
+  #   This may or may not be what is assumed, so it can’t be fixed here. It is up to the
+  #   command to decide how to handle empty arguments.
+  #
+  # Returns pid of executed command if wait is false.
+  # Returns command output if wait is true.
+  #
+  # 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.
+  #
+  # @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
+
+    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
+
+    # 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 argu
+    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
+    output
+  ensure
+    Execute.clean_variables
+  end
+
+  # Returns Process::Status instance of last execution.
+  #
+  # @note This only is able to return the status if wait is true, as otherwise caller is assumed to
+  # handle execution flow.
+  def self.last_status
+    @last_status
+  end
+
+  # Execute a command.
+  #
+  # This method can be used by including Execution module in a class that should be able to
+  # execute commands.
+  #
+  # @see .do_execute .do_execute for documentation of argument syntax
+  private def execute *args, **kwargs
+    # Mangle proper location to error message.
+    if kwargs.is_a? Hash
+      kwargs[:log_callback] = 3
+    else
+      kwargs = { log_callback: 3 }
+    end
+    Bwrap::Execution.do_execute(*args, **kwargs)
+  end
+
+  # Same as ::execute, but uses log: false to avoid unnecessary output when we’re just getting a
+  # value for internal needs.
+  #
+  # Defaults to fail: false, since when one just wants to get the value, there is not that much
+  # need to unconditionally die if getting bad exit code.
+  private def execvalue *args, fail: false, log: false, **kwargs
+    # This logging handling is a bit of duplication from execute(), but to be extra safe, it is duplicated.
+    # The debug message contents will always be evaluated, so can just do it like this.
+    log_command = args[0].respond_to?(:join) && args[0].join(" ") || args[0]
+    log_command =
+        if log_command.frozen?
+          log_command.dup.force_encoding("UTF-8")
+        else
+          log_command.force_encoding("UTF-8")
+        end
+    if @dry_run
+      puts "Would execvalue “#{log_command}” at #{caller_locations(1, 1)[0]}"
+      return
+    end
+    trace "Execvaluing “#{log_command}” at #{caller_locations(1, 1)[0]}"
+    execute(*args, fail: fail, log: log, **kwargs)
+  end
+
+  private def exec_success?
+    $CHILD_STATUS.success?
+  end
+
+  private def exec_failure?
+    !exec_success?
+  end
+
+  # When running through bundler, don’t use whatever it defines as we’re running inside chroot.
+  private def clean_execute
+    if (Bundler&.bundler_major_version) >= 2
+      Bundler.with_unbundled_env do
+        yield 2
+      end
+    elsif Bundler&.bundler_major_version == 1
+      Bundler.with_clean_env do
+        yield 1
+      end
+    else
+      yield nil
+    end
+  rescue NameError
+    # If NameError is thrown, no Bundler is available.
+    yield nil
+  end
+end

data/lib/bwrap/execution/labels.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
 require "bwrap/version"
-require_relative "execution"
+
+# Just declaring the module here so full Execution module
+# doesn’t need to be required just to have labels.
+#
+# Most users probably should just require bwrap/execution directly
+# instead of this file, but bwrap/output.rb benefits from this.
+module Bwrap::Execution
+end
 
 # Exit codes for exit status handling.
 #

data/lib/bwrap/execution/path.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "bwrap/output"
+require_relative "exceptions"
+
+# Path checking methods.
+module Bwrap::Execution::Path
+  # Utilities to handle environment path operations.
+  #
+  # @api private
+  class Environment
+    # Loop through each path in global PATH environment variable to
+    # perform an operation in each path, for example to resolve
+    # absolute path to a command.
+    #
+    # NOTE: This has nothing to do with {Bwrap::Config#env_paths}, as the
+    # env paths looped are what the system has defined, in ENV["PATH"].
+    #
+    # Should be cross-platform.
+    #
+    # @yield Command appended to each path in PATH environment variable
+    # @yieldparam path [String] Full path to executable
+    def self.each_env_path command, env_path_var: ENV["PATH"]
+      exts = ENV["PATHEXT"] ? ENV["PATHEXT"].split(";") : [ "" ]
+
+      env_path_var.split(File::PATH_SEPARATOR).each do |env_path|
+        exts.each do |ext|
+          exe = File.join(env_path, "#{command}#{ext}")
+          yield exe
+        end
+      end
+    end
+  end
+
+  # Check if requested program can be found.
+  #
+  # Should work cross-platform and in restricted environments pretty well.
+  #
+  # @param command [String] executable to be resolved
+  # @param env_path_var [String] PATH environment variable as string.
+  #   Defaults to `ENV["PATH"]`
+  private def command_available? command, env_path_var: ENV["PATH"]
+    # Special handling for absolute paths.
+    path = Pathname.new command
+    if path.absolute?
+      if path.executable? && !path.directory?
+        return true
+      end
+
+      return false
+    end
+
+    Bwrap::Execution::Path::Environment.each_env_path command, env_path_var: env_path_var do |exe|
+      return true if File.executable?(exe) && !File.directory?(exe)
+    end
+
+    false
+  end
+
+  # Returns path to given executable.
+  #
+  # @param (see #command_available?)
+  private def which command, fail: true, env_path_var: ENV["PATH"]
+    # Special handling for absolute paths.
+    path = Pathname.new command
+    if path.absolute?
+      if path.executable?
+        return command
+      end
+
+      raise Bwrap::Execution::CommandNotFound.new command: command if fail
+
+      return nil
+    end
+
+    Bwrap::Execution::Path::Environment.each_env_path command, env_path_var: env_path_var do |exe|
+      return exe if File.executable?(exe) && !File.directory?(exe)
+    end
+
+    return nil unless fail
+
+    raise Bwrap::Execution::CommandNotFound.new command: command
+  end
+end