Heimdallr

Heimdallr is a gem for managing security restrictions for ActiveRecord objects on field level; think of it as a supercharged CanCan. Heimdallr favors whitelisting over blacklisting, convention over configuration and is duck-type compatible with most of existing code.

# Define a typical set of models.
class User < ActiveRecord::Base
  has_many :articles
end

class Article < ActiveRecord::Base
  include Heimdallr::Model

  belongs_to :owner, :class_name => 'User'

  restrict do |user, record|
    if user.admin?
      # Administrator or owner can do everything
      scope :fetch
      scope :delete
      can [:view, :create, :update]
    else
      # Other users can view only their own or non-classified articles...
      scope :fetch,  -> { where('owner_id = ? or secrecy_level < ?', user.id, 5) }
      scope :delete, -> { where('owner_id = ?', user.id) }

      # ... and see all fields except the actual security level
      # (through owners can see everything)...
      if record.try(:owner) == user
        can :view
        can :update, {
          # each field may have validators that will allow update
          secrecy_level: { inclusion: { in: 0..4 } }
        }
      else
        can    :view
        cannot :view, [:secrecy_level]
      end

      # ... and can create them with certain restrictions.
      can :create, %w(content)
      can :create, {
        # each field may have fixed value that cannot be overridden
        owner_id:      user.id,
        secrecy_level: { inclusion: { in: 0..4 } }
      }
    end
  end
end

# Create some fictional data.
admin   = User.create admin: true
johndoe = User.create admin: false

Article.create id: 1, owner: admin,   content: "Nothing happens",  secrecy_level: 0
Article.create id: 2, owner: admin,   content: "This is a secret", secrecy_level: 10
Article.create id: 3, owner: johndoe, content: "Hello World"

# Get a restricted scope for the user.
secure = Article.restrict(johndoe)

# Use any ARel methods:
secure.pluck(:content)
# => ["Nothing happens", "Hello World"]

# Everything should be permitted explicitly:
secure.first.delete
# ! Heimdallr::PermissionError is raised
secure.find(1).secrecy_level
# ! Heimdallr::PermissionError is raised

# There is a helper for views to be easily written:
view_passed = secure.first.implicit
view_passed.secrecy_level
# => nil

# If only a single value is possible, it is inferred automatically:
secure.create! content: "My second article"
# => Article(id: 4, owner: johndoe, content: "My second article", security_level: 0)

# ... and cannot be changed:
secure.create! owner: admin, content: "I'm a haxx0r"
# ! Heimdallr::PermissionError is raised

# You can use any valid ActiveRecord validators, too:
secure.create! content: "Top Secret", secrecy_level: 10
# ! ActiveRecord::RecordInvalid is raised

# John Doe would not see what he is not permitted to, ever:
# -- I know that you have this classified material! It's in folder #2.
secure.find 2
# ! ActiveRecord::RecordNotFound is raised
# -- No, it is not.

The DSL is described in documentation for Heimdallr::Model.

Ideology

Heimdallr aims to make security explicit, but nevertheless convenient. It does not allow one to call any implicit operations which may be used maliciously; instead, it forces you to explicitly call #insecure method which returns the underlying object. This single point of entry is easily recognizable with code.

Heimdallr has two restrictions strategies: explicit and implicit. By default it will use explicit strategy that means it will raise an exception for every insecure request. Calling .implicit will give you a copy of proxy object switched to another strategy. With that it will silently return nil for every attribute that is inaccessible.

There are several options which alter Heimdallr's behavior in security-sensitive ways. They are described in Heimdallr.

Rails notes

As of Rails 3.2.3 attr_accessible is in whitelist mode by default. That makes no sense when using Heimdallr. To turn it off set the config.active_record.whitelist_attributes value to false at yours application.rb.

Typical cases

While working with MVC you'll mostly use Heimdallr-wrapped models inside your controllers and views. To protect your controllers using DSL from the model you can use Heimdallr::Resource extension gem.

To facilitate views you can use implicit strategy which is described above.

Compatibility

Ruby 1.8 and ActiveRecord versions prior to 3.0 are not supported.

Credits

• Peter Zotov (@whitequark)
• Boris Staal (@_inossidabile)

LICENSE

It is free software, and may be redistributed under the terms of MIT license.