annotation_security 1.0.1

data/CHANGELOG

@@ -0,0 +1,2 @@
+= 1.0.1
+* first public release

data/HOW-TO

@@ -0,0 +1,261 @@
+= How to secure your Rails application with Annotation Security
+
+== Step 0: Installing Annotation Security
+
+Annotation Security comes as a gem hosted on rubygems.org. You can install it
+via <tt>gem install annotation_security</tt>.
+The gem contains a binary called <tt>annotation_security</tt>. It can be used to
+install the security layer into a rails app via
+<tt>annotation_security --rails RAILS_HOME</tt>. This will make your app ready to be
+secured.
+
+== Step 1: Defining user and roles
+
+Annotation Security assumes that there is a user class, representing the user,
+and some role classes containing additional information if the user has a
+certain role in the application.
+
+If you don't have user or role classes in your application,
+continue with step 2.
+
+=== User
+
+In most cases the user class will be a subclass of ActiveRecord::Base,
+but this is not necessary.
+
+Include the module AnnotationSecurity::User into this class.
+
+ class User < ActiveRecord::Base
+   include AnnotationSecurity::User
+   ...
+
+=== Roles
+
+Include the module AnnotationSecurity::Role into these classes. If you are
+having a hierachy of role classes, only include the module in the topmost class.
+
+ class Role < ActiveRecord::Base
+   belongs_to :user
+   include AnnotationSecurity::Role
+   ...
+
+ class Student < Role
+   # no include here
+   ...
+
+A role object should respond to +user+ with returning the user object
+it belongs to.
+
+Do not include both modules in one class!
+
+=== Connecting user and roles
+
+As next, you should provide some default methods for accessing the roles
+of a user. You can skip this step, but it will be helpfull later on.
+
+There are two types of access methods: <tt>is_ROLE?</tt> and +as_ROLE+.
+
+IS-methods return true or false whether a user has a role or not.
+ class User < ActiveRecord::Base
+   def is_administrator?
+     self.admin_flag == 1
+   end
+   def is_student?
+     self.roles.any? { |role| role.is_a? Student }
+   end
+   ...
+
+AS-methods return a single object or an array of objects representing the role.
+If the user does not have the role, the result should be an empty array or nil.
+ class User < ActiveRecord::Base
+   def as_administrator
+     # there is no administrator class, just return the user
+     is_administrator? ? self : nil
+   end
+   def as_student
+     # assuming a user can only be student once
+     self.roles.detect { |role| role.is_a? Student }
+   end
+   def as_corrector
+     # assuming a user can be a corrector several times
+     self.roles.select { |role| role.is_a? Corrector }
+   end
+
+== Step 2: Providing the current credential
+
+To evaluate the security policies, for each request the current credential has
+to be provided. Therefore, a new filter type was introduced: security filters
+are around filters that are always the first in the filter chain. You can also
+use these filters to react to security violations.
+
+In this example, the user is simply fetched from the session. However, you
+could also pass a symbol or a string (e.g. if you are using API-keys).
+
+Passing +nil+ will be interpreted as not being authenticated in any way.
+
+ class ApplicationController < ActionController::Base
+
+   security_filter :security_filter
+
+   private
+
+   def security_filter
+     SecurityContext.current_credential = session[:user]
+     yield
+   rescue SecurityViolationError
+     if SecurityContext.is? :logged_in
+       render :template => "welcome/not_allowed"
+     else
+       render :template => "welcome/please_login"
+     end
+   end
+
+Please notice that once set, the credential cannot be changed.
+
+== Step 3: Defining your resources
+
+Another wild assumption we made is that your application contains some resources
+you want to protect. In most cases, this will be your ActiveRecord classes.
+To turn them into resources, just call <tt>resource(symbol)</tt> in the class
+definition.
+ class Course < ActiveRecord::Base
+   resource :course
+   ...
+The symbol is used to further identify this class and should be unique.
+
+It is possible (and likely) that the users and roles are resources as well.
+
+If you want to restrict access to other resource classes, see
+AnnotationSecurity::Resource for more information.
+
+== Step 4: Defining relations and rights
+
+in <tt>config/security</tt> you will find the files <tt>relations.rb</tt> and
+<tt>rights.yml</tt>.
+
+=== Relations
+
+The relations between the user (or the roles) and the resources are defined
+as code blocks, that evaluate to true or false.
+
+The <tt>:as</tt>-flag causes that instead of the user object, a role object
+will be passed into the block (using the +as_ROLE+-method from above).
+Similar, the <tt>:is</tt>-flag can be used as precondition.
+
+ AnnotationSecurity.define_relations do
+  resource :course do
+    enrolled :as => :student { |student,course| course.students.include? student }
+    corrector :as => :corrector { |corrector,course| corrector.corrects? course }
+    lecturer :as => :lecturer { |lecturer,course| lecturer.lectures? course }
+  end
+  ...
+
+You can also define relations that are valid for all resources.
+   all_resources do
+	 # corrector and lecturer are defined by the resource
+     responsible { corrector or lecturer }
+     # no block required here
+     administrator :is => :administrator
+   end
+
+For more details and features on defining relations,
+see AnnotationSecurity::RelationLoader.
+
+=== Rights
+
+The rights of application are specified in a YAML-file, they correspond to the
+actions(not necessarily the controller actions) that can be performed on a
+resource. For instance, to edit a course object, you will need the edit-right
+for the course resource. If you are not sure which rights your application
+needs, just skip this now and return after step 5.
+
+Rights should be valid ruby conditional statements.
+
+ course:
+   create: if lecturer
+   show: if enrolled or responsible
+   edit: if responsible
+
+AnnotationSecurity provides two default relations: +logged_in+, that is true
+if there is a user at all, and +self+, that can be used to determine if a user
+or role resource belongs to the current user.
+
+ user:
+   register: unless logged_in
+   show: if logged_in
+   edit: if self or administrator
+ student:
+   show_results: if self
+
+To improve readability, you can append 'may', 'is', 'can' or 'has' as prefix and
+'for', 'in', 'of' or 'to' as suffix to the relation name.
+This is especially recommended if you are defining rights that depend on
+other rights of the resource.
+
+ assignment:
+   edit: if responsible
+   delete: if may_edit
+
+Another example can be found at AnnotationSecurity::RightLoader.
+
+== Step 5: Securing your actions
+
+The main goal of AnnotationSecurity was to remove security logic from
+controller actions. Now you only have to define the abstract effects of an
+action.
+
+An action performs one or more tasks on different resources. You have to provide
+this information as a descriptions, using the
+{Action Annotation Gem}[http://comasy.nixis.de].
+A description always has the form 'ACTION on RESOURCE'.
+
+ desc 'shows a course'
+ def show
+   @course = Course.find(params[:id])
+ end
+
+To perform a task, the user must have the right for it. Thus, when a course is
+fetched from the database during the show-action, the right course/show will be
+evaluated for the current user and the course instance.
+
+In our example, the user has to be responsible or enrolled. If both relations
+evaluate to false, the right is not given and access will be denied by raising
+a SecurityViolationError, which will then be catched in the security filter.
+
+Congratulations, you Rails application is secured now.
+
+== Step 6: Securing your views
+
+However, actions aren't the only place with security code. Links to the actions
+are shown in the view and very often, the view itself depends on the
+user's rights.
+
+When setting up Annotation Security in your Rails project, a helper will be
+included automatically. The most important functions this helper provides are
+<tt>allowed?</tt> and +link_to_if_allowed+.
+
+The method <tt>allowed?</tt> expects a right and a resource and returns true iif
+the current user has that right.
+
+ <% unless allowed? :edit, @course %>
+   <p>You may not edit this course!</p>
+ <% end %>
+
++link_to_if_allowed+ expects the same arguments as +link_to+, except it also
+expects a block like +link_to_if+ (which will be called internally).
+
+ <%= link_to_if_allowed("New", new_course_path) { "You may not create a new course." } %>
+ <%= link_to_if_allowed("Edit", edit_course_path(@course)) { } %>
+ <%= link_to_if_allowed("Delete", @course, {:method => :delete}) { } %>
+
++link_to_if_allowed+ tries to automatically detect the accessed resources.
+In case this should not work for you, see AnnotationSecurity::Helper for more
+features.
+
+== Step 7: Live long and prosper
+
+Well, that's it. Here are some additional notes:
+* in development mode, the rights and relations are reloaded with every request.
+* See AnnotationSecurity::RelationLoader and AnnotationSecurity::RightLoader
+  for more examples and features for defining relations and rights.
+* See AnnotationSecurity::Helper for more methods for securing your views.

data/MIT-LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2009 Nico Rehwaldt, Arian Treffer
+
+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

@@ -0,0 +1,39 @@
+== AnnotationSecurity plugin for Ruby on Rails
+
+This plugin provides a security layer for rails applications. It performs access
+checks based on a behavioural description of controller actions. Security rules
+are defined cleanly separated from your models and controllers.
+
+== Installation steps
+
+The security layer is a gem and may be installed using
+<tt>gem install annotation_security</tt>.
+
+After installing the gem, run <tt>annotation_security --rails RAILS_HOME</tt> to
+integrate the security layer in your rails app. Along with the
+annotation_security plugin this will add
+
+* the AnnotationSecurity::Helper in the <tt>app/helpers</tt> folder of your
+  rails-app. It provides some useful methods to create links and query the
+  security layer from views.
+* example configuration files to setup the security layer under <tt>config/security</tt>
+* an initializer for the security layer under <tt>config/initializer</tt>
+
+== Where to start
+
+You can find a basic introduction how to secure your application {here}[link:files/HOW-TO.html].
+In order to get a detailed idea about how things work, have a deeper look
+inside AnnotationSecurity::ActionController (how to secure your application),
+AnnotationSecurity::RightLoader (how to setup rights) and
+AnnotationSecurity::RelationLoader (how to setup relations).
+
+Have a look at the view methods provided by the AnnotationSecurity::Helper as
+well and at the SecurityContext which is the main entry-point for security related
+functionality in the layer.
+
+== License
+
+Copyright Nico Rehwaldt, Arian Treffer 2009, 2010
+
+You may use, copy and redistribute this library under the same terms as
+{Ruby itself}[http://www.ruby-lang.org/en/LICENSE.txt] or under the MIT license.

data/Rakefile

@@ -0,0 +1,56 @@
+# 
+# To change this template, choose Tools | Templates
+# and open the template in the editor.
+ 
+
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+spec = Gem::Specification.new do |s|
+  s.name = 'annotation_security'
+  s.version = '1.0.1'
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['README', 'MIT-LICENSE', 'CHANGELOG', 'HOW-TO']
+  s.summary = 'A role based security model for rails applications with ' +
+              'descriptive definitions and automated evaluation.'
+  s.description =
+    'AnnotationSecurity provides a role based security model with automated ' +
+    'rule evaluation for Ruby on Rails. It allows you to define user-resource-'+
+    'relations and rights in separate files, keeping your controllers and ' +
+    'views free from any security logic. See the gem\'s homepage for an ' +
+    'example.'
+  s.author = 'Nico Rehwaldt, Arian Treffer'
+  s.email = 'ruby@nixis.de'
+  s.homepage = 'http://tech.lefedt.de/2010/3/annotation-based-security-for-rails'
+  s.add_dependency 'action_annotation', '>= 1.0.1'
+  s.add_dependency 'activesupport', '>= 2.3.5'
+  s.add_development_dependency 'rspec', '>= 1.2.0'
+  s.add_development_dependency 'mocha', '>= 0.9.8'
+  s.executables = ['annotation_security']
+  s.files = %w(CHANGELOG MIT-LICENSE README HOW-TO Rakefile) + Dir.glob("{bin,lib,spec,assets}/**/*")
+  s.require_path = "lib"
+  s.bindir = "bin"
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+Rake::RDocTask.new do |rdoc|
+  files = ['README', 'MIT-LICENSE', 'CHANGELOG', 'HOW-TO', 'lib/**/*.rb']
+  rdoc.rdoc_files.add(files)
+  rdoc.main = "README" # page to start on
+  rdoc.title = "Annotation Security Docs"
+  rdoc.rdoc_dir = 'doc' # rdoc output folder
+  rdoc.options << '--line-numbers'
+end
+
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end

data/assets/app/helpers/annotation_security_helper.rb

@@ -0,0 +1,9 @@
+#
+# = app/helpers/annotation_security_helper.rb
+#
+# This helper provides some useful view methods to be used in conjunction with
+# the plugin. See AnnotationSecurity::Helper for documentation.
+#
+module AnnotationSecurityHelper
+  include AnnotationSecurity::Helper
+end

data/assets/config/initializers/annotation_security.rb

@@ -0,0 +1,12 @@
+#
+# = config/initializers/annotation_security.rb
+#
+# Sets up files under <tt>config/security</tt> which hold
+# the security configuration.
+
+#
+# Add your own files here if they should also be loaded.
+#
+AnnotationSecurity.load_relations('relations')
+AnnotationSecurity.load_rights('rights')
+# AnnotationSecurity.load_rights('rights', 'rb) # loads rights from a ruby file

data/assets/config/security/relations.rb

@@ -0,0 +1,20 @@
+AnnotationSecurity.define_relations do
+
+  # All relations are defined in the context of a resource.
+  # The block should return true iif the user has this relations.
+
+#  all_resources do
+#    administrator(:system, :is => :administrator)
+#    owner_or_admin(:pretest){ owner or administrator }
+#    owner(:system) { |user| user.status == :registered }
+#  end
+
+#  resource :album do
+#    owner { |user, album| album.owner == user }
+#  end
+
+#  resource :picture do
+#    owner "if owner: album"
+#  end
+
+end

data/assets/config/security/rights.yml

@@ -0,0 +1,16 @@
+#all_resources:
+#  show: if logged_in
+#  edit: if may_show
+#  delete: if may_edit
+#
+#welcome:
+#  show: if logged_in
+#  register: unless logged_in
+#
+#picture:
+#  show: if owner or friend
+#
+#user_content:
+#  applies_to: picture, comment
+#  create: if logged_in
+#  edit: if owner

data/assets/vendor/plugins/annotation_security/init.rb

@@ -0,0 +1,14 @@
+#
+# = init.rb
+#
+# This file will be copied to a rails apps `vendors/plugins/annotation_security`
+# directory if the annotation_security gem is installed into a rails app
+# via `annosec --rails`. It will be invoked by the rails app during startup an
+# loads the security layer.
+#
+
+require "annotation_security"
+
+# Initialize security layer for rails root
+puts "Initializing AnnotationSecurity security layer"
+AnnotationSecurity::init_rails(binding)

data/bin/annotation_security

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# The command line to install .
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+
+require "annotation_security/exec"
+
+AnnotationSecurity::Exec::RailsInstaller.new(ARGV).parse!

data/lib/annotation_security/exceptions.rb

@@ -0,0 +1,125 @@
+#
+# = lib/annotation_security/exceptions.rb
+#
+# Provides some Exceptions used within AnnotationSecurity
+
+module AnnotationSecurity
+
+  # Superclass of all security related errors thrown by anno sec
+  class SecurityError < StandardError # :nodoc:
+  end
+
+end
+
+# Exception indicating that some rights were violated.
+#
+class SecurityViolationError < AnnotationSecurity::SecurityError
+
+  def self.access_denied(user,*args) # :nodoc:
+    new(user,*args)
+  end
+
+  def initialize(user=nil,*args) # :nodoc:
+    if user == nil || args.empty?
+      super "Access denied"
+    else
+      super load_args(user,args)
+    end
+  end
+
+  def load_args(user,args) # :nodoc:
+    @user = user
+    @action,@resclass,@res = AnnotationSecurity::Utils.parse_policy_arguments(args)
+    "You (#@user) are missing the right '#@action' for #@resclass" +
+        (@res.blank? ? '' : " '#@res'")
+  end
+
+  # user that violated the right
+  #
+  def user
+    @user
+  end
+
+  # the action that should have been performed on the resource object
+  #
+  def action
+    @action
+  end
+
+  # the resource type
+  #
+  def resource_class
+    @resclass
+  end
+
+  # the resource that was accessed
+  #
+  def resource
+    @res
+  end
+end
+
+module AnnotationSecurity
+
+  # = AnnotationSecurity::RuleError
+  #
+  # Will be raised if a right or relation is defined twice
+  # or has an invalid name.
+  #
+  class RuleError < SecurityError
+    def self.defined_twice(type,rule) # :nodoc:
+      new "The #{type} #{rule} is defined twice"
+    end
+
+    def self.forbidden_name(type,rule) # :nodoc:
+      new "#{rule} is not allowed as #{type} name"
+    end
+  end
+
+  # = AnnotationSecurity::RuleExecutionError
+  #
+  # Will be raised if an error occured while evaluation a right or relation.
+  #
+  class RuleExecutionError < RuleError
+
+    def initialize(rule, proc=false, ex = nil) # :nodoc:
+      if ex
+        log_backtrace(proc,ex)
+        super("An error occured while evaluating #{rule}: \n" +
+              ex.class.name + ": " + ex.message)
+      else
+        super("An error occured while evaluating #{rule}")
+      end
+    end
+
+    def set_backtrace(array) # :nodoc:
+      super((@bt || []) + array[1..-1])
+    end
+
+    private
+
+    # Select all lines of the backtrace above "rule.rb evaluate".
+    # so they can be appended to the backtrace
+    def log_backtrace(proc,ex)
+      return unless proc
+      backtrace = ex.backtrace
+      stop = backtrace.find { |l| l =~ /rule\.rb(.*)`evaluate'/ }
+      stop = backtrace.index(stop) || 5
+      backtrace = backtrace.first(stop)
+      @bt = backtrace.reject { |l| l =~ /annotation_security|active_support/ }
+    end
+
+  end
+
+  # = AnnotationSecurity::RuleNotFoundError
+  #
+  # Will be raised when attempting to acces a right or relation that was not
+  # defined.
+  #
+  class RuleNotFoundError < RuleError
+    def self.for_rule(rname,policy_class)
+      new("Unknown #{policy_class.static? ? 'static' : 'dynamic'} " +
+          "rule '#{rname}' for #{policy_class.name}")
+    end
+  end
+end