shikashi 0.1.0

data/AUTHORS

@@ -0,0 +1,3 @@
+shikashi de tario <rseminara@hotmail.com>
+
+

data/CHANGELOG

@@ -0,0 +1 @@
+0.2.0	Optimized Cymbol::resolv by using a singleton of Cymbol::Resolv

data/README

@@ -0,0 +1,199 @@
+= 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
+the sandbox can be replaced transparently (i.e: replace method IO#write in the sandbox context to capture the
+standard output of the script)
+
+The implementation of shikashi is pure ruby and it is based on rallhook, an amending of the ruby interpreter
+(see http://tario.github.com/rallhook/doc)
+
+== Installation
+
+=== Prerequisites
+
+* rallhook >= 0.7.0 (found at http://github.com/tario/rallhook)
+
+=== Gem installation
+
+* Download the last version of the gem from http://github.com/tario/shikashi/downloads
+* Install the gem with the following;
+
+gem install shikashi-X.X.X.gem.
+
+== 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
+
+	# allow definition of classes
+	priv.allow_class_definitions
+
+	#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
+	')
+
+	# run privileged code in the sandbox, if not, the methods defined in the sandbox are invisible from outside
+	s.run do
+		x = X.new
+		x.foo
+		begin
+		x.bar
+		rescue SecurityError => e
+			print "x.bar failed due security errors: #{e}\n"
+		end
+	end
+
+
+=== Redirection feature example
+
+Simple redirection of method, the method foo is replaced by TestWrapper::call
+
+	require "rubygems"
+	require "shikashi"
+
+	class TestWrapper < Shikashi::Sandbox::MethodWrapper
+	  def call(*args)
+	    print "called foo from source: #{source}, arguments: #{args.inspect} \n"
+	    original_call(*args)
+	  end
+	end
+
+	class X
+	  def foo
+	    print "original foo\n"
+	  end
+	end
+
+	s = Shikashi::Sandbox.new
+	perm = Shikashi::Privileges.new
+
+	perm.object(X).allow :new
+	perm.instances_of(X).allow :foo
+
+	# redirect calls to foo to TestWrapper
+	perm.instances_of(X).redirect :foo, TestWrapper
+
+	s.run(perm,"X.new.foo")
+

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+spec = Gem::Specification.new do |s|
+  s.name = 'shikashi'
+  s.version = '0.1.0'
+  s.author = 'Dario Seminara'
+  s.email = 'robertodarioseminara@gmail.com'
+  s.platform = Gem::Platform::RUBY
+  s.summary = 'shikashi is a ruby sandbox that permits the execution of "unprivileged" scripts by defining the permitted methods and constants the scripts can invoke (I.E., the script cannot use the File class or a RoR Model Class unless that permission is specified) "well done version" of ruby-arena-sanbox based on rallhook'
+  s.homepage = "http://github.com/tario/shikashi"
+  s.add_dependency "rallhook", ">= 0.7.0"  
+  s.has_rdoc = true
+  s.extra_rdoc_files = [ 'README' ]
+#  s.rdoc_options << '--main' << 'README'
+  s.files = Dir.glob("{examples,lib,test}/**/*") +
+    [ 'AUTHORS', 'CHANGELOG', 'README', 'Rakefile', 'TODO' ]
+end
+
+desc 'Run tests'
+task :default => [ :test ]
+
+Rake::TestTask.new('test') do |t|
+  t.libs << 'test'
+  t.pattern = '{test}/test_*.rb'
+  t.verbose = true
+end
+
+desc 'Generate RDoc'
+Rake::RDocTask.new :rdoc do |rd|
+  rd.rdoc_dir = 'doc'
+  rd.rdoc_files.add 'lib', 'README'
+  rd.main = 'README'
+end
+
+desc 'Build Gem'
+Rake::GemPackageTask.new spec do |pkg|
+  pkg.need_tar = true
+end
+
+desc 'Clean up'
+task :clean => [ :clobber_rdoc, :clobber_package ]
+
+desc 'Clean up'
+task :clobber => [ :clean ]

data/examples/basic/example.rb

@@ -0,0 +1,28 @@
+# call method defined in sandbox from outside
+
+require "rubygems"
+require "shikashi"
+
+include Shikashi
+
+s = Sandbox.new
+priv = Privileges.new
+
+# allow execution of foo in this object
+priv.object(self).allow :foo
+
+# allow execution of print in this object
+priv.object(self).allow :print
+
+#inside the sandbox, only can use method foo on main and method times on instances of Fixnum
+s.run(priv, "
+def inside_foo(a)
+	print 'inside_foo'
+	if (a)
+	system('ls -l') # denied
+	end
+end
+")
+
+inside_foo(false)
+inside_foo(true)

data/examples/basic/example1.rb

@@ -0,0 +1,12 @@
+# "hello world" from within the sandbox
+
+require "rubygems"
+require "shikashi"
+
+include Shikashi
+
+s = Sandbox.new
+priv = Privileges.new
+priv.allow_method :print
+
+s.run(priv, 'print "hello world\n"')

data/examples/basic/example2.rb

@@ -0,0 +1,24 @@
+# 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")
+

data/examples/basic/example3.rb

@@ -0,0 +1,46 @@
+# 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
+')

data/examples/basic/example4.rb

@@ -0,0 +1,41 @@
+# call method defined in sandbox from outside
+
+require "rubygems"
+require "shikashi"
+
+include Shikashi
+
+s = Sandbox.new
+priv = Privileges.new
+
+# allow execution of print
+priv.allow_method :print
+
+# allow execution of method_added
+priv.allow_method :method_added
+
+# allow execution of singleton_method_added
+priv.allow_method :singleton_method_added
+
+#inside the sandbox, only can use method foo on main and method times on instances of Fixnum
+s.run(priv, '
+module A
+def self.inside_foo(a)
+	print "inside_foo\n"
+	if (a)
+	system("ls -l") # denied
+	end
+end
+end
+')
+
+# run privileged code in the sandbox, if not, the methods defined in the sandbox are invisible from outside
+s.run do
+	A.inside_foo(false)
+	begin
+	A.inside_foo(true)
+	rescue SecurityError => e
+		print "A.inside_foo(true) failed due security errors: #{e}\n"
+	end
+end
+

data/examples/basic/example5.rb

@@ -0,0 +1,40 @@
+# 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
+
+# allow definition of classes
+priv.allow_class_definitions
+
+#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
+')
+
+# run privileged code in the sandbox, if not, the methods defined in the sandbox are invisible from outside
+s.run do
+	x = X.new
+	x.foo
+	begin
+	x.bar
+	rescue SecurityError => e
+		print "x.bar failed due security errors: #{e}\n"
+	end
+end
+