### Install Migrations and Run Database Migrations

Source: https://context7.com/basecamp/console1984/llms.txt

Install Console1984's database migrations and then run `rails db:migrate` to create the necessary audit tables.

```bash
# Install migrations and run them
rails console1984:install:migrations
rails db:migrate
```

--------------------------------

### Get All Sessions for a User

Source: https://context7.com/basecamp/console1984/llms.txt

Retrieves and displays the creation time and reason for all console sessions associated with a given user.

```ruby
user.sessions.order(created_at: :desc).each do |session|
  puts "#{session.created_at}: #{session.reason}"
end
```

--------------------------------

### Start Rails Console Session

Source: https://github.com/basecamp/console1984/blob/master/README.md

Initiates a Rails console session, prompting for a reason to use the console and documenting all commands executed.

```bash
$ rails c

You have access to production data here. That's a big deal. As part of our promise to keep customer data safe and private, we audit the commands you type here. Let's get started!



Commands:

* decrypt!: enter unprotected mode with access to encrypted information

Unnamed, why are you using this console today?

> ...
```

--------------------------------

### Protected Connection Error Example

Source: https://github.com/basecamp/console1984/blob/master/README.md

When a connection to a protected system is attempted in default protected mode, an error like `Console1984::Errors::ProtectedConnection` will be raised.

```ruby
irb(main)> Rails.cache.read("some key") # raises Console1984::Errors::ProtectedConnection
```

--------------------------------

### Start a Protected Console Session

Source: https://context7.com/basecamp/console1984/llms.txt

Initiate a Rails console session in a protected environment. Users will be prompted for a session reason, which is logged along with all subsequent commands. Encrypted data will appear as ciphertext by default.

```bash
# Starting a console session
$ CONSOLE_USER=david rails c -e production
```

```irb
# Console output:
# You have access to production data here. That's a big deal. As part of our
# promise to keep customer data safe and private, we audit the commands you
# type here. Let's get started!
#
# Commands:
# * decrypt!: enter unprotected mode with access to encrypted information
#
# david, why are you using this console today?
# > Investigating customer support ticket #12345

# Now in protected mode - encrypted data shows as ciphertext
irb(main):001:0> User.last.email
=> "{\"p\":\"iu6+LfnNlurC6sL++JyOIDvedjNSz/AvnZQ=\",\"h\":{...}}"

irb(main):002:0> User.last.name
=> "{\"p\":\"7L1l/5UiYsFQqqo4jfMZtLwp90KqcrIgS7HqgteVjuM=\",\"h\":{...}}"
```

--------------------------------

### Get All Commands for a Session

Source: https://context7.com/basecamp/console1984/llms.txt

Retrieves and iterates through all commands executed within a specific console session, displaying their creation time and statements.

```ruby
session = Console1984::Session.last
session.commands.sorted_chronologically.each do |cmd|
  puts "[#{cmd.created_at}] #{cmd.sensitive? ? '[SENSITIVE]' : ''}"
  puts cmd.statements
end
```

--------------------------------

### Handle MissingUsername Error

Source: https://context7.com/basecamp/console1984/llms.txt

Example of rescuing Console1984::Errors::MissingUsername when the CONSOLE_USER environment variable is not set and ask_for_username_if_empty is false.

```ruby
# Starting console without CONSOLE_USER
begin
  # ... code that requires username ...
rescue Console1984::Errors::MissingUsername
  puts "Set CONSOLE_USER environment variable"
end
```

--------------------------------

### Handle ForbiddenIncineration Error

Source: https://context7.com/basecamp/console1984/llms.txt

Example of rescuing Console1984::Errors::ForbiddenIncineration when attempting to delete a session too early.

```ruby
begin
  recent_session = Console1984::Session.last
  recent_session.incinerate
rescue Console1984::Errors::ForbiddenIncineration => e
  puts "Cannot delete yet: #{e.message}"
end
```

--------------------------------

### Handle ProtectedConnection Error

Source: https://context7.com/basecamp/console1984/llms.txt

Example of rescuing Console1984::Errors::ProtectedConnection when attempting to access a protected URL in protected mode.

```ruby
begin
  Rails.cache.read("key")
rescue Console1984::Errors::ProtectedConnection => e
  puts "Access blocked: #{e.message}"
  puts "Run decrypt! to access sensitive systems"
end
```

--------------------------------

### Get Recent Console Commands

Source: https://context7.com/basecamp/console1984/llms.txt

Retrieves and displays the username and truncated statements for the 20 most recent commands executed in console sessions.

```ruby
Console1984::Command.order(created_at: :desc).limit(20).each do |cmd|
  puts "[#{cmd.session.user.username}] #{cmd.statements.truncate(80)}"
end
```

--------------------------------

### Handle ForbiddenCommandAttempted Error

Source: https://context7.com/basecamp/console1984/llms.txt

Example of the error raised when attempting to execute dangerous commands like eval, instance_eval, or class_eval.

```ruby
irb(main):001:0> eval("User.delete_all")
# Forbidden command attempted: eval("User.delete_all")
```

--------------------------------

### Generate Console1984 Migrations

Source: https://github.com/basecamp/console1984/blob/master/README.md

Run these commands to create the necessary database tables for storing console activity logs.

```ruby
rails console1984:install:migrations
```

```ruby
rails db:migrate
```

--------------------------------

### Run Rails Tests with Different Databases

Source: https://github.com/basecamp/console1984/blob/master/README.md

Execute the test suite against SQLite, MySQL, or PostgreSQL. Ensure Docker containers and databases are set up first.

```bash
bin/rails test # against SQLite (default)
bin/rails test TARGET_DB=mysql
bin/rails test TARGET_DB=postgres
bin/rails test TARGET_DB=sqlite
```

--------------------------------

### Find or Create a Console User

Source: https://context7.com/basecamp/console1984/llms.txt

Creates a new user if one with the specified username does not exist, otherwise finds the existing user.

```ruby
user = Console1984::User.find_or_create_by!(username: "david")
```

--------------------------------

### Configure Known Agents for QueryAuditor

Source: https://context7.com/basecamp/console1984/llms.txt

Set up known AI agents for Console1984's QueryAuditor to log Rails query API usage with context.

```ruby
# Automatically installed during engine initialization
# Subscribes to "query.rails" ActiveSupport notifications

# Known agents are detected via environment variables
Console1984::QueryAuditor.known_agents = {
  "CLAUDECODE"      => "Claude Code",
  "CODEX_THREAD_ID" => "Codex"
}

# When a Rails query is executed via these agents, it's logged with context
```

--------------------------------

### Run Rails Tests Against All Rails Versions

Source: https://github.com/basecamp/console1984/blob/master/README.md

Execute the test suite against all defined Rails versions in the Appraisal configuration. This provides comprehensive compatibility testing.

```bash
bundle exec appraisal bin/rails test
```

--------------------------------

### SSH Configuration for Username Propagation

Source: https://context7.com/basecamp/console1984/llms.txt

Configure SSH server and client to propagate the CONSOLE_USER environment variable for authentication.

```bash
# Server: /etc/ssh/sshd_config
AcceptEnv LANG LC_* CONSOLE_USER

# Restart SSH service
sudo service sshd restart

# Client: ~/.ssh/config
Host production-server
  HostName prod.example.com
  SetEnv CONSOLE_USER=david
  User deploy

# Or set in shell profile
# ~/.bashrc or ~/.zshrc
export CONSOLE_USER="david"
```

--------------------------------

### Configure Protected Environments

Source: https://github.com/basecamp/console1984/blob/master/README.md

Specify which environments Console1984 should be active in by default. It is enabled in production.

```ruby
config.console1984.protected_environments = %i[ production staging ]
```

--------------------------------

### Configure SSH to Accept Environment Variables

Source: https://github.com/basecamp/console1984/blob/master/README.md

Modify the SSH server configuration to accept specific environment variables. Restart the SSH service after making changes.

```bash
AcceptEnv LANG LC_* CONSOLE_USER
```

```bash
service sshd restart
```

--------------------------------

### Verify Return to Protected Mode

Source: https://github.com/basecamp/console1984/blob/master/README.md

After typing `encrypt!`, accessing encrypted data will again show the ciphertext instead of the decrypted content.

```ruby
irb(main)> Topic.last.name
  Topic Load (1.4ms)  SELECT `topics`.* FROM `topics` ORDER BY `topics`.`id` DESC LIMIT 1
=> "{\"p\":\"iu6+LfnNlurC6sL++JyOIDvedjNSz/AvnZQ=\",\"h\":{\"iv\":\"BYa86+JNM/LdkC18\",\"at\":\"r4sQNoSyIlAjJdZEKHVMow==\",\"k\":{\"p\":\"7L1l/5UiYsFQqqo4jfMZtLwp90KqcrIgS7HqgteVjuM=\",\"h\":{\"iv\":\"ItwRYxZAerKIoSZ8\",\"at\":\"ZUSNVfvtm4wAYWLBKRAx/g==\",\"e\":\"QVNDSUktOEJJVA==\"}},\"i\":\"OTdiOQ==\"}}"
```

--------------------------------

### Configure Protected External System URLs

Source: https://github.com/basecamp/console1984/blob/master/README.md

Add URLs of sensitive external systems like Elasticsearch or Redis to `config.console1984.protected_urls` in your environment configuration file to prevent accidental data exposure.

```ruby
config.console1984.protected_urls = [ "https://my-app-us-east-1-whatever.us-east-1.es.amazonaws.com", "redis://my-app-cache-1.whatever.cache.amazonaws.com:6379" ]
```

--------------------------------

### Return to Protected Mode with encrypt!

Source: https://context7.com/basecamp/console1984/llms.txt

Execute the `encrypt!` command in the Rails console to exit unprotected mode and return to the default protected state. This action is logged and may prompt a review of commands entered during the unprotected session.

```irb
# Return to protected mode
irb(main):001:0> encrypt!

# Great! You are back in protected mode. When we audit, we may reach out for
# a conversation about the commands you entered. What went well? Did you
# solve the problem without accessing personal data?
```

--------------------------------

### Configure Console1984 Incineration Settings

Source: https://context7.com/basecamp/console1984/llms.txt

Sets global configuration for Console1984's automatic session incineration, including enabling/disabling, retention period, and background queue.

```ruby
# config/environments/production.rb
config.console1984.incinerate = true
config.console1984.incinerate_after = 1.year  # Keep for 1 year
config.console1984.incineration_queue = "low_priority"
```

--------------------------------

### Return to Protected Mode

Source: https://github.com/basecamp/console1984/blob/master/README.md

Type `encrypt!` to return to the default protected mode, where encrypted data is not decrypted.

```ruby
irb(main):004:0> encrypt!
```

--------------------------------

### Configure SSH Client to Set Environment Variables

Source: https://github.com/basecamp/console1984/blob/master/README.md

Set environment variables for SSH client connections. This ensures that variables like CONSOLE_USER are sent to the server.

```sshconfig
Host *
  SetEnv CONSOLE_USER=david
```

--------------------------------

### Run Rails Tests Against Specific Rails Versions

Source: https://github.com/basecamp/console1984/blob/master/README.md

Test the application against specific Rails versions using Appraisal. This is useful for ensuring compatibility with different Rails releases.

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

--------------------------------

### Find Sensitive Accesses by Justification Pattern

Source: https://context7.com/basecamp/console1984/llms.txt

Filters sensitive accesses to find those where the justification matches a specific SQL LIKE pattern, useful for finding accesses related to support tickets.

```ruby
ticket_accesses = Console1984::SensitiveAccess.where("justification LIKE ?", "%support.example.com/tickets%")
```

--------------------------------

### Configure Session Incineration Period

Source: https://github.com/basecamp/console1984/blob/master/README.md

Set `config.console1984.incinerate_after` to customize how long sessions are retained before automatic incineration. Default is 30 days.

```ruby
config.console1984.incinerate_after = 1.year
```

--------------------------------

### Configure Protected URLs in Rails

Source: https://context7.com/basecamp/console1984/llms.txt

Define a list of sensitive URLs that Console1984 should block access to when in protected mode.

```ruby
# config/environments/production.rb
config.console1984.protected_urls = [
  # Elasticsearch
  "https://my-app-us-east-1.es.amazonaws.com",

  # Redis instances
  "redis://my-app-cache-1.cache.amazonaws.com:6379",
  "redis://my-app-cache-2.cache.amazonaws.com:6379",

  # Internal APIs
  "https://internal-api.example.com"
]

# In protected mode, connections are blocked
irb(main):001:0> Rails.cache.read("user:123")
# Console1984::Errors::ProtectedConnection: A connection attempt was prevented
# because it represents a sensitive access. Please run decrypt! and try again.

# After running decrypt!, connections are allowed
irb(main):002:0> decrypt!
# (provide justification)
irb(main):003:0> Rails.cache.read("user:123")
=> { name: "John", email: "john@example.com" }
```

--------------------------------

### Regenerate Appraisal Gemfiles

Source: https://github.com/basecamp/console1984/blob/master/README.md

Update the generated gemfiles for Appraisal after modifying the Appraisals file. This ensures the test matrix reflects the latest configuration.

```bash
bundle exec appraisal install
```

--------------------------------

### Find Sensitive Console Commands

Source: https://context7.com/basecamp/console1984/llms.txt

Identifies and displays details for commands that were executed during a sensitive access, including the user and justification.

```ruby
sensitive_commands = Console1984::Command.where.not(sensitive_access: nil)
sensitive_commands.each do |cmd|
  puts "User: #{cmd.session.user.username}"
  puts "Justification: #{cmd.sensitive_access.justification}"
  puts "Command: #{cmd.statements}"
end
```

--------------------------------

### Find All Sensitive Accesses

Source: https://context7.com/basecamp/console1984/llms.txt

Retrieves and displays details for all recorded sensitive accesses, including the associated user, justification, and count of commands executed during the access.

```ruby
Console1984::SensitiveAccess.includes(:session => :user).each do |access|
  puts "User: #{access.session.user.username}"
  puts "Justification: #{access.justification}"
  puts "Time: #{access.created_at}"
  puts "Commands during access: #{access.commands.count}"
  puts "---"
end
```

--------------------------------

### Enter Unprotected Mode with decrypt!

Source: https://context7.com/basecamp/console1984/llms.txt

Use the `decrypt!` command within the Rails console to temporarily enter unprotected mode. This allows viewing of encrypted data in plain text and access to external protected systems. A justification for accessing sensitive data is required and logged.

```irb
# Enter unprotected mode to decrypt data
irb(main):001:0> decrypt!

# Before you can access personal information, you need to ask for and get
# explicit consent from the user(s). david, where can we find this consent
# (a URL would be great)?
# > https://support.example.com/tickets/12345 - customer requested data export

# Ok! You have access to encrypted information now. We pay extra close
# attention to any commands entered while you have this access.

# Now encrypted data is visible
irb(main):002:0> User.last.email
=> "customer@example.com"

irb(main):003:0> User.last.name
=> "John Smith"

# External protected systems are now accessible
irb(main):004:0> Rails.cache.read("user:123:profile")
=> { name: "John Smith", preferences: {...} }
```

--------------------------------

### Query Recent Console Sessions

Source: https://context7.com/basecamp/console1984/llms.txt

Retrieves and displays details for the 10 most recent console sessions. Useful for auditing recent activity.

```ruby
Console1984::Session.order(created_at: :desc).limit(10).each do |session|
  puts "User: #{session.user.username}"
  puts "Reason: #{session.reason}"
  puts "Created: #{session.created_at}"
  puts "Sensitive: #{session.sensitive?}"
  puts "Commands: #{session.commands.count}"
  puts "---"
end
```

--------------------------------

### Enter Unprotected Mode to Decrypt Data

Source: https://github.com/basecamp/console1984/blob/master/README.md

Use the `decrypt!` command within the Rails console to gain access to data encrypted with Active Record encryption. This action is logged as sensitive.

```ruby
irb(main)> Topic.last.name
  Topic Load (1.4ms)  SELECT `topics`.* FROM `topics` ORDER BY `topics`.`id` DESC LIMIT 1
=> "{\"p\":\"iu6+LfnNlurC6sL++JyOIDvedjNSz/AvnZQ=\",\"h\":{\"iv\":\"BYa86+JNM/LdkC18\",\"at\":\"r4sQNoSyIlAjJdZEKHVMow==\",\"k\":{\"p\":\"7L1l/5UiYsFQqqo4jfMZtLwp90KqcrIgS7HqgteVjuM=\",\"h\":{\"iv\":\"ItwRYxZAerKIoSZ8\",\"at\":\"ZUSNVfvtm4wAYWLBKRAx/g==\",\"e\":\"QVNDSUktOEJJVA==\"}},\"i\":\"OTdiOQ==\"}}"
irb(main)> decrypt!
```

--------------------------------

### Manually Incinerate a Session

Source: https://context7.com/basecamp/console1984/llms.txt

Initiates the incineration (deletion) process for a console session. Raises ForbiddenIncineration if the session is too new.

```ruby
session = Console1984::Session.last
session.incinerate  # Raises ForbiddenIncineration if too early
```

--------------------------------

### Manually Schedule Session Incineration

Source: https://context7.com/basecamp/console1984/llms.txt

Explicitly schedules a session to be incinerated by the background job, respecting configured retention policies.

```ruby
Console1984::IncinerationJob.schedule(session)
```

--------------------------------

### Console1984 Database Migration

Source: https://context7.com/basecamp/console1984/llms.txt

Defines the database schema for Console1984, including tables for users, sessions, commands, and sensitive accesses.

```ruby
# db/migrate/xxx_create_console1984_tables.rb
class CreateConsole1984Tables < ActiveRecord::Migration[7.0]
  def change
    # Users who have accessed the console
    create_table :console1984_users do |t|
      t.string :username, null: false
      t.timestamps
      t.index [:username]
    end

    # Console sessions with reason
    create_table :console1984_sessions do |t|
      t.text :reason
      t.references :user, null: false, index: false
      t.timestamps
      t.index :created_at
      t.index [:user_id, :created_at]
    end

    # Commands executed during sessions (encrypted)
    create_table :console1984_commands do |t|
      t.text :statements  # Encrypted with Active Record Encryption
      t.references :sensitive_access
      t.references :session, null: false, index: false
      t.timestamps
      t.index [:session_id, :created_at, :sensitive_access_id],
              name: "on_session_and_sensitive_chronologically"
    end

    # Sensitive access records (decrypt! justifications)
    create_table :console1984_sensitive_accesses do |t|
      t.text :justification
      t.references :session, null: false
      t.timestamps
    end
  end
end
```

--------------------------------

### Add Console1984 to Gemfile

Source: https://github.com/basecamp/console1984/blob/master/README.md

Include the console1984 gem in your application's Gemfile to add its functionality.

```ruby
gem 'console1984'
```

--------------------------------

### Configure Console1984 Settings

Source: https://context7.com/basecamp/console1984/llms.txt

Configure Console1984 settings within your Rails application configuration. This includes specifying protected environments, external URLs to protect, session incineration behavior, username resolution, and custom warning messages.

```ruby
# config/application.rb or config/environments/production.rb
module MyApp
  class Application < Rails::Application
    # Environments where console1984 is active (default: production only)
    config.console1984.protected_environments = %i[production staging]

    # External systems to protect (Redis, Elasticsearch, etc.)
    config.console1984.protected_urls = [
      "https://my-app-us-east-1.es.amazonaws.com",
      "redis://my-app-cache.cache.amazonaws.com:6379"
    ]

    # Session incineration settings
    config.console1984.incinerate = true
    config.console1984.incinerate_after = 30.days
    config.console1984.incineration_queue = "console1984_incineration"

    # Username resolution (default reads CONSOLE_USER env var)
    config.console1984.username_resolver = Console1984::Username::EnvResolver.new("CONSOLE_USER")
    config.console1984.ask_for_username_if_empty = false

    # Custom warning messages
    config.console1984.production_data_warning = "You have access to production data!"
    config.console1984.enter_unprotected_encryption_mode_warning = "Entering unprotected mode..."
    config.console1984.enter_protected_mode_warning = "Back to protected mode."

    # Base record class for console1984 models
    config.console1984.base_record_class = "::ApplicationRecord"
  end
end
```

--------------------------------

### Find Sensitive Console Sessions

Source: https://context7.com/basecamp/console1984/llms.txt

Identifies all console sessions where sensitive data was accessed (decrypt! was used). Requires joining with sensitive_accesses.

```ruby
sensitive_sessions = Console1984::Session.joins(:sensitive_accesses).distinct
```

--------------------------------

### Configure Username Resolver in Rails

Source: https://context7.com/basecamp/console1984/llms.txt

Set a custom username resolver in your Rails application's production environment configuration.

```ruby
class MyApp::ConsoleUsernameResolver
  include Console1984::Freezeable

  def current
    # Resolve username from AWS metadata, SSO, or other source
    fetch_from_aws_metadata || fetch_from_sso || ENV["CONSOLE_USER"] || "unknown"
  end

  private

  def fetch_from_aws_metadata
    # Implementation for AWS instance metadata
    nil
  end

  def fetch_from_sso
    # Implementation for SSO integration
    nil
  end
end

# config/environments/production.rb
config.console1984.username_resolver = MyApp::ConsoleUsernameResolver.new
```

--------------------------------

### Disable Session Incineration

Source: https://github.com/basecamp/console1984/blob/master/README.md

Set `config.console1984.incinerate` to `false` to completely disable the automatic incineration of sessions.

```ruby
config.console1984.incinerate = false
```

--------------------------------

### Access Decrypted Data

Source: https://github.com/basecamp/console1984/blob/master/README.md

After entering `decrypt!`, you can access and view the content of encrypted data fields.

```ruby
irb(main)> Topic.last.name
  Topic Load (1.2ms)  SELECT `topics`.* FROM `topics` ORDER BY `topics`.`id` DESC LIMIT 1
=> "Thanks for the inspiration"
```

--------------------------------

### Find Users with Sensitive Accesses

Source: https://context7.com/basecamp/console1984/llms.txt

Identifies users who have had one or more sessions involving sensitive data access. Counts sensitive sessions per user.

```ruby
users_with_sensitive = Console1984::User.joins(sessions: :sensitive_accesses).distinct
users_with_sensitive.each do |user|
  sensitive_count = user.sessions.joins(:sensitive_accesses).count
  puts "#{user.username}: #{sensitive_count} sensitive sessions"
end
```

--------------------------------

### Check if Session Can Be Incinerated

Source: https://context7.com/basecamp/console1984/llms.txt

Determines if a session has passed the configured retention period and can be safely incinerated.

```ruby
# Sessions can only be destroyed after incinerate_after period
session.created_at + Console1984.incinerate_after <= Time.now
```

--------------------------------

### Check if a Command was Sensitive

Source: https://context7.com/basecamp/console1984/llms.txt

Determines if a specific command was executed during a sensitive access. Also retrieves the justification if it was sensitive.

```ruby
command = Console1984::Command.last
command.sensitive?  # => true/false
command.sensitive_access&.justification  # => "https://support.example.com/tickets/12345"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.