shikashi

= Shikashi - A flexible sandbox for ruby

Shikashi is an sandbox for ruby that handles all ruby method calls executed in the interpreter to allow or deny these calls depending on the receiver object, the method name, the source file from where the call was originated and the source file where the called method is implemented.

The permissions for each sandboxed run is fully configurable and the implementation of the methods called from within the sandbox can be replaced transparently

The implementation of shikashi is written in pure ruby and now implemented based in evalhook, (see http://tario.github.com/evalhook)

== Installation

=== Gem installation

Run in the terminal:

sudo gem install shikashi

OR

• Download the last version of the gem from http://github.com/tario/shikashi/downloads
• Install the gem with the following;

sudo gem install shikashi-X.X.X.gem.

=== Troubleshooting

ERROR: While executing gem ... (Gem::DependencyError) Unable to resolve dependencies: ruby2ruby requires sexp_processor (> 3.0); ruby_parser requires sexp_processor (> 3.0)

The version of ruby2ruby and ruby_parser required depends on sexp_processor 3.X but for some reason this version of the gem is not automatically installed by gem, you can workaround this issue by installing it before using:

gem install sexp_processor --version '~> 3.2'

== Documentation

Full API documentation can be found on: http://tario.github.com/shikashi/doc/

== Usage

This examples and more can be found in examples directory

=== Basic Example

Hello world from a sandbox

require "rubygems"
require "shikashi"

include Shikashi

s = Sandbox.new
priv = Privileges.new
priv.allow_method :print

s.run(priv, 'print "hello world\n"')

=== Basic Example 2

Call external method from inside the sandbox

require "rubygems"
require "shikashi"

include Shikashi

def foo
	# privileged code, can do any operation
	print "foo\n"
end

s = Sandbox.new
priv = Privileges.new

# allow execution of foo in this object
priv.object(self).allow :foo

# allow execution of method :times on instances of Fixnum
priv.instances_of(Fixnum).allow :times

#inside the sandbox, only can use method foo on main and method times on instances of Fixnum
s.run(priv, "2.times do foo end")

=== Basic Example 3

Define a class outside the sandbox and use it in the sandbox

require "rubygems"
require "shikashi"

include Shikashi

s = Sandbox.new
priv = Privileges.new

# allow execution of print
priv.allow_method :print

class X
	def foo
		print "X#foo\n"
	end

	def bar
		system("echo hello world") # accepted, called from privileged context
	end

	def privileged_operation( out )
		# write to file specified in out
		system("echo privileged operation > " + out)
	end
end
# allow method new of class X
priv.object(X).allow :new

# allow instance methods of X. Note that the method privileged_operations is not allowed
priv.instances_of(X).allow :foo, :bar

priv.allow_method :=== # for exception handling
#inside the sandbox, only can use method foo on main and method times on instances of Fixnum
s.run(priv, '
x = X.new
x.foo
x.bar

begin
x.privileged_operation # FAIL
rescue SecurityError
print "privileged_operation failed due security error\n"
end
')

=== Basic Example 4

define a class from inside the sandbox and use it from outside

require "rubygems"
require "shikashi"

include Shikashi

s = Sandbox.new
priv = Privileges.new

# allow execution of print
priv.allow_method :print

#inside the sandbox, only can use method foo on main and method times on instances of Fixnum
s.run(priv, '
class X
	def foo
		print "X#foo\n"
	end

	def bar
		system("ls -l")
	end
end
')

x = s.base_namespace::X.new
x.foo
begin
	x.bar
rescue SecurityError => e
	print "x.bar failed due security errors: #{e}\n"
end

=== Base namespace

require "rubygems"
require "shikashi"

include Shikashi

class X
	def foo
		print "X#foo\n"
	end
end

s = Sandbox.new

s.run( "
  class X
	def foo
		print \"foo defined inside the sandbox\\n\"
	end
  end
  ", Privileges.allow_method(:print))
  

x = X.new # X class is not affected by the sandbox (The X Class defined in the sandbox is SandboxModule::X)
x.foo

x = s.base_namespace::X.new
x.foo

s.run("X.new.foo", Privileges.allow_method(:new).allow_method(:foo))

=== Timeout example

require "rubygems"
require "shikashi"

s = Shikashi::Sandbox.new
perm = Shikashi::Privileges.new

perm.allow_method :sleep

s.run(perm,"sleep 3", :timeout => 2) # raise Shikashi::Timeout::Error after 2 seconds

== Copying

Copyright (c) 2010-2011 Dario Seminara, released under the GPL License (see LICENSE)