bwrap 1.0.0.pre.alpha5 → 1.0.0

data/lib/bwrap/args/library.rb

@@ -6,7 +6,7 @@ require_relative "args"
 
 # Class to clean up namespace for implementation specific reasons.
 #
-# @api internal
+# @api private
 class Bwrap::Args::Library
   include Bwrap::Execution
   include Bwrap::Output
@@ -14,6 +14,11 @@ class Bwrap::Args::Library
   # NOTE: This caching can be made more efficient, but need to look at it later, what to do about it.
   @@needed_libraries_cache ||= []
 
+  # Empties {@@needed_libraries_cache}.
+  def self.clear_needed_libraries_cache
+    @@needed_libraries_cache.clear
+  end
+
   # Otherwise similar to {#needed_libraries}, but checks used libc to handle musl executables.
   #
   # @param executable [String] Path to the executable to find dependencies for
@@ -99,17 +104,17 @@ class Bwrap::Args::Library
     binary_path, libraries_line = line.split "::SEPARATOR::"
     libraries = libraries_line.split ","
 
-    @needed_libraries += libraries
+    (@needed_libraries & libraries).each do |library|
+      verb "Binding #{library} as dependency of #{binary_path}"
+    end
+
+    @needed_libraries |= libraries
 
     # Also check if requisite libraries needs some libraries.
     inner = Bwrap::Args::Library.new
-    @needed_libraries += inner.needed_libraries libraries
+    @needed_libraries |= inner.needed_libraries libraries
 
-    # Mark library cached only after its dependencies have been also handled.
-    libraries.each do |library|
-      verb "Binding #{library} as dependency of #{binary_path}"
-      @@needed_libraries_cache << library
-    end
+    @@needed_libraries_cache |= libraries
   end
 
   # Used by {#musl_needed_libraries}.
@@ -120,11 +125,13 @@ class Bwrap::Args::Library
     matches = library_data.match(/(.*) \(0x[0-9a-f]+\)/)
     library_path = matches[1]
 
-    @needed_libraries << library_path
+    unless @needed_libraries.include? library_path
+      @needed_libraries << library_path
+    end
 
     # Also check if requisite libraries needs some libraries.
     inner = Bwrap::Args::Library.new
-    @needed_libraries += inner.musl_needed_libraries library_path
+    @needed_libraries |= inner.musl_needed_libraries library_path
   end
 end
 # class Library ended

data/lib/bwrap/args/machine_id.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "securerandom"
+require "tempfile"
 
 require "bwrap/output"
 require_relative "args"
@@ -24,7 +25,7 @@ class Bwrap::Args::MachineId
     # Returning [] means that execute() will ignore this fully.
     # Nil would be converted to empty string, causing spawn() to pass it as argument, causing
     # bwrap to misbehave.
-    return unless @config.machine_id
+    return unless @config&.machine_id
 
     machine_id = @config.machine_id
 
@@ -51,10 +52,10 @@ class Bwrap::Args::MachineId
     debug "Using random machine id as /etc/machine-id"
 
     @machine_id_file = Tempfile.new "bwrap-random_machine_id-", @config.tmpdir
-    @machine_id_file.write SecureRandom.uuid.gsub("-", "")
+    @machine_id_file.write SecureRandom.uuid.tr("-", "")
     @machine_id_file.flush
 
-    %W{ --ro-bind-data #{machine_id_file.fileno} /etc/machine-id }
+    %W{ --ro-bind-data #{@machine_id_file.fileno} /etc/machine-id }
   end
 
   # Uses `10000000000000000000000000000000` as machine id.
@@ -79,6 +80,8 @@ class Bwrap::Args::MachineId
   end
 
   # Uses file inside sandbox directory as machine id.
+  #
+  # TODO: I kind of want to deprecate this one. It may make sense, but eh... Let’s see.
   private def machine_id_inside_sandbox_dir sandbox_directory
     machine_id_file = "#{sandbox_directory}/machine-id"
 

data/lib/bwrap/args/mount.rb

@@ -10,6 +10,7 @@ module Bwrap::Args::Mount
 
     debug "Binding #{@config.root} as /"
     @args.append %W{ --bind #{@config.root} / }
+    @args.append %w{ --chdir / }
   end
 
   # Arguments for mounting devtmpfs to /dev.

data/lib/bwrap/bwrap.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+#require "deep-cover" if ENV["DEEP_COVER"]
+
+require_relative "bwrap_module"
+require "bwrap/version"
+require "bwrap/args/construct"
+require "bwrap/config"
+require "bwrap/execution"
+
+# Executes given command under {https://github.com/containers/bubblewrap bwrap}
+# using given configuration.
+#
+# @see ::Bwrap Bwrap module for usage example
+class Bwrap::Bwrap
+  include Bwrap::Execution
+
+  # @param config [Bwrap::Config] Configuration used to tailor bwrap
+  def initialize config
+    # 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.
+    @config = config
+  end
+
+  # Parses command line arguments given to caller script.
+  #
+  # @note This method automatically sets output levels according parsed
+  #   options. It is also possible to set the levels manually using
+  #   {Bwrap::Output.handle_output_options}, for example with flags
+  #   parsed with optparse’s `OptionParser`, found in Ruby’s standard
+  #   library.
+  #
+  # @warning Requires optimist gem to be installed, which is not a dependency of this gem.
+  def parse_command_line_arguments
+    options = parse_options
+
+    Bwrap::Output.handle_output_options options
+  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.
+  #
+  # @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
+  # @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
+    bwrap_args = construct.construct_bwrap_args
+
+    exec_command = [ "bwrap" ]
+    exec_command += bwrap_args
+    exec_command.append command
+    exec_command += @cli_args if @cli_args
+
+    execute exec_command
+
+    construct.cleanup
+  end
+
+  # Convenience method to executes a command that is inside bwrap.
+  #
+  # Given command is expected to already be inside {Config#root}.
+  #
+  # Calling this method is equivalent to setting {Config#command_inside_root} to `true`.
+  #
+  # @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
+    if @config
+      config = @config.dup
+      config.command_inside_root = true
+    else
+      config = nil
+    end
+
+    construct = Bwrap::Args::Construct.new
+    construct.command = command
+    construct.config = config
+    bwrap_args = construct.construct_bwrap_args
+
+    exec_command = [ "bwrap" ]
+    exec_command += bwrap_args
+    exec_command.append command
+    exec_command += @cli_args if @cli_args
+
+    execute exec_command
+
+    construct.cleanup
+  end
+
+  # Parses global bwrap flags using Optimist.
+  #
+  # Sets instance variable `@cli_args`.
+  #
+  # @warning Requires optimist gem to be installed, which is not a dependency of this gem.
+  #
+  # @api private
+  # @return [Hash] options parsed by `Optimist.options`
+  private def parse_options
+    begin
+      require "optimist"
+    rescue LoadError => e
+      puts "Failed to load optimist gem. In order to use Bwrap::Bwrap#parse_command_line_arguments, " \
+           "ensure optimist gem is present for example in your Gemfile."
+      puts
+      raise e
+    end
+
+    options = Optimist.options do
+      version ::Bwrap::VERSION
+
+      banner "Usage:"
+      banner "  #{$PROGRAM_NAME} [global options]\n \n"
+      banner "Global options:"
+      opt :verbose,
+          "Show verbose output",
+          short: "v"
+      opt :debug,
+          "Show debug output (useful when debugging a problem)",
+          short: "d"
+      opt :trace,
+          "Show trace output (noisiest, probably not useful for most of time)",
+          short: :none
+      opt :version,
+          "Print version and exit",
+          short: "V"
+      opt :help,
+          "Show help message",
+          short: "h"
+
+      educate_on_error
+    end
+
+    @cli_args = ARGV.dup
+
+    options
+  end
+end

data/lib/bwrap/bwrap_module.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# ruby-bwrap provides easy-to-use interface to run complex programs in sandboxes created with
+# {https://github.com/containers/bubblewrap bubblewrap}.
+#
+# To run a program inside bubblewrap, a wrapper executable can be created. For example:
+#
+#     require "bwrap"
+#
+#     config = Bwrap::Config.new
+#     config.user = "dummy_user"
+#     config.full_system_mounts = true
+#     config.binaries_from = %w{
+#       /bin
+#       /usr/bin
+#     }
+#
+#     bwrap = Bwrap::Bwrap.new config
+#     bwrap.parse_command_line_arguments
+#     bwrap.run "/bin/true"
+#
+# There also are few generic utilities, {Bwrap::Output} for handling output of scripts and
+# {Bwrap::Execution} to run executables.
+module Bwrap
+  # Empty module.
+end

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,9 @@ 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.
@@ -35,34 +85,23 @@ class Bwrap::Config
   # @return [Boolean] Whether Xorg specific binds are used.
   attr_accessor :xorg_application
 
-  # Array of audio schemes usable inside chroot.
+  # Array of directories to be bind mounted in sandbox.
   #
-  # Currently supports:
-  #   - :pulseaudio
+  # Given paths are also added to PATH environment variable inside sandbox.
   #
-  attr_accessor :audio
-
-  # @return [Boolean] true if network should be shared from host.
-  attr_accessor :share_net
-
-  # TODO: This should cause Bind#full_system_mounts to mount /lib64/ld-linux-x86-64.so.2 and so on,
-  # probably according executable type of specified command. But that needs some magic.
+  # @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:
   #
-  # For now this just mounts all relevant files it can find.
+  #       config.ro_binds["/etc/alternatives"] = "/etc/alternatives"
   #
-  # @return [Boolean] true if Linux library loaders are mounted inside chroot
-  attr_accessor :full_system_mounts
+  # @return [Array] Paths to directories where binaries are looked from.
+  attr_reader :binaries_from
 
-  # Set to true if basic system directories, like /usr/lib and /usr/lib64,
-  # should be bound inside chroot.
+  # Paths to be added to sandbox instance’s PATH environment variable.
   #
-  # /usr/bin can be mounted using {Config#binaries_from=}.
-  #
-  # @return [Boolean] true if libdirs are mounted to the chroot
-  attr_accessor :libdir_mounts
-
-  # Array of directories to be bind mounted and used to construct PATH environment variable.
-  attr_reader :binaries_from
+  # @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 ...
@@ -72,71 +111,34 @@ class Bwrap::Config
   # Use given directory as root. End result is similar to classic chroot.
   attr_reader :root
 
-  # `Hash`[`Pathname`] => `Pathname` containing custom read-only binds.
+  # @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.
+  #   Defaults to Dir.tmpdir.
+  # @overload tmpdir=(dir)
+  #   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
   attr_reader :tmpdir
 
-  # Methods to enable or disable feature sets to control various aspects of sandboxing.
-  class Features
-    # Defines Ruby feature set.
-    class Ruby
-      # @return [Array] list of needed libraries.
-      attr_reader :stdlib
-
-      def initialize
-        @stdlib = []
-      end
-
-      # @see enabled=
-      def enabled?
-        @enabled
-      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.
-      def enable
-        @enabled = true
-      end
-
-      # Disable Ruby feature set.
-      def disable
-        @enabled = false
-      end
-
-      # 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.
-      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 [Ruby] Instance of feature class for Ruby
-    def ruby
-      @ruby ||= Ruby.new
-    end
-  end
-
   def initialize
+    @audio = []
     @binaries_from = []
+    @env_paths = []
+    @ro_binds = {}
     @tmpdir = Dir.tmpdir
-    @audio = []
   end
 
   def binaries_from= array
@@ -178,14 +180,13 @@ class Bwrap::Config
     @root = 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.
   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."
@@ -197,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