console1984 0.1.4 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39d8147e2b8b8fa0a20c6aec1422a28633afe80567bac0ac0c98a7d6096ae430
-  data.tar.gz: 760d761d4ced82752b89aa7bd1de44416d545a75bdb0f4266165718100d8a7a5
+  metadata.gz: bc64d037f2de5570292e0b09710b4543a68ba1af12759150cc68e7b7f4dd6e16
+  data.tar.gz: c5929af5061393a32c4df38022535d53c62aaaabe951727798e340322fb0d950
 SHA512:
-  metadata.gz: 3eedbf3cc3436469edd615b397af1c5ad03195f7f1eebfcc1ed6da859a90e0fc213327f8d487841640ddec8c4d39ed1562239e9dda10360a622f59aa809b6f9a
-  data.tar.gz: bdd11a8580f29fd700c954c486e01dc1f8189e452565f37b281d9ee96b78bd375c2f02728df3c4ce405c047fc9fe52b5eac8b5b90a62519bfeaff4aa1465a5d9
+  metadata.gz: b64f422bcdd421e7a874af965c9ee615f6d873e0d2a685d68667216fd1ee91d4e8e4815d4dd9e78ef7838a75763fb898be1f328c8466a137f1782a4121531da6
+  data.tar.gz: ce7e1f60bfdb666abe3c85a02ddaa1ac25344c994a1471ec64d07cd15f8aac5735bcd0608497e71d9813cf111cdb76f414a2373eb8dbef14b983757ba3876812

data/README.md

@@ -10,10 +10,12 @@ A Rails console extension that protects sensitive accesses and makes them audita
 
 If you are looking for the auditing tool, check [`audits1984`](https://github.com/basecamp/audits1984).
 
-![console-session-reason](docs/images/console-session-reason.png)
+![Terminal screenshot showing console1984 asking for a reason for the session](docs/images/console-session-reason.png)
 
 ## Installation
 
+**Important:** `console1984` depends on [Active Record encryption](https://edgeguides.rubyonrails.org/active_record_encryption.html) which is a Rails 7 feature. Since no gem for Rails 7 has been released yet, you need to run Rails edge in your project (point the gem to latest `main` in the [repo](https://github.com/rails/rails)).
+
 Add it to your `Gemfile`:
 
 ```ruby
@@ -69,7 +71,7 @@ To decrypt data, enter the command `decrypt!`. It will ask for a justification,
 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):002:0> decrypt!
+irb(main)> decrypt!
 ```
 
 ```
@@ -104,15 +106,11 @@ irb(main)> Topic.last.name
 => "{\"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==\"}}"
 ```
 
-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:
-
-```ruby
-irb(main)> Rails.cache.read("some key") # raises Console1984::Errors::ProtectedConnection
-```
+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.
 
 ### 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.
+While Active Record encryption can protect personal information in the database, there 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`):
 
@@ -120,7 +118,13 @@ To protect the access to such systems, you can add their URLs to `config.console
 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.
+In the default protected mode, trying to read data from a protected system will be aborted with an error:
+
+```ruby
+irb(main)> Rails.cache.read("some key") # raises Console1984::Errors::ProtectedConnection
+```
+
+Running `decrypt!` will switch you to unprotected mode and 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.
 
@@ -128,6 +132,10 @@ This will work for systems that use Ruby sockets as the underlying communication
 
 By default, sessions will be incinerated with a job 30 days after they are created. You can configure this period by setting `config.console1984.incinerate_after = 1.year` and you can disable incineration completely by setting `config.console1984.incinerate = false`.
 
+### Eager loading
+
+When starting a console session, `console1984` will eager load all the application classes if necessary. In practice, production environments already load classes eagerly, so this won't represent any change for those.  
+
 ## Configuration
 
 These config options are namespaced in `config.console1984`:
@@ -137,7 +145,7 @@ These config options are namespaced in `config.console1984`:
 | `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`. |
+| `username_resolver`                         | Configure how the current user is determined for a given console session. The default is `Console1984::Username::EnvResolver.new("CONSOLE_USER")`, which returns the value of the environment variable `CONSOLE_USER`. |
 | `production_data_warning`                   | The text to show when a console session starts.              |
 | `enter_unprotected_encryption_mode_warning` | The text to show when user enters into unprotected mode.     |
 | `enter_protected_mode_warning`              | The text to show when user go backs to protected mode.       |
@@ -149,3 +157,17 @@ These config options are namespaced in `config.console1984`:
 
 `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.
 
+The current version includes protection mechanisms to avoid tampering the tables that store console sessions. A bullet-proof mechanism would be using a read only connection when user commands are evaluated. Implementing such scheme is possible by writing a custom session logger and leveraging Rails' multi-database support. We would like that future versions of `console1984` supported this scheme directly as a configuration option.
+
+## Running the test suite
+
+The test suite runs against SQLite by default, but can be run against Postgres and MySQL too. It will run against the three in the CI server.
+
+To run the suite in your computer, first, run `bin/setup` to create the docker containers for MySQL/PostgreSQL and create the databases. Then run:
+
+```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  
+```

data/config/protections.yml

@@ -0,0 +1,30 @@
+static_validations:
+  forbidden_reopening:
+    - ActiveRecord
+    - Console1984
+    - PG
+    - Mysql2
+  forbidden_constant_reference:
+    always:
+      - Console1984
+    protected:
+      - PG
+      - Mysql2
+      - ActiveRecord::ActiveRecordEncryption
+  suspicious_terms:
+    - console_1984
+    - Console1984
+    - secret
+    - credentials
+forbidden_methods:
+  always:
+  user:
+    Kernel:
+      - eval
+    Object:
+      - eval
+    BasicObject:
+      - eval
+      - instance_eval
+    Module:
+      - class_eval

data/lib/console1984/command_executor.rb

@@ -0,0 +1,90 @@
+# Supervise execution of console commands:
+#
+# * It will {validate commands}[rdoc-ref:Console1984::CommandValidator] before running
+#   them.
+# * It will execute the commands in {protected mode}[rdoc-ref:Console1984::Shield#with_protected_mode]
+#   if needed.
+# * It will log the command execution, and flag suspicious attempts and forbidden commands
+#   appropriately.
+class Console1984::CommandExecutor
+  include Console1984::Freezeable
+
+  delegate :username_resolver, :session_logger, :shield, to: Console1984
+
+  # Logs and validates +commands+, and executes the passed block in a protected environment.
+  #
+  # Suspicious commands will be executed but flagged as suspicious. Forbidden commands will
+  # be prevented and flagged too.
+  def execute(commands, &block)
+    run_as_system { session_logger.before_executing commands }
+    validate_command commands
+    execute_in_protected_mode(&block)
+  rescue Console1984::Errors::ForbiddenCommand, FrozenError => e
+    flag_suspicious(commands)
+  rescue Console1984::Errors::SuspiciousCommand
+    flag_suspicious(commands)
+    execute_in_protected_mode(&block)
+  ensure
+    run_as_system { session_logger.after_executing commands }
+  end
+
+  # Executes the passed block in protected mode.
+  #
+  # See Console1984::Shield::Modes.
+  def execute_in_protected_mode(&block)
+    run_as_user do
+      shield.with_protected_mode(&block)
+    end
+  end
+
+  # Executes the passed block as a user.
+  #
+  # While the block is being executed, #executing_user_command? will return true.
+  # This method helps implementing certain protection mechanisms that should only act with
+  # user commands.
+  def run_as_user(&block)
+    run_command true, &block
+  end
+
+  # Executes the passed block as the system.
+  #
+  # While the block is being executed, #executing_user_command? will return false.
+  def run_as_system(&block)
+    run_command false, &block
+  end
+
+  # Returns whether the system is currently executing a user command.
+  def executing_user_command?
+    @executing_user_command
+  end
+
+  # Validates the command.
+  #
+  # See Console1984::CommandValidator.
+  def validate_command(command)
+    command_validator.validate(command)
+  end
+
+  private
+    def command_validator
+      @command_validator ||= build_command_validator
+    end
+
+    def build_command_validator
+      Console1984::CommandValidator.from_config(Console1984.protections_config.static_validations)
+    end
+
+    def flag_suspicious(commands)
+      puts "Forbidden command attempted: #{commands.join("\n")}"
+      run_as_system { session_logger.suspicious_commands_attempted commands }
+      nil
+    end
+
+    def run_command(run_by_user, &block)
+      original_value = @executing_user_command
+      @executing_user_command = run_by_user
+      block.call
+    ensure
+      @executing_user_command = original_value
+    end
+end

data/lib/console1984/command_validator/forbidden_constant_reference_validation.rb

@@ -0,0 +1,31 @@
+# Validates references to a configured set of constants.
+class Console1984::CommandValidator::ForbiddenConstantReferenceValidation
+  include Console1984::Freezeable
+
+  # +config+ will be a hash like:
+  #
+  #    { always: [ Console1984 ], protected: [ PG, Mysql2 ] }
+  def initialize(shield = Console1984.shield, config)
+    # We make shield an injectable dependency for testing purposes. Everything is frozen
+    # for security purposes, so stubbing won't work.
+    @shield = shield
+
+    @forbidden_constants_names = config[:always] || []
+    @constant_names_forbidden_in_protected_mode = config[:protected] || []
+  end
+
+  # Raises a Console1984::Errors::ForbiddenCommand if a banned constant is referenced.
+  def validate(parsed_command)
+    if contains_invalid_const_reference?(parsed_command, @forbidden_constants_names) ||
+      (@shield.protected_mode? && contains_invalid_const_reference?(parsed_command, @constant_names_forbidden_in_protected_mode))
+      raise Console1984::Errors::ForbiddenCommand
+    end
+  end
+
+  private
+    def contains_invalid_const_reference?(parsed_command, banned_constants)
+      (parsed_command.constants + parsed_command.constant_assignments).find do |constant_name|
+        banned_constants.find { |banned_constant| "#{constant_name}::".start_with?("#{banned_constant}::") }
+      end
+    end
+end

data/lib/console1984/command_validator/forbidden_reopening_validation.rb

@@ -0,0 +1,29 @@
+# Validates attempts to reopen classes and modules based on a configured set.
+class Console1984::CommandValidator::ForbiddenReopeningValidation
+  include Console1984::Freezeable
+
+  attr_reader :banned_class_or_module_names
+
+  def initialize(banned_classes_or_modules)
+    @banned_class_or_module_names = banned_classes_or_modules.collect(&:to_s)
+  end
+
+  # Raises a Console1984::Errors::ForbiddenCommand if an banned class or module reopening
+  # is detected.
+  def validate(parsed_command)
+    if contains_invalid_class_or_module_declaration?(parsed_command)
+      raise Console1984::Errors::ForbiddenCommand
+    end
+  end
+
+  private
+    def contains_invalid_class_or_module_declaration?(parsed_command)
+      (parsed_command.declared_classes_or_modules + parsed_command.constant_assignments).find { |class_or_module_name| banned?(class_or_module_name) }
+    end
+
+    def banned?(class_or_module_name)
+      @banned_class_or_module_names.find do |banned_class_or_module_name|
+        "#{class_or_module_name}::".start_with?("#{banned_class_or_module_name}::")
+      end
+    end
+end

data/lib/console1984/command_validator/parsed_command.rb

@@ -0,0 +1,90 @@
+# Parses a command string and exposes different constructs to be used by validations.
+#
+# Internally, it uses the {parser}[https://github.com/whitequark/parser] gem to perform the parsing.
+class Console1984::CommandValidator::ParsedCommand
+  include Console1984::Freezeable
+
+  attr_reader :raw_command
+
+  delegate :declared_classes_or_modules, :constants, :constant_assignments, to: :processed_ast
+
+  def initialize(raw_command)
+    @raw_command = Array(raw_command).join("\n")
+  end
+
+  private
+    def processed_ast
+      @processed_ast ||= CommandProcessor.new.tap do |processor|
+        ast = Parser::CurrentRuby.parse(raw_command)
+        processor.process(ast)
+      rescue Parser::SyntaxError
+        # Fail open with syntax errors
+      end
+    end
+
+    class CommandProcessor < ::Parser::AST::Processor
+      include AST::Processor::Mixin
+      include Console1984::Freezeable
+
+      def initialize
+        @constants = []
+        @declared_classes_or_modules = []
+        @constant_assignments = []
+      end
+
+      # We define accessors to define lists without duplicates. We are not using a +SortedSet+ because we want
+      # to mutate strings in the list while the processing is happening. And we don't use metapgroamming to define the
+      # accessors to prevent having problems with freezable and its instance_variable* protection.
+
+      def constants
+        @constants.uniq
+      end
+
+      def declared_classes_or_modules
+        @declared_classes_or_modules.uniq
+      end
+
+      def constant_assignments
+        @constant_assignments.uniq
+      end
+
+      def on_class(node)
+        super
+        const_declaration, _, _ = *node
+        constant = extract_constants(const_declaration).first
+        @declared_classes_or_modules << constant if constant.present?
+      end
+
+      alias_method :on_module, :on_class
+
+      def on_const(node)
+        super
+        name, const_name = *node
+        const_name = const_name.to_s
+        last_constant = @constants.last
+
+        if name.nil? || (name && name.type == :cbase) # cbase = leading ::
+          if last_constant&.end_with?("::")
+            last_constant << const_name
+          else
+            @constants << const_name
+          end
+        elsif last_constant
+          last_constant << "::#{const_name}"
+        end
+      end
+
+      def on_casgn(node)
+        super
+        scope_node, name, value_node = *node
+        @constant_assignments.push(*extract_constants(value_node))
+      end
+
+      private
+        def extract_constants(node)
+          self.class.new.tap do |processor|
+            processor.process(node)
+          end.constants
+        end
+    end
+end

data/lib/console1984/command_validator/suspicious_terms_validation.rb

@@ -0,0 +1,22 @@
+# Validates that the command doesn't include a term based on a configured list.
+class Console1984::CommandValidator::SuspiciousTermsValidation
+  include Console1984::Freezeable
+
+  def initialize(suspicious_terms)
+    @suspicious_terms = suspicious_terms
+  end
+
+  # Raises a Console1984::Errors::SuspiciousCommand if the term is referenced.
+  def validate(parsed_command)
+    if contains_suspicious_term?(parsed_command)
+      raise Console1984::Errors::SuspiciousCommand
+    end
+  end
+
+  private
+    def contains_suspicious_term?(parsed_command)
+      @suspicious_terms.find do |term|
+        parsed_command.raw_command.include?(term)
+      end
+    end
+end

data/lib/console1984/command_validator.rb

@@ -0,0 +1,71 @@
+# Validates console commands.
+#
+# This performs an static analysis of console commands. The analysis is meant to happen
+# *before* commands are executed, so that they can prevent the execution if needed.
+#
+# The validation itself happens as a chain of validation objects. The system will invoke
+# each validation in order. Validations will raise an error if the validation fails (typically
+# a Console1984::Errors::ForbiddenCommand or Console1984::Errors::SuspiciousCommands).
+#
+# Internally, validations will receive a Console1984::CommandValidator::ParsedCommand object. This
+# exposes parsed constructs in addition to the raw strings so that validations can use those.
+#
+# There is a convenience method .from_config that lets you instantiate a validation setup from
+# a config hash (e.g to customize validations via YAML).
+#
+# See +config/command_protections.yml+ and the validations in +lib/console1984/command_validator+.
+class Console1984::CommandValidator
+  include Console1984::Freezeable
+
+  def initialize
+    @validations_by_name = HashWithIndifferentAccess.new
+  end
+
+  class << self
+    # Instantiates a command validator that will configure the validations based on the config passed.
+    #
+    # For each key in +config+, it will derive the class Console1984::CommandValidator::#{key.camelize}Validation
+    # and will instantiate the validation passed the values as params.
+    #
+    # For example for this config:
+    #
+    #    { forbidden_reopening: [ActiveRecord, Console1984] }
+    #
+    # It will instantiate Console1984::CommandValidator::ForbiddenReopeningValidation passing
+    # +["ActiveRecord", "Console1984"]+ in the constructor.
+    #
+    # # See +config/command_protections.yml+ as an example.
+    def from_config(config)
+      Console1984::CommandValidator.new.tap do |validator|
+        config.each do |validator_name, validator_config|
+          validator_class = "Console1984::CommandValidator::#{validator_name.to_s.camelize}Validation".constantize
+          validator_config.try(:symbolize_keys!)
+          validator.add_validation validator_name, validator_class.new(validator_config)
+        end
+      end
+    end
+  end
+
+  # Adds a +validation+ to the chain indexed by the provided +name+
+  #
+  # Validations are executed in the order they are added.
+  def add_validation(name, validation)
+    validations_by_name[name] = validation
+  end
+
+  # Executes the chain of validations passing a {parsed command}[rdoc-ref:Console1984::CommandValidator::ParsedCommand]
+  # created with the +command+ string passed by parameter.
+  #
+  # The validations are executed in the order they were added. If one validation raises an error, the error will
+  # raise and the rest of validations won't get checked.
+  def validate(command)
+    parsed_command = ParsedCommand.new(command)
+
+    validations_by_name.values.each do |validation|
+      validation.validate(parsed_command)
+    end
+  end
+
+  private
+    attr_reader :validations_by_name
+end