Audits1984

A simple auditing tool for console1984.

Add it to your Gemfile:

gem 'audits1984'

Create tables to store audits in the database:

rails audits1984:install:migrations
rails db:migrate

Mount the engine in your routes.rb:

mount Audits1984::Engine => "/console"

If you want to use this gem with an API-only Rails app or an app that's using vite_ruby/vite_rails, or some other custom asset pipeline different from Sprockets and Propshaft, you need just one more thing: configure an asset pipeline so you can serve the JavaScript and CSS included in this gem. We recommend to use Propshaft. You simply need to add this line to your application's Gemfile:

gem "propshaft"

Then execute

$ bundle install

And you should be ready to go.

By default, the library controllers will inherit from the host application's ApplicationController. To authenticate auditors, you need to implement a method #find_current_auditor in your ApplicationController. This method must return a record representing the auditing user. It can be any model but it has to respond to #name.

For example, Imagine all the staff in your company can audit console sessions:

def find_current_auditor
  Current.user if Current.user&.staff?
end

Auditors can generate bearer tokens for API access via the token management UI at /console/auditor_token. By default, Audits1984::ApplicationController will respect a valid bearer token.

For some applications that have more complex authentication requirements, the auditor_from_bearer_token method is available in your base controller class to integrate token authentication into your own auth flow.

For example, to allow bearer token authentication before your normal auth:

class Admin::AuditController < AdminController
  private
    # Extend the existing application authentication to support bearer token
    def require_authentication
      authenticate_by_audit_bearer_token || super
    end

    def authenticate_by_audit_bearer_token
      if auditor = auditor_from_bearer_token
        Current.user = auditor
      end
    end

    def find_current_auditor
      Current.user
    end
end

Then configure audits1984 to use this controller:

config.audits1984.base_controller_class = "Admin::AuditController"

The default migration creates auditor_id as an integer column. If your application uses UUIDs as primary keys, you'll need to modify the generated migration after copying it into your application. Change the auditor reference to specify the UUID type:

# Change this:
t.references :auditor, null: false

# To this:
t.references :auditor, null: false, type: :uuid

See #47 for more details.

The main screen lists the registered console sessions. It includes a form to filter sessions by date, and also to only show that contains sensitive accesses.

You can click on a session to see its commands and choose whether it was an appropiate console usage or not.

After making a decision on the session, you will be redirected to the next pending session, based on the filter configured in the main screen.

That's it. I said it was simple.

These config options are namespaced in config.audits1984:

This project uses Appraisal to test against multiple Rails versions. The Appraisals file defines the matrix and the generated gemfiles live in gemfiles/.

To run tests against a specific Rails version:

bundle exec appraisal rails-8-0 bin/rails test
bundle exec appraisal rails-8-1 bin/rails test

To run tests against all Rails versions:

bundle exec appraisal bin/rails test

To regenerate the appraisal gemfiles after changing the Appraisals file:

bundle exec appraisal install