sandboxed_erb 0.2.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,15 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+gem "partialruby", ">= 0.2.0"
+gem "ruby_parser", ">= 2.0.6"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.6.1"
+  gem "rcov", ">= 0"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Mark Pentland
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,127 @@
+= sandboxed_erb
+
+This is a gem that allows you to run an ERB template in a sandbox so it is safe to expose these templates to your customers to allow them to customise your application (or any other use you can think of).
+
+This has been inspired by http://github.com/tario/shikashi, a ruby sandbox which uses the evalhook gem to intercept and rewrite every ruby call to go through an access check at runtime.
+It was originally designed to run in the shikashi sandbox, but was found to be too slow as every call was being intercepted and analysed at runtime. Because a templating language does not need everything ruby offers, 
+i have limited the allowed synax to a safer subset at compile time to reduce the number of runtime checks required.
+
+
+== How It Works
+
+The code does not run in a 'sandbox' like javascript, it is actually processed into 'safe' code then run using the normal ruby intepreter.
+
+1. The template is first processed by the ERB compiler to produce valid ruby code.
+2. The generated erb code is then processed to check that if conforms to the 'whitelist'of allowed syntax.
+3. Every invokation on an object is converted from some_object.some_method(arg1,argn) to some_object._sbm(:some_method,arg1,argn).
+4. Run using ruby intepreter.
+5. The _sbm method checks at runtime that the method is allowed as per rules defined by 'Module.sandboxed_methods' and 'Module.not_sandboxed_methods'
+
+
+
+== Why Is The Code Safe?
+* I use a 'white list' of allowed syntax, so if I've missed something it will be denied.
+* I dont allow the defining of any classes, methods or modules.
+* You cannot access global variables or constants (or define them)
+* Every call is routed through the _sbm method, so if an non-safe object is somehow called, it wont have the _sbm method, so it will error.
+
+== _sbm (SandBoxed Method)
+Heres an example of the generated code after is has been processed:
+
+Source:
+ email_address = user.login + "@" + user.domain(:local_domain)
+ 
+Processed Code
+ email_address = user._sbm(:login)._sbm(:+,"@")._sbm(:+,user._sbm(:domain, :local_domain))
+ 
+_smb will check that the symbol of the function to call (:login and :domain) has been explicitly allowed for that object using the sandboxed_methods module function (example below).
+If it has been allowed, it is assumed that the method getting called is safe (developers responsibility!) and that it can handle the arguments (which should be safe because you cannot define methods etc in a sandbox). 
+ 
+
+== Optimisations
+* The ERB template generates many _erbout.concat calls, these are not routed through _sbm.
+* to_s is called heaps, it is assumed .to_s is safe to all (without arguments) an any object.
+
+== Benchmark Results
+Taken from profile/vs_liquid.rb
+                          user     system      total        real
+ erb template         0.030000   0.000000   0.030000 (  0.024003)
+ sandboxed template   0.100000   0.000000   0.100000 (  0.100563)
+ liquid template      3.040000   0.020000   3.060000 (  3.116854)
+
+
+== Examples
+
+=== Calling some sandboxed methods
+You can define a class and specify what methods are safe to use from within the sandbox using the sandboxed_methods function.
+ 
+ #Define a class we want accessable from the sandbox
+ class SandboxedClass
+
+   sandboxed_methods :method_i_can_call
+   
+   def method_i_can_call(arg1)
+     "{arg1} passed in"
+   end
+   
+   def private_method(arg1)
+     "You cannot call this from the sandbox"
+   end
+ end
+ 
+ #a basic template that calls 'method_i_can_call' on an instance of SandboxedClass passed in below
+ str_template = "test = <%=sandboxed_class.method_i_can_call('some value')%>"
+
+ template = SandboxedErb::Template.new
+ #compile the template so it can get run multiple times
+ template.compile(str_template)
+ #run the template, passing in an instance of SandboxedClass as a variable called 'sandboxed_class'
+ result = template.run(nil, {:sandboxed_class=>SandboxedClass.new})
+ 
+ #result = "test = some value passed in"
+ 
+ 
+=== Mixins / Helper functions
+To add helper functions to the template, you can define the helper function mixins when the template is instantiated.
+
+ #define helper functions in a module
+ module MixinTest
+   def test_mixin_method 
+     "TEST #{@controller.some_value}"  #@controller is a 'context' object 
+   end
+ end
+ 
+ #define a 'context' object that the helper function will have access to
+ class FauxController
+   def some_value
+     "ABC"  
+   end
+ end
+
+ faux_controller = FauxController.new
+
+ str_template = "mixin = <%= test_mixin_method %>"
+ #declare the template, passing in the MixinTest module so its test_mixin_method will be available as a helper function
+ template = SandboxedErb::Template.new([MixinTest])
+ template.compile(str_template)
+ #pass the FauxController object as a context object called @controller (the keys are converted to member variables)
+ result = template.run({:controller=>faux_controller}, {}) 
+
+ #result =  "mixin = TEST ABC"
+ 
+
+== Contributing to sandboxed_erb
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Mark Pentand. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,54 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "sandboxed_erb"
+  gem.homepage = "http://github.com/markpent/SandboxedERB"
+  gem.license = "MIT"
+  gem.summary = %Q{Run an erb template in a sandbox.}
+  gem.description = %Q{All your customers to extend your web application by exposing erb templates that can be safely run on your server within a sandbox.}
+  gem.email = "mark.pent@gmail.com"
+  gem.authors = ["MarkPent"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+  test.rcov_opts << '--exclude "gems/*"'
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "sandboxed_erb #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/example/controller.rb

@@ -0,0 +1,11 @@
+class Controller
+
+
+  def url_for(options)
+    "/#{options[:controller]}/#{options[:action]}/#{options[:id]}"
+  end
+  
+  def base_url
+    "http://some.url"
+  end
+end

data/example/example.rb

@@ -0,0 +1,87 @@
+require 'rubygems'
+
+gem 'faker'
+gem 'partialruby'
+gem 'ruby_parser'
+
+require 'date'
+require 'faker'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'sandboxed_erb'
+
+
+require 'controller.rb'
+require 'note.rb'
+require 'users.rb'
+
+
+#an example helper to make functions available to the template... 
+module ExampleHelper
+  def link_to(title, href)
+    #silly example, but it shows how the mixins have access to the @controller context as an instance variable
+    if href.index(":").nil?
+      "<a href=\"#{@controller.base_url}/#{href}\">#{title}</a>"
+    else
+      "<a href=\"#{href}\">#{title}</a>"
+    end
+  end
+  
+  def format_date(date, format)
+    if format == :short_date
+      date.strftime("%d %b %Y %H:%M")
+    else
+      "unknown format: #{format}"
+    end
+  end
+end
+
+
+#we will load both templates up and output them...
+
+listing_sbhtml = File.open('listing.sbhtml') { |f| f.read }
+
+notes_sbhtml = File.open('view_notes.sbhtml') { |f| f.read}
+
+
+controller = Controller.new
+users = Users.users(20)
+    
+
+listing_template = SandboxedErb::Template.new([ExampleHelper])
+
+if !listing_template.compile(listing_sbhtml)
+  puts "Listing: #{listing_template.get_error}"
+  exit
+end
+
+
+notes_template = SandboxedErb::Template.new([ExampleHelper])
+
+if !notes_template.compile(notes_sbhtml)
+  puts "Notes: #{notes_template.get_error}"
+  exit
+end
+
+
+
+
+result = listing_template.run({:controller=>controller}, {:users=>users})
+if result.nil?
+  puts "Listing: #{listing_template.get_error}"
+  exit
+end
+
+File.open("listing.html", "w") { |f| f.write(result)}
+
+result = notes_template.run({:controller=>controller}, {:user=>users[0], :users=>users})
+if result.nil?
+  puts "Notes: #{notes_template.get_error}"
+  exit
+end
+
+File.open("notes.html", "w") { |f| f.write(result)}
+
+
+

data/example/listing.sbhtml

@@ -0,0 +1,26 @@
+<h1>User Notes</h1>
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Email</th>
+    <th>Phone</th>
+    <th></th>
+  </tr>
+  <% for user in users %>
+    <tr>
+      <td>
+        <%=link_to "#{user.first_name} #{user.last_name}",  user.url_for(:edit)%>
+      </td>
+      <td>
+        <%=link_to user.email, "mailto: #{user.email}"%>
+      </td>
+      <td>
+        <%= user.phone%>
+      </td>
+      <td>
+        <%=link_to "Send Message",  user.url_for(:send_message)%>
+      </td>
+    </tr>
+  <%end%>
+</table>

data/example/note.rb

@@ -0,0 +1,17 @@
+class Note
+  
+  attr_accessor :from
+  attr_accessor :subject
+  attr_accessor :message
+  attr_accessor :at
+  
+  
+  sandboxed_methods :from, :subject, :message, :at
+
+  def initialize(all_users)
+    @from = all_users[(rand * all_users.length).floor]
+    @subject = Faker::Lorem.sentence
+    @message = Faker::Lorem.paragraph
+    @at = DateTime.now - (rand * 10000)
+  end
+end

data/example/users.rb

@@ -0,0 +1,55 @@
+class Users
+  
+  def self.users(count)
+    res = []
+    for i in 0...count
+      res << User.new(i)
+    end
+    res
+  end
+end
+
+class User
+
+  attr_accessor :id
+  attr_accessor :first_name
+  attr_accessor :last_name
+  attr_accessor :email
+  attr_accessor :phone
+  
+  
+  sandboxed_methods :id, :first_name, :last_name, :email, :phone, :notes, :url_for
+  
+  def initialize(id)
+    @id = id
+    @first_name = Faker::Name.first_name
+    @last_name = Faker::Name.last_name     
+    @email = Faker::Internet.email(@first_name)
+    @phone = Faker::PhoneNumber.phone_number
+  end
+  
+  def set_sandbox_context(context)
+    @sandbox_context = context
+  end
+  
+  def notes
+    @notes ||= build_notes
+  end
+  
+  def build_notes
+    res = []
+    for i in 0..(rand * 5 + 1).to_i
+      res << Note.new(@sandbox_context[:locals][:users])
+    end
+    res
+  end
+  
+  def url_for(action)
+    if action == :edit
+      @sandbox_context[:controller].url_for(:controller=>:users, :action=>:edit, :id=>@id)
+    elsif action == :send_message
+      @sandbox_context[:controller].url_for(:controller=>:users, :action=>:send_message, :id=>@id)
+    end
+    
+  end
+end

data/example/view_notes.sbhtml

@@ -0,0 +1,9 @@
+<h1>Viewing Notes For <%=user.first_name%> <%=user.last_name%></h1>
+
+<% for note in user.notes %>
+<div>
+  <h2><%=note.subject%></h2>
+  <h3>From <%=note.from.first_name%> <%=note.from.last_name%> at <%=format_date(note.at, :short_date)%></h3>
+  <p><%=note.message%>
+</div>
+<%end%>