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

data/lib/bwrap/args/environment.rb

@@ -1,24 +1,82 @@
 # frozen_string_literal: true
 
+require "bwrap/execution"
 require "bwrap/output"
 require_relative "args"
 
 # Environment variable calculation for bwrap.
 class Bwrap::Args::Environment < Hash
+  include Bwrap::Execution
   include Bwrap::Output
 
   # Instance of {Config}.
   attr_writer :config
 
-  # Returns used environment variables.
+  def initialize
+    super
+
+    self["PATH"] ||= []
+  end
+
+  # Returns used environment variables wrapped as bwrap arguments.
   def environment_variables
     if debug?
       debug "Passing following environment variables to bwrap:\n" \
             "#{self}"
     end
 
+    env_paths
+
     map do |key, value|
+      if key == "PATH" and value.respond_to? :join
+        value = value.join ":"
+      end
+
       [ "--setenv", key, value ]
     end
   end
+
+  # @return [Array] All environment paths added via {Config#add_env_path} and other parsing logic
+  def env_paths
+    if @config.env_paths.respond_to? :each
+      self["PATH"] |= @config.env_paths
+    end
+
+    features_env_paths
+
+    self["PATH"]
+  end
+
+  # Adds given paths to PATH environment variable defined in the sandbox.
+  #
+  # @param elements [String, Array] Path(s) to be added added to PATH environment variable
+  def add_to_path elements
+    if elements.respond_to? :each
+      self["PATH"] += elements
+    else
+      # Expecting elements to be single path element as a string.
+      self["PATH"] << elements
+    end
+  end
+
+  # Feature specific environment path handling.
+  private def features_env_paths
+    ruby_env_paths
+  end
+
+  # Ruby feature specific environment path handling.
+  private def ruby_env_paths
+    return unless @config.features.ruby.enabled?
+    return unless @config.features.ruby.gem_env_paths?
+
+    unless command_available? "gem"
+      warn "gem is not installed in the system, so can’t add its bindirs to PATH."
+      return
+    end
+
+    gempath = execvalue %w{ gem environment gempath }
+    gempath.split(":").each do |path|
+      self["PATH"] << "#{path}/bin"
+    end
+  end
 end

data/lib/bwrap/args/features.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "bwrap/output"
+require_relative "args"
+require_relative "library"
+
+# Feature parameter construction.
+#
+# @see Config::Features
+class Bwrap::Args::Features < Hash
+  include Bwrap::Output
+
+  # Implementation for Bash feature set.
+  #
+  # @api private
+  class BashBinds
+    # Mounts stuff like /bin/bash.
+    def bash_mounts
+      mounts = []
+
+      if File.file? "/bin/bash"
+        mounts << "--ro-bind" << "/bin/bash" << "/bin/bash"
+      end
+      if File.file? "/usr/bin/bash"
+        mounts << "--ro-bind" << "/usr/bin/bash" << "/usr/bin/bash"
+      end
+
+      mounts
+    end
+  end
+
+  # Implementation for nscd feature set.
+  #
+  # @api private
+  class NscdBinds
+    # Custom binds needed by the feature.
+    def custom_binds
+      mounts = []
+
+      # TODO: Probably some path checking is needed here. Or somewhere.
+      # TODO: Since on many systems /var/run is symlinked to /run, that probably should be handled.
+      mounts << "--ro-bind" << "/var/run/nscd" << "/var/run/nscd"
+
+      mounts
+    end
+  end
+
+  # Implementation for Ruby feature set.
+  #
+  # @api private
+  class RubyBinds
+    # Returns mounts needed by Ruby feature set.
+    attr_reader :mounts
+
+    # Bind system paths so scripts works inside sandbox.
+    def sitedir_mounts
+      mounts = []
+      mounts << "--ro-bind" << RbConfig::CONFIG["sitedir"] << RbConfig::CONFIG["sitedir"]
+      mounts << "--ro-bind" << RbConfig::CONFIG["rubyhdrdir"] << RbConfig::CONFIG["rubyhdrdir"]
+      mounts << "--ro-bind" << RbConfig::CONFIG["rubylibdir"] << RbConfig::CONFIG["rubylibdir"]
+      mounts << "--ro-bind" << RbConfig::CONFIG["vendordir"] << RbConfig::CONFIG["vendordir"]
+
+      mounts
+    end
+
+    # Create binds for required system libraries.
+    #
+    # These are in path like /usr/lib64/ruby/2.5.0/x86_64-linux-gnu/,
+    # and as they are mostly shared libraries, they may have some extra
+    # dependencies that also need to be bound inside the sandbox.
+    def stdlib_mounts stdlib
+      library_mounts = []
+      library = Bwrap::Args::Library.new
+      stdlib.each do |lib|
+        path = "#{RbConfig::CONFIG["rubyarchdir"]}/#{lib}.so"
+
+        library.needed_libraries(path).each do |requisite_library|
+          library_mounts << "--ro-bind" << requisite_library << requisite_library
+        end
+      end
+
+      library_mounts
+    end
+  end
+
+  # `Array` of parameters passed to bwrap.
+  attr_writer :args
+
+  # Instance of {Config}.
+  attr_writer :config
+
+  # Resolves binds required by different features.
+  #
+  # Currently implemented feature sets:
+  # - ruby
+  def feature_binds
+    bash_binds
+    nscd_binds
+    ruby_binds
+  end
+
+  private def bash_binds
+    return unless @config.features.bash.enabled?
+
+    binds = BashBinds.new
+
+    @args.append binds.bash_mounts
+  end
+
+  private def nscd_binds
+    return unless @config.features.nscd.enabled?
+
+    binds = NscdBinds.new
+
+    @args.append binds.custom_binds
+  end
+
+  # @note This does not allow development headers needed for compilation for now.
+  #   I’ll look at it after I have an use for it.
+  private def ruby_binds
+    return unless @config.features.ruby.enabled?
+
+    binds = RubyBinds.new
+
+    @args.append binds.sitedir_mounts
+    @args.append binds.stdlib_mounts(@config.features.ruby.stdlib)
+  end
+end

data/lib/bwrap/args/library.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "bwrap/execution"
+require "bwrap/output"
+require_relative "args"
+
+# Class to clean up namespace for implementation specific reasons.
+#
+# @api private
+class Bwrap::Args::Library
+  include Bwrap::Execution
+  include Bwrap::Output
+
+  # 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
+  def libraries_needed_by executable
+    # %i == interpreter, the library used to load the executable by kernel.
+    # %F == Path to given file.
+    output_format = "%i::SEPARATOR::%F"
+    scanelf_command = %W{ scanelf --nobanner --quiet --format #{output_format} }
+    scanelf_command << executable
+
+    data = execvalue scanelf_command
+    data = data.strip
+    interpreter, _executable_path = data.split "::SEPARATOR::"
+    interpreter = Pathname.new interpreter
+
+    if interpreter.basename.to_s[0..6] == "ld-musl"
+      musl_needed_libraries executable
+    else
+      # For glibc, scanelf can return full paths for us most of time.
+      needed_libraries executable
+    end
+  end
+
+  # @param binary_paths [String, Array] one or more paths to be resolved
+  #
+  # @todo Maybe caching should be done here too?
+  def musl_needed_libraries binary_paths
+    trace "Finding musl libraries #{binary_paths} requires"
+    @needed_libraries = []
+
+    if binary_paths.is_a? String
+      binary_paths = [ binary_paths ]
+    end
+
+    binary_paths.each do |binary_path|
+      output = execvalue %W{ ldd #{binary_path} }
+      lines = output.split "\n"
+      _interpreter_line = lines.shift
+
+      lines.each do |line|
+        parse_ldd_line line
+      end
+    end
+
+    @needed_libraries
+  end
+
+  # Used by {Bwrap::Args::Bind#libs_command_requires}.
+  #
+  # @param binary_paths [String, Array] one or more paths to be resolved
+  def needed_libraries binary_paths
+    trace "Finding libraries #{binary_paths} requires"
+    @needed_libraries = []
+
+    # %i == interpreter, the library used to load the executable by kernel.
+    output_format = "%F::SEPARATOR::%n"
+    scanelf_command = %W{ scanelf --nobanner --quiet --format #{output_format} --ldcache --needed }
+
+    if binary_paths.is_a? String
+      binary_paths = [ binary_paths ]
+    end
+
+    # Check if the exe is already resolved.
+    binary_paths.delete_if do |binary_path|
+      @@needed_libraries_cache.include? binary_path
+    end
+
+    return [] if binary_paths.empty?
+
+    data = execvalue(scanelf_command + binary_paths)
+    trace "scanelf found following libraries: #{data}"
+
+    lines = data.split "\n"
+    lines.each do |line|
+      parse_scanelf_line line
+    end
+
+    @needed_libraries
+  end
+
+  # Used by {#needed_libraries}.
+  private def parse_scanelf_line line
+    binary_path, libraries_line = line.split "::SEPARATOR::"
+    libraries = libraries_line.split ","
+
+    (@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_cache |= libraries
+  end
+
+  # Used by {#musl_needed_libraries}.
+  private def parse_ldd_line line
+    line = line.strip
+    _library_name, library_data = line.split " => "
+
+    matches = library_data.match(/(.*) \(0x[0-9a-f]+\)/)
+    library_path = matches[1]
+
+    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
+  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

@@ -4,21 +4,30 @@ require_relative "args"
 
 # Bind arguments for bwrap.
 module Bwrap::Args::Mount
+  # Arguments for readwrite-binding {Config#root} as /.
+  private def root_mount
+    return unless @config.root
+
+    debug "Binding #{@config.root} as /"
+    @args.append %W{ --bind #{@config.root} / }
+    @args.append %w{ --chdir / }
+  end
+
   # Arguments for mounting devtmpfs to /dev.
   private def dev_mount
     debug "Mounting new devtmpfs to /dev"
-    %w{ --dev /dev }
+    @args.append %w{ --dev /dev }
   end
 
   # Arguments for mounting procfs to /proc.
   private def proc_mount
     debug "Mounting new procfs to /proc"
-    %w{ --proc /proc }
+    @args.append %w{ --proc /proc }
   end
 
   # Arguments for mounting tmpfs to /tmp.
   private def tmp_as_tmpfs
     debug "Mounting tmpfs to /tmp"
-    %w{ --tmpfs /tmp }
+    @args.append %w{ --tmpfs /tmp }
   end
 end

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