The project is in a healthy, maintained state
Disallow insecure, unscoped, finds


~> 1.0, >= 1.0.8
~> 2.5
~> 1.0, >= 1.0.2
>= 13
>= 3
~> 1.0, >= 1.0.5
~> 0.1, >= 0.1.16
~> 18.2, >= 18.2.1
~> 0.5, >= 0.5.2
~> 1.0, >= 1.0.8
>= 1.6.9, < 2
~> 0.9, >= 0.9.34
~> 0.0


~> 1.1, >= 1.1.4
 Project Readme


CI Build Test Coverage Maintainability Depfu

Liberapay Patrons Sponsor Me on Github

Buy me coffee donation button Patreon donate button


  • ⚙️ Ruby >= 2.7, plus JRuby and Truffleruby, but only non-EOL Rubies are officially supported
  • ⚙️ Rails >= 7.0 (actually, it only requires activerecord)
Project bundle add active_security
1️⃣ name, license, docs, standards RubyGems.org License: MIT RubyDoc.info YARD Documentation SemVer 2.0.0 Keep-A-Changelog 1.0.0
2️⃣ version & activity Gem Version Total Downloads Download Rank Source Code Open PRs Closed PRs
3️⃣ maintenance & linting Maintainability Helpers Depfu Contributors Style
4️⃣ testing Supported Heads Unsupported
5️⃣ coverage & security CodeClimate CodeCov Coveralls Security Policy CodeQL Code Coverage
6️⃣ resources Get help on Codementor Blog Wiki
7️⃣ ... 💖 Liberapay Patrons Sponsor Me Follow Me on LinkedIn Find Me on WellFound: Find Me on CrunchBase My LinkTree Follow Me on Ruby.Social Tweet @ Peter 💻 🌏


Install the gem and add to the application's Gemfile by executing:

$ bundle add active_security

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install active_security


All documentation is in the source so check there if the following is not enough.

Setting Up ActiveSecurity in Your Model

To use ActiveSecurity in your ActiveRecord models, you must first either extend or include the ActiveSecurity module (it makes no difference), then invoke the {ActiveSecurity::Base#active_security active_security} method to configure your desired options:

class Foo < ActiveRecord::Base
  include ActiveSecurity
  active_security :use => {finders: {default_finders: :restricted}, scoped: {scope: :bar_id}}

The most important option is :use, which you use to tell ActiveSecurity which addons it should use. See the documentation for {ActiveSecurity::Base#active_security} for a list of all available addons, or skim through the rest of the docs to get a high-level overview.

A note about single table inheritance (STI): you must extend ActiveSecurity in all classes that participate in STI, both your parent classes and their children.

The Basic Setup: Simple Models

By default the :restricted plugin is the only one configured, and the restricted scope must be explicitly added to every query. This is the simplest way to use ActiveSecurity. But it is messy, and laborious. It will ensure that finds are executed within a where scope:

class User < ActiveRecord::Base
  extend ActiveSecurity

User.restricted.find(1)                       # blows up, because no scope
User.where(name: "Bart").restricted.find(1)   # returns the user

The Strict Setup: Magic Finders

The problem with the above approach is that a naked find (User.find(1)) still works, and is just as insecure as before. The :finders plugin fixes this problem, so you don't need to add restricted everywhere.

class User < ActiveRecord::Base
  extend ActiveSecurity
  active_security use: {finders: {default_finders: :restricted}}

User.find(1)                                 # blows up, because no scope
User.where(name: "Bart").find(1)             # returns the user
User.where(name: "Bart").restricted.find(1)  # also returns the user

Configuration: ActiveSecurity's behavior in a model

Here's a basic config.

class Post < ActiveRecord::Base
  extend ActiveSecurity
  active_security use: :finders

Now let's get crazy secure!

When given the optional block, this method will yield the class's instance of {ActiveSecurity::Configuration} to the block before evaluating other arguments, so configuration values set in the block may be overwritten by the arguments. This order was chosen to allow passing the same proc to multiple models, while being able to override the values it sets. Here is a contrived example:

$active_security_config_proc = Proc.new do |config|
  config.use :finders

class Foo < ActiveRecord::Base
  extend ActiveSecurity
  active_security &$active_security_config_proc

class Bar < ActiveRecord::Base
  extend ActiveSecurity
  active_security &$active_security_config_proc

However, it's usually better to use {ActiveSecurity.defaults} for this:

ActiveSecurity.defaults do |config|
  config.use :finders, default_finders: :restricted

class Foo < ActiveRecord::Base
  extend ActiveSecurity

class Bar < ActiveRecord::Base
  extend ActiveSecurity

In general you should use the block syntax either because of your personal aesthetic preference, or because you need to share some functionality between multiple models that can't be well encapsulated by {ActiveSecurity.defaults}.

Order Method Calls in a Block vs Ordering Options

When calling this method without a block, you may set the hash options in any order, so long as they either have no dependencies, or are coupled with their respective module.

Here's an example that configures every plugin:

class Person < ActiveRecord::Base
  active_security use: {
    finders: {default_finders: :restricted},
    scoped: {scope: :name},
    privileged: {}

Person.find(1)                                 # blows up, because no scope
Person.where(name: "Bart").find(1)             # returns the person
Person.where(age: 29).find(1)                  # blows up, because name scope wasn't used
Person.where(age: 29).privileged.find(1)       # returns the person, because privileged
Person.where(name: "Bart").restricted.find(1)  # also returns the person, because name scope used

However, when using block-style invocation, be sure to call ActiveSecurity::Configuration's {ActiveSecurity::Configuration#use use} method prior to the associated configuration options, because it will include modules into your class, and these modules in turn may add required configuration options to the @active_security_configuration's class:

class Person < ActiveRecord::Base
  active_security do |config|
    # This will work
    config.use :scoped
    config.scope = "family_id"

class Person < ActiveRecord::Base
  active_security do |config|
    # This will fail
    config.scope = "family_id"
    config.use :scoped

Including Your Own Modules

Because :use can accept a name or a Module, {ActiveSecurity.defaults defaults} can be a convenient place to set up behavior common to all classes using ActiveSecurity. You can include any module, or more conveniently, define one on-the-fly. For example, let's say you want to globally override the error that is raised when no scope is used:

ActiveSecurity.defaults do |config|
  config.use :finders
  config.use Module.new {
    def self.setup(model_class)
      model_class.instance_eval do
        relation.class.send(:prepend, RaiseOverride)
        model_class.singleton_class.send(:prepend, RaiseOverride)

      association_relation_delegate_class = model_class.relation_delegate_class(::ActiveRecord::AssociationRelation)
      association_relation_delegate_class.send(:prepend, RaiseOverride)

    module RaiseOverride
      def raise_if_not_scoped
        puts "My errors are better than yours"
        raise StandardError, "Calm Down"

Running Specs

The basic compatibility matrix:

appraisal install
appraisal rake test

Sometimes also:

BUNDLE_GEMFILE=gemfiles/vanilla.gemfile appraisal update

NOTE: This results in bad paths to the gemspec. gemspec path: "../../" needs to be replaced with gemspec path: "../" in each Appraisal gemfile.

Code Coverage

Coverage Graph

🪇 Code of Conduct

Everyone interacting in this project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

📌 Versioning

This Library adheres to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions.

To get a better understanding of how SemVer is intended to work over a project's lifetime, read this article from the creator of SemVer:

As a result of this policy, you can (and should) specify a dependency on these libraries using the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency("active_security", "~> 1.0")

📄 License

The gem is available as open source under the terms of the MIT License License: MIT. See LICENSE.txt for the official Copyright Notice.

© Copyright