console1984 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a76f26ca8567b7261e2062a9360216ebca2c230ffb48e4ecb5e5a9970339e99
-  data.tar.gz: 6a892b894d3274e9567a4fd763d9121690b889b89e7a2e7a2b9f919825e51144
+  metadata.gz: 498f37bd3803f7f76e073d91f51e2dc69fc8a00fc575392c3869b2ae4d65d9bf
+  data.tar.gz: 1675df589a603042a54e6de8b835e4434f5a112158521379553e9875b25c9eeb
 SHA512:
-  metadata.gz: 125c2457aca08f4f1476db595f465a85c1b2d9dfa22634502b398456aeb0816436563372a42a1c2182a731a87b7c8552bb4429b775bd2b6f320fbc86bd74d5b3
-  data.tar.gz: bd3ed3832febd22d4f6038ee8e3bf2db7471f9bbc62a77bb8934ee0904681050b072b67c12d8bccac3b2eebc8e52c8f06f06c32cf0407be6fb9f0008248f0834
+  metadata.gz: aa0edb371ac31cd2b87e1b8ddb833482516bed91ff3a5c85c12c10c2206ce7dbe8aba514a6a3aecc2e5d594eee527db78b270cd0789484960c7c98e55ca504aa
+  data.tar.gz: bc595388d7ca433c22a1ccc17a5bb28759cc0b0dd8b5267a061456ad0e17de58be0f95a129689e7fbe88915c709af82d0efd70a3f410f4b40cb0f7e767fa7cb6

data/README.md

@@ -155,4 +155,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 definitive mechanism to do this 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.
+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/command_protections.yml

@@ -0,0 +1,17 @@
+forbidden_reopening:
+  - ActiveRecord
+  - Console1984
+  - PG
+  - Mysql2
+forbidden_constant_reference:
+  always:
+    - Console1984
+  protected:
+    - PG
+    - Mysql2
+    - ActiveRecord::ActiveRecordEncryption
+suspicious_terms:
+  - console_1984
+  - Console1984
+  - secret
+  - credentials

data/lib/console1984/command_executor.rb

@@ -0,0 +1,94 @@
+# 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
+    flag_suspicious(commands)
+  rescue Console1984::Errors::SuspiciousCommand
+    flag_suspicious(commands)
+    execute_in_protected_mode(&block)
+  rescue FrozenError
+    flag_suspicious(commands)
+  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
+    COMMAND_VALIDATOR_CONFIG_FILE_PATH = Console1984::Engine.root.join("config/command_protections.yml")
+
+    def command_validator
+      @command_validator ||= build_command_validator
+    end
+
+    def build_command_validator
+      Console1984::CommandValidator.from_config(YAML.safe_load(File.read(COMMAND_VALIDATOR_CONFIG_FILE_PATH)).symbolize_keys)
+    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.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.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,64 @@
+# 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, 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
+
+      attr_reader :constants, :declared_classes_or_modules
+
+      def initialize
+        @constants = []
+        @declared_classes_or_modules = []
+      end
+
+      def on_class(node)
+        super
+        const_declaration, _, _ = *node
+
+        processor = self.class.new
+        processor.process(const_declaration)
+        @declared_classes_or_modules << processor.constants.first if processor.constants.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
+    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

data/lib/console1984/config.rb

@@ -1,9 +1,11 @@
 # Container for config options.
+#
+# These config options are accessible via first-level reader methods at Console1984.
 class Console1984::Config
   include Console1984::Freezeable, Console1984::Messages
 
   PROPERTIES = %i[
-    session_logger username_resolver
+    session_logger username_resolver shield command_executor
     protected_environments protected_urls
     production_data_warning enter_unprotected_encryption_mode_warning enter_protected_mode_warning
     incinerate incinerate_after incineration_queue
@@ -24,16 +26,18 @@ class Console1984::Config
 
   def freeze
     super
-    protected_urls.freeze
+    [ protected_urls ].each(&: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.shield = Console1984::Shield.new
+      self.command_executor = Console1984::CommandExecutor.new
+
+      self.protected_environments = []
+      self.protected_urls = []
 
       self.production_data_warning = DEFAULT_PRODUCTION_DATA_WARNING
       self.enter_unprotected_encryption_mode_warning = DEFAULT_ENTER_UNPROTECTED_ENCRYPTION_MODE_WARNING

data/lib/console1984/engine.rb

@@ -14,6 +14,8 @@ module Console1984
       end
     end
 
+    # Console 1984 setup happens when a console is started. Just including the
+    # gem won't install any protection mechanisms.
     console do
       Console1984.config.set_from(config.console1984)
 

data/lib/console1984/errors.rb

@@ -1,5 +1,6 @@
 module Console1984
   module Errors
+    # Attempt to access a protected url while in protected mode.
     class ProtectedConnection < StandardError
       def initialize(details)
         super "A connection attempt was prevented because it represents a sensitive access."\
@@ -7,8 +8,16 @@ module Console1984
       end
     end
 
+    # Attempt to execute a command that is not allowed. The system won't
+    # execute such commands and will flag them as sensitive.
     class ForbiddenCommand < StandardError; end
+
+    # A suspicious command was executed. The command will be flagged but the system
+    # will let it run.
+    class SuspiciousCommand < StandardError; end
+
+    # Attempt to incinerate a session ahead of time as determined by
+    # +config.console1984.incinerate_after+.
     class ForbiddenIncineration < StandardError; end
-    class ForbiddenCodeManipulation < StandardError; end
   end
 end

data/lib/console1984/{protected_auditable_tables.rb → ext/active_record/protected_auditable_tables.rb}

@@ -1,11 +1,11 @@
 # Prevents accessing trail model tables when executing console commands.
-module Console1984::ProtectedAuditableTables
+module Console1984::Ext::ActiveRecord::ProtectedAuditableTables
   include Console1984::Freezeable
 
   %i[ execute exec_query exec_insert exec_delete exec_update exec_insert_all ].each do |method|
     define_method method do |*args, **kwargs|
       sql = args.first
-      if Console1984.supervisor.executing_user_command? && sql =~ auditable_tables_regexp
+      if Console1984.command_executor.executing_user_command? && sql =~ auditable_tables_regexp
         raise Console1984::Errors::ForbiddenCommand, "#{sql}"
       else
         super(*args, **kwargs)
@@ -25,6 +25,4 @@ module Console1984::ProtectedAuditableTables
     def auditable_models
       @auditable_models ||= Console1984::Base.descendants
     end
-
-    include Console1984::Freezeable
 end