Class: Bwrap::Bwrap

Inherits:
Object
  • Object
show all
Includes:
Execution
Defined in:
lib/bwrap/bwrap.rb

Overview

Executes given command under bwrap using given configuration.

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.

See Also:

Instance Method Summary collapse

Methods included from Execution

do_execute, last_status, popen2e

Methods included from Output

debug?, debug_output, error_output, handle_output_options, info_output, quiet?, trace?, trace_output, verb_output, verbose?, warn_output

Constructor Details

#initialize(config = nil) ⇒ Bwrap

Note:

When config is not given, alternative root directory can be specified with #run_inside_root.

Returns a new instance of Bwrap.

Parameters:

  • config (Bwrap::Config) (defaults to: nil) —

    Configuration used to tailor bwrap



30
31
32
33
34
35
36
37
 
# File 'lib/bwrap/bwrap.rb', line 30

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

Instance Method Details

#build_bwrap_arguments(command, config: nil) ⇒ Object

TODO:

Proper documentation.

Parameters:

  • command (String, Array) —

    Command to be executed inside bwrap along with necessary arguments

  • config (Bwrap::Config|nil) (defaults to: nil) —

    Configuration to tailor bwrap sandbox. Defaults to config given to #initialize



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/bwrap/bwrap.rb', line 59

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

#parse_command_line_arguments ⇒ Object

Note:

This method automatically sets output levels according parsed options. It is also possible to set the levels manually using Output.handle_output_options, for example with flags parsed with optparse’s `OptionParser`, found in Ruby’s standard library.

Parses command line arguments given to caller script.



48
49
50
51
52
 
# File 'lib/bwrap/bwrap.rb', line 48

def parse_command_line_arguments
  options = parse_options

  Bwrap::Output.handle_output_options options
end

#run(command, **kwargs) ⇒ Object

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 Execution#execute.

Executed command is constructed using configuration passed to constructor. After execution has completed, bwrap will also shut down.

Parameters:

  • command (String, Array) —

    Command to be executed inside bwrap along with necessary arguments

  • kwargs (Hash) —

    a customizable set of options

Options Hash (**kwargs):

  • log_callback (Integer) — default: 1 —

    Semi-internal variable used to tailor caller in debug messages

See Also:



94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/bwrap/bwrap.rb', line 94

def run command, **kwargs
  exec_command = build_bwrap_arguments command

  # add 1 to log_callback so executing is shown to where this method is called at.
  kwargs[:log_callback] ||= 1
  kwargs[:log_callback] += 1

  result = execute exec_command, **kwargs

  @construct.cleanup

  result
end

#run_inside_root(command, **kwargs) ⇒ Object

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.

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`.

`kwargs` are passed to Execution#execute.

Parameters:

  • command (String, Array) —

    Command to be executed inside bwrap along with necessary arguments

See Also:



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/bwrap/bwrap.rb', line 121

def run_inside_root command, **kwargs
  if @config
    config = @config.dup
    config.command_inside_root = true
  else
    config = nil
  end

  # 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 = build_bwrap_arguments command, config: config

  execute exec_command, **kwargs

  @construct.cleanup
end