Audits1984

In a detailed session view, commands are grouped into command_batches. Each batch represents a sequence of commands that were either all non-sensitive, or all executed under the same sensitive access justification.

| Field | Type | Description |
|-------|------|-------------|
| `sensitive` | boolean | Whether these commands accessed sensitive data |
| `justification` | string or null | The justification provided for sensitive access (null for non-sensitive batches) |
| `commands` | array of strings | The console commands executed in this batch |

Auditors can generate bearer tokens via the UI at /console/auditor_token.

If you have complex authentication requirements, you can integrate token authentication into your own flow using the auditor_from_bearer_token method. To use a custom controller as the base for Audits1984, configure config.audits1984.base_controller_class.

Example of integrating bearer tokens into an Admin::AuditController:

class Admin::AuditController < AdminController
  private

    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 in your configuration:

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

All API requests require authentication via a Bearer token provided in the Authorization header. Additionally, every request must include the Accept: application/json header.

Generating a Token

Tokens are generated through the web interface. An authenticated auditor must visit /auditor_token and click "Generate Token".

Important Constraints:

• The plaintext token is displayed only once and cannot be retrieved again.
• Tokens expire after 1 week.
• Only one active token exists per auditor; generating a new token invalidates any previous token.

Authorization: Bearer <token>
Accept: application/json

To install Audits1984 in your Rails application, add the gem to your Gemfile, run the installation migrations, and mount the engine in your routes.

1. Add the gem

gem 'audits1984'

2. Install migrations

Run the following commands to create the necessary audit tables:

rails audits1984:install:migrations
rails db:migrate

3. Mount the engine

Add the following to your config/routes.rb to expose the audit interface at /console:

mount Audits1984::Engine => "/console"

The default migration creates auditor_id as an integer column. If your application uses UUIDs for primary keys, you must manually modify the generated migration file before running rails db:migrate.

Change the auditor reference to include type: :uuid:

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

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

By default, Audits1984 controllers inherit from your application's ApplicationController. To authenticate auditors, you must implement a #find_current_auditor method in your ApplicationController.

This method must return a record representing the auditing user. The returned object can be any model, but it must respond to the #name method.

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

If you are using an API-only Rails app or a custom asset pipeline like vite_ruby/vite_rails (instead of Sprockets or Propshaft), you must ensure an asset pipeline is configured to serve the gem's JavaScript and CSS.

It is recommended to use Propshaft. Add it to your Gemfile and install:

$ bundle install

gem "propshaft"

Audits1984 configuration options are namespaced under config.audits1984.

| Name | Description |
| --- | --- |
| `auditor_class` | The name of the auditor class. By default it's `::User.` |
| `auditor_name_attribute` | The attribute on the auditor class that returns the auditor's name. By default it's `:name`. |
| `base_controller_class` | The host application base class that will be the parent of `audit1984` controllers. By default it's `::ApplicationController`. |

If you are using Audits1984 in a Rails API-only application (config.api_only = true), the engine automatically injects the necessary middleware to support standard web features required by the auditing interface:

• ActionDispatch::Flash: For flash message support.
• Rack::MethodOverride: To support HTTP method overriding (e.g., via _method parameter).

No manual middleware configuration is required if api_only is enabled.

Create a new audit for a specific session. The audit is automatically associated with the authenticated auditor.

Status Values:

• pending: Audit has been started but not yet completed.
• approved: Session access was appropriate and legitimate.
• flagged: Session access was suspicious or inappropriate.

POST /sessions/:session_id/audits

Request Body:

{
  "audit": {
    "status": "approved",
    "notes": "Access was appropriate for the stated reason"
  }
}

Update an existing audit using PATCH or PUT. Note: Only the auditor who originally created the audit is permitted to update it.

PATCH /sessions/:session_id/audits/:id
PUT /sessions/:session_id/audits/:id

Request Body:

{
  "audit": {
    "status": "flagged",
    "notes": "Upon further review, this access seems suspicious"
  }
}