console1984 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c81de72722b12e6a998fafaeba1d39b85532998751ef112b683413d6f0936cd
-  data.tar.gz: 734a353f1bf41d8dd2a6e55cf1e5c4f9163d5d0fc12f5ba77727c4ad221cc709
+  metadata.gz: 00c631a415150d26c5af9cc748900015818ca7eb78a1a958a4a92aeee572fc06
+  data.tar.gz: 05520effef693150b8a2cf1e17ab578038c1ddd02b99db4fdd5a97d54884ea36
 SHA512:
-  metadata.gz: 48fdc3a58ac26fafd4ee5137cddfb1f878a3abdcc8a6c230fdc8e6c6629eb936401c8f4dda7f7974983eba961c6249ebf68ce1abda00c702b3d874f760ffbac7
-  data.tar.gz: 3e13e25fe6af1380d39f566b345fcce7b25b73a7afa74368de2c49d8f329d55721a5f90e13740bdddc22079aba650d8429ecdba95fdde7287e3ed95d05d0fb73
+  metadata.gz: 974b06da4ce3b24d837bc9e4b7488014bde82fb7597ef5eff1c261ce155b430eb91948711404844714ac94a067c6bede7a808ff3c017a3feacd546a39790f244
+  data.tar.gz: a63cf7c90b42f1d8f2ce6df8f46e4867e0f081f7073d5696704271502527a6385a330fa7413cc11dae95d72e8c30a35fade40bf9d1c878109a55a14977bc3f4d

data/README.md

@@ -1,95 +1,86 @@
+![example workflow](https://github.com/basecamp/console1984/actions/workflows/build.yml/badge.svg)
+
 # Console1984
 
-A Rails Console that audits commands and protects users privacy.
+Console1984 is an extension for Rails consoles that protects sensitive accesses and makes them auditable.
 
-> “If you want to keep a secret, you must also hide it from yourself.”
-> 
-> ― George Orwell, 1984
+If you are looking for the auditing tool, check [`audits1984`](https://github.com/basecamp/audits1984).
 
-## Usage
+## Installation
 
-Add this line to your application's Gemfile:
+Add it to your `Gemfile`:
 
 ```ruby
 gem 'console1984'
 ```
 
-By default, `console1984` will only work in `production`. [You can configure other environments](#protected-environments). 
-
-## Features
-
-### Auditing
-
-The console will ask for a reason for the console session, identifying the user via the environment
-variable `CONSOLE_USER`.
-
-After that, every command the user types will be captured and logged. `console1984` uses
-[`rails-structured-logggin`](https://github.com/basecamp/rails-structured-logging) to form
-a JSON entry that looks like this:
-
-```json
-{
-  "@timestamp": "2020-05-15T15:05:45.845642+02:00",
-  "ecs": {
-    "version": "1.2.0"
-  },
-  "event": {
-    "action": "console.audit_trail",
-    "duration": {
-      "ms": 0.01
-    }
-  },
-  "console": {
-    "user": "Jorge",
-    "reason": "fix something",
-    "commands": "Account.first\n"
-  },
-  "rails": {
-    "application": "haystack",
-    "env": "beta"
-  },
-  "ruby": {
-    "allocations": {
-      "count": 0
-    }
-  },
-  "process": {
-    "pid": 8539,
-    "name": "rails_console",
-    "working_directory": "/Users/jorge/Work/basecamp/haystack"
-  },
-  "performance": {
-    "time": {
-      "cpu": {
-        "ms": 0.01
-      },
-      "idle": {
-        "ms": 0.0
-      }
-    }
-  },
-  "original": "  Account Load (1.0ms)  SELECT `accounts`.* FROM `accounts` ORDER BY `accounts`.`id` ASC LIMIT 1\n"
-}
+Create tables to store console activity in the database:
+
+```ruby
+rails console1984:install:migrations
+rails db:migrate
 ```
 
-## Configuration
+By default, console1984 is only enabled in `production`. You can configure the target environments in your `application.rb`:
 
-### Protected environments
+```ruby
+config.console1984.protected_environments = %i[ production staging ]
+```
 
-<a name="protected-environments"></a>
+## How it works
 
-By default, `console1984` will only be enabled in `production`. You can configure the target environments with
-`config.console1984.protected_environments`:
+### Session activity logging
 
-```ruby
-config.console1984.protected_environments = %i[ staging production ]
-```
+When starting a console session, it will ask for a reason. Internally, it will use this reason to document the console session and record all the commands executed in it.
+
+![console-session-reason](docs/images/console-session-reason.png)
+
+### Auditing sessions
+
+Check out [`audits1984`](https://github.com/basecamp/audits1984), a companion auditing tool prepared to work with `console1984` database session trails.
+
+### Access to encrypted data
+
+By default, `console1984` won't decrypt data encrypted with [Active Record encryption](https://edgeguides.rubyonrails.org/active_record_encryption.html).
+
+To decrypt data, enter the command `decrypt!`. It will ask for a justification, and these accesses will be flagged internally as sensitive.
+
+![console-session-reason](docs/images/console-decrypt.png)
 
-### Audit logger
+You can type `encrypt!` to go back to protected mode again.
 
-By default, the console will output JSON entries for audit trails to STDOUT. You can configure the
-used logger with `config.console1984.audit_logger`: 
+![console-session-reason](docs/images/console-encrypt.png)
+
+While in protected mode, you can't modify encrypted data, but can save unencrypted attributes normally. If you try to modify an encrypted column it will raise an error:
+
+![console-session-reason](docs/images/console-protect-urls.png)
+
+### Access to external systems
+
+While Active Record encryption can protect personal information in the database, are other systems can contain very sensitive information. For example: Elasticsearch indexing user information or Redis caching template fragments.
+
+To protect the access to such systems, you can add their URLs to `config.console1984.protected_urls` in the corresponding environment config file (e.g: `production.rb`):
 
 ```ruby
-config.console1984.audit_logger = ActiveSupport::Logger.new("log/console.txt")
+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" ]
 ```
+
+As with encryption data, running `decrypt!` will let you access these systems normally. The system will ask for a justfication and will flag those accesses as sensitive.
+
+This will work for systems that use Ruby sockets as the underlying communication mechanism.
+
+## Configuration
+
+These config options are namespaced in `config.console1984`:
+
+| Name                     | Description                                                  |
+| ------------------------ | ------------------------------------------------------------ |
+| `protected_environments` | The list of environments where `console1984` will act on. Defaults to `%i[ production ]` |
+| `protected_urls`         | The list of URLs corresponding with external systems to protect. |
+| `session_logger`         | The system used to record session data. The default logger is `Console1984::SessionsLogger::Database`. |
+| `username_resolver`      | Configure an object responsible of resolving the current database username. The default is `Console1984::Username::EnvResolver.new("CONSOLE_USER")`, which returns the value of the environment variable `CONSOLE_USER`. |
+
+## About built-in protection mechanisms
+
+`console1984` uses Ruby to add several protection mechanisms. However, because Ruby is highly dynamic, it's technically possible to circumvent most of these controls if you know what you are doing. We have made an effort to prevent such attempts, but if your organization needs bullet-proof protection against malicious actors using the console, you should consider additional security measures.
+

data/lib/console1984.rb

@@ -7,36 +7,14 @@ loader.setup
 module Console1984
   include Messages
 
-  mattr_accessor :supervisor
-  mattr_accessor :session_logger
-  mattr_accessor :username_resolver
-
-  mattr_accessor :protected_environments
-  mattr_reader :protected_urls, default: []
-
-  mattr_reader :production_data_warning, default: DEFAULT_PRODUCTION_DATA_WARNING
-  mattr_reader :enter_unprotected_encryption_mode_warning, default: DEFAULT_ENTER_UNPROTECTED_ENCRYPTION_MODE_WARNING
-  mattr_reader :enter_protected_mode_warning, default: DEFAULT_ENTER_PROTECTED_MODE_WARNING
-
-  mattr_accessor :incinerate, default: true
-  mattr_accessor :incinerate_after, default: 30.days
-  mattr_accessor :incineration_queue, default: "console1984_incineration"
-
-  mattr_accessor :debug, default: false
+  mattr_reader :supervisor, default: Supervisor.new
+  mattr_reader :config, default: Config.new
 
   thread_mattr_accessor :currently_protected_urls, default: []
 
   class << self
-    def install_support(config)
-      self.protected_environments ||= config.protected_environments
-      self.protected_urls.push(*config.protected_urls)
-      self.session_logger = config.session_logger || Console1984::SessionsLogger::Database.new
-      self.username_resolver = config.username_resolver || Console1984::Username::EnvResolver.new("CONSOLE_USER")
-
-      self.supervisor = Supervisor.new
-      self.protected_urls.freeze
-
-      extend_protected_systems
+    Config::PROPERTIES.each do |property|
+      delegate property, to: :config
     end
 
     def running_protected_environment?
@@ -50,31 +28,6 @@ module Console1984
     end
 
     private
-      def extend_protected_systems
-        extend_active_record
-        extend_socket_classes
-      end
-
-      def extend_active_record
-        %w[ActiveRecord::ConnectionAdapters::Mysql2Adapter ActiveRecord::ConnectionAdapters::PostgreSQLAdapter ActiveRecord::ConnectionAdapters::SQLite3Adapter].each do |class_string|
-          if Object.const_defined?(class_string)
-            klass = class_string.constantize
-            klass.prepend(Console1984::ProtectedAuditableTables)
-          end
-        end
-      end
-
-      def extend_socket_classes
-        socket_classes = [TCPSocket, OpenSSL::SSL::SSLSocket]
-        if defined?(Redis::Connection)
-          socket_classes.push(*[Redis::Connection::TCPSocket, Redis::Connection::SSLSocket])
-        end
-
-        socket_classes.compact.each do |socket_klass|
-          socket_klass.prepend Console1984::ProtectedTcpSocket
-        end
-      end
-
       def protecting_connections
         old_currently_protected_urls = self.currently_protected_urls
         self.currently_protected_urls = protected_urls

data/lib/console1984/commands.rb

@@ -11,4 +11,6 @@ module Console1984::Commands
     def supervisor
       Console1984.supervisor
     end
+
+    include Console1984::FrozenMethods
 end

data/lib/console1984/config.rb

@@ -0,0 +1,49 @@
+# Container for config options.
+class Console1984::Config
+  include Console1984::Messages
+
+  PROPERTIES = %i[
+    session_logger username_resolver
+    protected_environments protected_urls
+    production_data_warning enter_unprotected_encryption_mode_warning enter_protected_mode_warning
+    incinerate incinerate_after incineration_queue
+    debug freeze_config
+  ]
+
+  attr_accessor(*PROPERTIES)
+
+  def initialize
+    set_defaults
+  end
+
+  def set_from(properties)
+    properties.each do |key, value|
+      public_send("#{key}=", value) if value.present?
+    end
+  end
+
+  def freeze
+    super if freeze_config
+    protected_urls.freeze
+  end
+
+  private
+    def set_defaults
+      self.protected_environments = []
+      self.protected_urls = []
+
+      self.session_logger = Console1984::SessionsLogger::Database.new
+      self.username_resolver = Console1984::Username::EnvResolver.new("CONSOLE_USER")
+
+      self.production_data_warning = DEFAULT_PRODUCTION_DATA_WARNING
+      self.enter_unprotected_encryption_mode_warning = DEFAULT_ENTER_UNPROTECTED_ENCRYPTION_MODE_WARNING
+      self.enter_protected_mode_warning = DEFAULT_ENTER_PROTECTED_MODE_WARNING
+
+      self.incinerate = true
+      self.incinerate_after = 30.days
+      self.incineration_queue = "console1984_incineration"
+
+      self.debug = false
+      self.freeze_config = true
+    end
+end

data/lib/console1984/engine.rb

@@ -10,12 +10,13 @@ module Console1984
 
     initializer "console1984.config" do
       config.console1984.each do |key, value|
-        Console1984.send("#{key}=", value) unless %i[ protected_urls protected_environments ].include?(key.to_sym)
+        Console1984.config.send("#{key}=", value) unless %i[ protected_urls protected_environments ].include?(key.to_sym)
       end
     end
 
     console do
-      Console1984.install_support(config.console1984)
+      Console1984.config.set_from(config.console1984)
+
       Console1984.supervisor.start if Console1984.running_protected_environment?
 
       class OpenSSL::SSL::SSLSocket

data/lib/console1984/errors.rb

@@ -9,5 +9,6 @@ module Console1984
 
     class ForbiddenCommand < StandardError; end
     class ForbiddenIncineration < StandardError; end
+    class ForbiddenClassManipulation < StandardError; end
   end
 end

data/lib/console1984/frozen_methods.rb

@@ -0,0 +1,17 @@
+# Prevents adding new methods to classes.
+#
+# This prevents manipulating certain Console1984 classes
+# during a console session.
+module Console1984::FrozenMethods
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    def method_added(method_name)
+      raise Console1984::Errors::ForbiddenClassManipulation, "Can't override #{name}##{method_name}"
+    end
+
+    def singleton_method_added(method_name)
+      raise Console1984::Errors::ForbiddenClassManipulation, "Can't override #{name}.#{method_name}"
+    end
+  end
+end

data/lib/console1984/messages.rb

@@ -17,8 +17,7 @@ module Console1984::Messages
   TXT
 
   COMMANDS = {
-      "decrypt!": "enter unprotected mode with access to encrypted information",
-      "log '<reason>'": "provide further information about what you are going to do in the middle of a console session"
+      "decrypt!": "enter unprotected mode with access to encrypted information"
   }
 
   COMMANDS_HELP = <<~TXT

data/lib/console1984/protected_auditable_tables.rb

@@ -1,4 +1,5 @@
 module Console1984
+  # Prevents accessing trail model tables when executing console commands.
   module ProtectedAuditableTables
     %i[ execute exec_query exec_insert exec_delete exec_update exec_insert_all ].each do |method|
       define_method method do |*args|
@@ -23,4 +24,6 @@ module Console1984
         @auditable_tables ||= AUDITABLE_MODELS.collect(&:table_name)
       end
   end
+
+  include Console1984::FrozenMethods
 end

data/lib/console1984/protected_context.rb

@@ -1,15 +1,18 @@
 module Console1984::ProtectedContext
-  # Protect the code to show inspected objects too. This method is invoked
-  # for showing returned objects in the console
+  # This method is invoked for showing returned objects in the console
+  # Overridden to make sure their evaluation is supervised.
   def inspect_last_value
     Console1984.supervisor.execute do
       super
     end
   end
 
+  #
   def evaluate(line, line_no, exception: nil)
     Console1984.supervisor.execute_supervised(Array(line)) do
       super
     end
   end
+
+  include Console1984::FrozenMethods
 end

data/lib/console1984/protected_tcp_socket.rb

@@ -1,3 +1,4 @@
+# Wraps socket methods to execute supervised.
 module Console1984::ProtectedTcpSocket
   def write(*args)
     protecting do
@@ -53,4 +54,6 @@ module Console1984::ProtectedTcpSocket
         super(addrinfo.ip_address, addrinfo.ip_port)
       end
     end
+
+    include Console1984::FrozenMethods
 end

data/lib/console1984/sessions_logger/database.rb

@@ -1,3 +1,4 @@
+# A session logger that saves audit trails in the database.
 class Console1984::SessionsLogger::Database
   attr_reader :current_session, :current_sensitive_access
 

data/lib/console1984/supervisor.rb

@@ -1,48 +1,47 @@
 require 'colorized_string'
 require 'rails/console/app'
 
+# Protects console sessions and executes code in supervised mode.
 class Console1984::Supervisor
-  include Accesses, InputOutput, Executor
-
-  attr_reader :session_id
-  delegate :session_logger, :username_resolver, to: Console1984
-
-  def initialize
-    disable_access_to_encrypted_content(silent: true)
-  end
+  include Accesses, InputOutput, Executor, Protector
 
+  # Starts a console session extending IRB and several systems to inject
+  # the protection logic, and notifies the session logger to record the
+  # session.
   def start
-    show_production_data_warning
-    show_commands
+    Console1984.config.freeze
+    extend_protected_systems
+    disable_access_to_encrypted_content(silent: true)
 
-    extend_irb
+    show_welcome_message
 
-    session_logger.start_session current_username, ask_for_session_reason
+    start_session
   end
 
   def stop
-    session_logger.finish_session
+    stop_session
   end
 
   private
-    def current_username
-      username_resolver.current
+    def start_session
+      session_logger.start_session current_username, ask_for_session_reason
     end
 
-    def show_production_data_warning
-      show_warning Console1984.production_data_warning
+    def stop_session
+      session_logger.finish_session
     end
 
-    def extend_irb
-      IRB::Context.prepend(Console1984::ProtectedContext)
-      Rails::ConsoleMethods.include(Console1984::Commands)
+    def session_logger
+      Console1984.session_logger
     end
 
-    def ask_for_session_reason
-      ask_for_value("#{current_username}, why are you using this console today?")
+    def current_username
+      Console1984.username_resolver.current
     end
 
-    def show_commands
-      puts COMMANDS_HELP
+    def username_resolver
+      Console1984.username_resolver
     end
+
+    include Console1984::FrozenMethods
 end

data/lib/console1984/supervisor/executor.rb

@@ -4,7 +4,7 @@ module Console1984::Supervisor::Executor
   def execute_supervised(commands, &block)
     run_system_command { session_logger.before_executing commands }
     execute(&block)
-  rescue Console1984::Errors::ForbiddenCommand
+  rescue Console1984::Errors::ForbiddenCommand, Console1984::Errors::ForbiddenClassManipulation
     puts "Forbidden command attempted: #{commands.join("\n")}"
     run_system_command { session_logger.suspicious_commands_attempted commands }
     nil

data/lib/console1984/supervisor/input_output.rb

@@ -1,11 +1,31 @@
 module Console1984::Supervisor::InputOutput
-  def show_warning(message)
-    puts ColorizedString.new("\n#{message}\n").yellow
-  end
-
-  def ask_for_value(message)
-    puts ColorizedString.new("#{message}").green
-    reason = $stdin.gets.strip until reason.present?
-    reason
-  end
+  include Console1984::Messages
+
+  private
+    def show_welcome_message
+      show_production_data_warning
+      show_commands
+    end
+
+    def show_production_data_warning
+      show_warning Console1984.production_data_warning
+    end
+
+    def ask_for_session_reason
+      ask_for_value("#{current_username}, why are you using this console today?")
+    end
+
+    def show_commands
+      puts COMMANDS_HELP
+    end
+
+    def show_warning(message)
+      puts ColorizedString.new("\n#{message}\n").yellow
+    end
+
+    def ask_for_value(message)
+      puts ColorizedString.new("#{message}").green
+      reason = $stdin.gets.strip until reason.present?
+      reason
+    end
 end

data/lib/console1984/supervisor/protector.rb

@@ -0,0 +1,37 @@
+module Console1984::Supervisor::Protector
+  extend ActiveSupport::Concern
+
+  private
+    def extend_protected_systems
+      extend_irb
+      extend_active_record
+      extend_socket_classes
+    end
+
+    def extend_irb
+      IRB::Context.prepend(Console1984::ProtectedContext)
+      Rails::ConsoleMethods.include(Console1984::Commands)
+    end
+
+    ACTIVE_RECORD_CONNECTION_ADAPTERS = %w[ActiveRecord::ConnectionAdapters::Mysql2Adapter ActiveRecord::ConnectionAdapters::PostgreSQLAdapter ActiveRecord::ConnectionAdapters::SQLite3Adapter]
+
+    def extend_active_record
+      ACTIVE_RECORD_CONNECTION_ADAPTERS.each do |class_string|
+        if Object.const_defined?(class_string)
+          klass = class_string.constantize
+          klass.prepend(Console1984::ProtectedAuditableTables)
+        end
+      end
+    end
+
+    def extend_socket_classes
+      socket_classes = [TCPSocket, OpenSSL::SSL::SSLSocket]
+      if defined?(Redis::Connection)
+        socket_classes.push(*[Redis::Connection::TCPSocket, Redis::Connection::SSLSocket])
+      end
+
+      socket_classes.compact.each do |socket_klass|
+        socket_klass.prepend Console1984::ProtectedTcpSocket
+      end
+    end
+end

data/lib/console1984/username/env_resolver.rb

@@ -1,3 +1,5 @@
+# A username resolver that returns the value of a given
+# environment variable.
 class Console1984::Username::EnvResolver
   def initialize(key)
     @key = key

data/lib/console1984/version.rb

@@ -1,3 +1,3 @@
 module Console1984
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: console1984
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Jorge Manrubia
@@ -94,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rubocop-rails
   requirement: !ruby/object:Gem::Requirement
@@ -143,9 +157,10 @@ files:
 - db/migrate/20210517203931_create_console1984_tables.rb
 - lib/console1984.rb
 - lib/console1984/commands.rb
+- lib/console1984/config.rb
 - lib/console1984/engine.rb
-- lib/console1984/env_variable_username.rb
 - lib/console1984/errors.rb
+- lib/console1984/frozen_methods.rb
 - lib/console1984/messages.rb
 - lib/console1984/protected_auditable_tables.rb
 - lib/console1984/protected_context.rb
@@ -157,6 +172,7 @@ files:
 - lib/console1984/supervisor/accesses/unprotected.rb
 - lib/console1984/supervisor/executor.rb
 - lib/console1984/supervisor/input_output.rb
+- lib/console1984/supervisor/protector.rb
 - lib/console1984/username/env_resolver.rb
 - lib/console1984/version.rb
 - test/fixtures/console1984/commands.yml

data/lib/console1984/env_variable_username.rb

@@ -1,9 +0,0 @@
-class Console1984::EnvVariableUsername
-  def initialize(key)
-    @username = ENV[key]
-  end
-
-  def current_user_name
-    @username
-  end
-end