bwrap 1.0.0.pre.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e4193a0724aceb154c2e9be0809366ed2998837beeeb577dc101a58e20dca97d
+  data.tar.gz: a927a6a6b8cb415f3983440ca0437b852582227f5b163f34143ffb375dc96a40
+SHA512:
+  metadata.gz: f2f49d20cf15a331d34439d71ef038645bc2a5520407cdb519ea8f5e9e32db526dd7524ad35939acd8098a328d6a3c1c2542d5fde44d0adcfd8ae26f2313d5fb
+  data.tar.gz: ee295629e684ef280652e38a94e7731b6e3227a2bac1150a79da268f3d2972eaac889ac1928103edf9d022c84430898ebc53d008a6f181d412d3f1ede441d0a9

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changes
+
+## 1.0.0-alpha1 (10.11.2021)
+
+## 0.1.0 (unreleased)
+
+* First, currently unfinished and unreleased version. Work in Progress.

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright © 2021 Samu Voutilainen
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD
+TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
+OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,33 @@
+# Bwrap
+
+Framework to create commands for bwrap.
+
+For now this is tailored to my needs, so this may or may not be of any use.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "bwrap"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bwrap
+
+## Usage
+
+For now this is under ongoing development, though semantic versioning will apply.
+
+There is few different modules, especially execution stuff probably should be moved to its own gem.
+
+Please see [API documentation](https://www.rubydoc.info/gems/bwrap) for usage instructions.
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://git.sr.ht/~smar/ruby-bwrap.

data/lib/bwrap/args/args.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bwrap/version"
+
+# bwrap argument related operations.
+module Bwrap::Args
+  # Nya.
+end

data/lib/bwrap/args/bind.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "args"
+
+# Bind arguments for bwrap.
+module Bwrap::Args::Bind
+  # Arguments to bind /dev/dri from host to sandbox.
+  private def bind_dev_dri
+    %w{ --dev-bind /dev/dri /dev/dri }
+  end
+
+  # Arguments to bind /sys/dev/char from host to sandbox.
+  private def bind_sys_dev_char
+    %w{ --ro-bind /sys/dev/char /sys/dev/char }
+  end
+
+  # Arguments to bind /sys/devices/pci0000:00 from host to sandbox.
+  private def bind_pci_devices
+    %w{ --ro-bind /sys/devices/pci0000:00 /sys/devices/pci0000:00 }
+  end
+
+  # Arguments to bind home directory from sandbox directory (`#{@config.sandbox_directory}/home`)
+  # as `/home/#{@config.user}`.
+  #
+  # @note Requires @config.user to be set.
+  private def bind_home_directory
+    unless @config.user
+      raise "Tried to bind user directory without user being set."
+    end
+
+    home_directory = "#{@config.sandbox_directory}/home"
+
+    unless Dir.exist? home_directory
+      raise "Home directory #{home_directory} does not exist. You need to create it yourself."
+    end
+
+    @environment["HOME"] = "/home/#{@config.user}"
+
+    %W{ --bind #{home_directory} /home/#{@config.user} }
+  end
+
+  # Arguments to read-only bind whole system inside sandbox.
+  private def full_system_mounts
+    bindir_mounts = []
+    binaries_from = @config.binaries_from
+    binaries_from.each do |path|
+      bindir_mounts << "--ro-bind" << path << path
+    end
+    @environment["PATH"] = binaries_from.join(":")
+
+    libdir_mounts = %w{
+      --ro-bind /lib /lib
+      --ro-bind /lib64 /lib64
+      --ro-bind /usr/lib /usr/lib
+      --ro-bind /usr/lib64 /usr/lib64
+    }
+
+    system_mounts = bindir_mounts + libdir_mounts
+    if debug?
+      debug "Using following system mounts:\n" \
+            "#{system_mounts}\n" \
+            "(Odd is key, even is value)"
+    end
+    system_mounts
+  end
+
+  # These are something user can specify to do custom --ro-bind binds.
+  private def custom_read_only_binds
+    return [] unless @config.ro_binds
+
+    binds = []
+    @config.ro_binds.each do |source_path, destination_path|
+      binds << "--ro-bind" << source_path.to_s << destination_path.to_s
+    end
+
+    binds
+  end
+end

data/lib/bwrap/args/construct.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+require "bwrap/output"
+require_relative "bind"
+require_relative "environment"
+require_relative "machine_id"
+require_relative "mount"
+
+# Constructs arguments for bwrap execution.
+class Bwrap::Args::Construct
+  include Bwrap::Output
+  include Bwrap::Args::Bind
+  include Bwrap::Args::Mount
+
+  attr_writer :config
+
+  # Constructs arguments for bwrap execution.
+  def construct_bwrap_args
+    @environment = Bwrap::Args::Environment.new
+    @environment.config = @config
+    @machine_id = Bwrap::Args::MachineId.new
+    @machine_id.config = @config
+
+    [
+      xauthority_args,
+      @machine_id.machine_id,
+      resolv_conf,
+      full_system_mounts,
+      custom_read_only_binds,
+      create_user_dir,
+      read_only_pulseaudio,
+      dev_mount,
+      bind_dev_dri,
+      bind_sys_dev_char,
+      bind_pci_devices,
+      proc_mount,
+      tmp_as_tmpfs,
+      bind_home_directory,
+      "--unshare-all",
+      share_net,
+      hostname,
+      @environment.environment_variables,
+      "--die-with-parent",
+      "--new-session"
+    ]
+  end
+
+  # Performs cleanup operations after execution.
+  def cleanup
+    @machine_id&.cleanup
+  end
+
+  # Arguments for generating .Xauthority file.
+  private def xauthority_args
+    xauth_args = %W{ --ro-bind #{Dir.home}/.Xauthority #{Dir.home}/.Xauthority }
+    debug "Binding following .Xauthority file: #{Dir.home}/.Xauthority"
+    xauth_args
+  end
+
+  # Arguments to read-only bind /etc/resolv.conf.
+  private def resolv_conf
+    #source_resolv_conf = "/etc/resolv.conf"
+    source_resolv_conf = "/run/netconfig/resolv.conf"
+    debug "Binding #{source_resolv_conf} as /etc/resolv.conf"
+    %w{ --ro-bind /run/netconfig/resolv.conf /etc/resolv.conf }
+  end
+
+  # Arguments to create `/run/user/#{uid}`.
+  private def create_user_dir
+    trace "Creating directory /run/user/#{uid}"
+    %W{ --dir /run/user/#{uid} }
+  end
+
+  # Arguments to bind necessary pulseaudio data for audio support.
+  private def read_only_pulseaudio
+    debug "Binding pulseaudio"
+    %W{ --ro-bind /run/user/#{uid}/pulse /run/user/#{uid}/pulse }
+  end
+
+  # Arguments to allow network connection inside sandbox.
+  private def share_net
+    verb "Sharing network"
+    %w{ --share-net }
+  end
+
+  # Arguments to set hostname to whatever is configured.
+  private def hostname
+    return unless @config.hostname
+
+    debug "Setting hostname to #{@config.hostname}"
+    %W{ --hostname #{@config.hostname} }
+  end
+
+  # Returns current user id.
+  private def uid
+    Process.uid
+  end
+end

data/lib/bwrap/args/environment.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "bwrap/output"
+require_relative "args"
+
+# Environment variable calculation for bwrap.
+class Bwrap::Args::Environment < Hash
+  include Bwrap::Output
+
+  # Instance of {Config}.
+  attr_writer :config
+
+  # Returns used environment variables.
+  def environment_variables
+    if debug?
+      debug "Passing following environment variables to bwrap:\n" \
+            "#{self}"
+    end
+
+    map do |key, value|
+      [ "--setenv", key, value ]
+    end
+  end
+end

data/lib/bwrap/args/machine_id.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require "bwrap/output"
+require_relative "args"
+
+# Calculate machine id data.
+class Bwrap::Args::MachineId
+  include Bwrap::Output
+
+  # Instance of {Config}.
+  attr_writer :config
+
+  # machine_id == :random
+  #   Generates random machine id for each launch and sets it as /etc/machine_id.
+  # machine_id ==  :dummy
+  #   Uses 10000000000000000000000000000000 as dummy machine id and sets it as /etc/machine_id.
+  # machine_id == true
+  #   A file from `#{sandbox_directory}/machine_id` is bound as /etc/machine_id.
+  # machine_id.is_a? String
+  #   Given file as bound as /etc/machine_id.
+  def machine_id
+    # 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
+
+    machine_id = @config.machine_id
+
+    if machine_id == :random
+      random_machine_id
+    elsif machine_id == :dummy
+      dummy_machine_id
+    elsif machine_id == true
+      machine_id_inside_sandbox_dir @config.sandbox_directory
+    elsif machine_id.is_a? String
+      string_machine_id machine_id
+    end
+  end
+
+  # Removes opened temporary machine id file.
+  #
+  # Can be called safely even if no file is opened.
+  def cleanup
+    @machine_id_file&.unlink
+  end
+
+  # Generated random machine id.
+  private def random_machine_id
+    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.flush
+
+    %W{ --ro-bind-data #{machine_id_file.fileno} /etc/machine-id }
+  end
+
+  # Uses `10000000000000000000000000000000` as machine id.
+  private def dummy_machine_id
+    debug "Using dummy machine id as /etc/machine-id"
+
+    @machine_id_file = Tempfile.new "bwrap-dummy_machine_id-", @config.tmpdir
+    @machine_id_file.write "10000000000000000000000000000000"
+    @machine_id_file.flush
+
+    %W{ --ro-bind-data #{@machine_id_file.fileno} /etc/machine-id }
+  end
+
+  # Uses given file as machine id.
+  private def string_machine_id machine_id_file
+    unless File.exist? machine_id_file
+      raise "Configured machine_id file #{machine_id_file} does not exist."
+    end
+
+    debug "Binding #{machine_id_file} as /etc/machine-id"
+    %W{ --ro-bind #{machine_id_file} /etc/machine-id }
+  end
+
+  # Uses file inside sandbox directory as machine id.
+  private def machine_id_inside_sandbox_dir sandbox_directory
+    machine_id_file = "#{sandbox_directory}/machine-id"
+
+    unless File.exist? machine_id_file
+      raise "#{machine_id_file} does not exist.\n" \
+            "Hint: you can generate dummy machine-id file with:\n" \
+            "  echo 10000000000000000000000000000000 > #{machine_id_file}"
+    end
+
+    debug "Binding #{machine_id_file} as /etc/machine-id"
+    %W{ --ro-bind #{machine_id_file} /etc/machine-id }
+  end
+end
+

data/lib/bwrap/args/mount.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "args"
+
+# Bind arguments for bwrap.
+module Bwrap::Args::Mount
+  # Arguments for mounting devtmpfs to /dev.
+  private def dev_mount
+    debug "Mounting new devtmpfs to /dev"
+    %w{ --dev /dev }
+  end
+
+  # Arguments for mounting procfs to /proc.
+  private def proc_mount
+    debug "Mounting new procfs to /proc"
+    %w{ --proc /proc }
+  end
+
+  # Arguments for mounting tmpfs to /tmp.
+  private def tmp_as_tmpfs
+    debug "Mounting tmpfs to /tmp"
+    %w{ --tmpfs /tmp }
+  end
+end

data/lib/bwrap/config.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "bwrap/output"
+require "bwrap/version"
+
+# Represents configuration set by user for bwrap execution.
+#
+# Implementation NOTE: logger methods (debug, warn and so on) can’t be used here as logger
+# isn’t initialized before this class.
+class Bwrap::Config
+  attr_accessor :hostname
+
+  # What should be used as /etc/machine_id file.
+  #
+  # If not specified, no /etc/machine_id handling is done.
+  #
+  # machine_id == :random
+  #   Generates random machine id for each launch and sets it as /etc/machine_id.
+  # machine_id ==  :dummy
+  #   Uses 10000000000000000000000000000000 as dummy machine id and sets it as /etc/machine_id.
+  # machine_id == true
+  #   A file from #{sandbox_directory}/machine_id is bound as /etc/machine_id.
+  # machine_id.is_a? String
+  #   Given file as bound as /etc/machine_id.
+  attr_accessor :machine_id
+
+  attr_accessor :user
+
+  # Array of directories to be bind mounted and used to construct PATH environment variable.
+  attr_reader :binaries_from
+
+  attr_reader :sandbox_directory
+
+  # `Hash`[`Pathname`] => `Pathname` containing custom read-only binds.
+  attr_reader :ro_binds
+
+  # Path to temporary directory.
+  #
+  # Defaults to Dir.tmpdir.
+  attr_reader :tmpdir
+
+  def initialize
+    @binaries_from = []
+    @tmpdir = Dir.tmpdir
+  end
+
+  def binaries_from= array
+    @binaries_from = []
+    array.each do |path|
+      unless Dir.exist? path
+        raise "Path “#{path}” given to binaries_from does not exist."
+      end
+
+      @binaries_from << path
+    end
+  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."
+    end
+
+    @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.
+  def ro_binds= binds
+    @ro_binds = {}
+    binds.each do |source_path, destination_path|
+      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."
+      end
+
+      destination_path = Pathname.new destination_path
+
+      @ro_binds[source_path] = destination_path
+    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
+  def tmpdir= dir
+    raise "Directory to be set as a temporary directory, “#{dir}”, does not exist." unless Dir.exist? dir
+
+    @tmpdir = dir
+  end
+end

data/lib/bwrap/execution/execute.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: false
+
+# force_encoding modifies string, so can’t freeze strings.
+
+require "bwrap/output"
+require_relative "execution"
+
+# Methods that performs actual execution logic.
+#
+# @api internal
+class Bwrap::Execution::Execute
+  include Bwrap::Output
+
+  class << self
+    # Can be used to access pipe where `Kernel#spawn` should write its data.
+    attr_reader :w
+
+    # Dry run flag from parent Execution module.
+    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:
+    replace_nils command
+    return command if rootcmd.nil?
+
+    prepend_rootcmd command, rootcmd: rootcmd
+  end
+
+  # Opens pipes for command output handling.
+  def self.open_pipes direct_output
+    @r, @w = IO.pipe
+    return unless direct_output
+
+    @pipe_w = @w
+    @w = $stdout
+  end
+
+  # Converts output to be UTF-8.
+  def self.process_output output:
+    # read_nonblock() uses read(), which always reads as ASCII-8BIT:
+    #   In the case of an integer length, the resulting string is always in ASCII-8BIT encoding.
+    output.force_encoding("UTF-8").strip
+  end
+
+  # Checks whether execution failed and acts accordingly.
+  def self.handle_execution_fail fail:, error:, output:
+    return unless fail and !$CHILD_STATUS.success?
+
+    if error == :show and !output.empty?
+      Bwrap::Output.warn_output "Command failed with output:\n“#{output}”"
+    end
+    raise Bwrap::Execution::ExecutionFailed, "Command execution failed.", caller
+  end
+
+  # @note It makes sense for caller to just return if wait has been set and not check output.
+  #
+  # @return output from command or nil if execution should stop here.
+  def self.finish_execution log:, wait:, direct_output:
+    @w = @pipe_w if direct_output
+    @w.close
+    unless wait
+      @r.close
+      return # With wait == false, execute() stops here.
+    end
+    output = buffer_exec_output @r, log
+    @r.close
+
+    output
+  end
+
+  # Removes data in class instance variables after execution has completed either successfully or with an error.
+  def self.clean_variables
+    @w = nil
+    @r = nil
+    @pipe_w = nil
+  end
+
+  # 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."
+  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
+    return unless command.respond_to? :map!
+
+    command.map! do |argument|
+      argument.nil? && "" || argument
+    end
+  end
+
+  # Used by Execution#execute, not useful for anything else.
+  private_class_method def self.buffer_exec_output read, log
+    buffer = String.new capacity: 1024
+    output = ""
+    until read.eof?
+      read.read_nonblock 1024, buffer
+      if log
+        print buffer if Bwrap::Output.verbose?
+        Bwrap::Output::Log.write_to_log buffer
+      end
+      output << buffer
+    end
+
+    output
+  end
+end

data/lib/bwrap/execution/execution.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bwrap/version"
+
+# Generic execution functionality.
+module Bwrap::Execution
+  # Nyan.
+end