safe_bro 0.1.0

data/lib/safe_bro/errors.rb

@@ -0,0 +1,41 @@
+module SafeBro
+  class Error < StandardError; end
+
+  # Setup problems that stop a console from starting (fail closed).
+  class MissingUsername < Error
+    def initialize(msg = "SafeBro needs to know who you are. Set CONSOLE_USER (e.g. via SSH SetEnv), or enable config.ask_for_username_if_empty.")
+      super
+    end
+  end
+
+  class MissingReason < Error
+    def initialize(msg = "SafeBro needs a reason for this session. Set CONSOLE_REASON when there is no terminal to ask on.")
+      super
+    end
+  end
+
+  class NotInteractive < Error
+    def initialize(msg = "This needs an interactive terminal.")
+      super
+    end
+  end
+
+  # Raised when a console command is not allowed. The command is not executed.
+  class ForbiddenCommand < Error; end
+
+  # Raised when a command tries to change SafeBro's own audit trail.
+  class TamperingAttempt < ForbiddenCommand; end
+
+  # Raised when a command touches a protected resource while the console is locked.
+  class ProtectedResource < ForbiddenCommand
+    attr_reader :resource
+
+    def initialize(resource, detail = nil)
+      @resource = resource
+      super([ "Access to #{resource} is protected.", detail, "Run unlock! to get access (you will be asked why)." ].compact.join(" "))
+    end
+  end
+
+  # Not blocked, but recorded as suspicious.
+  class SuspiciousCommand < Error; end
+end

data/lib/safe_bro/executor.rb

@@ -0,0 +1,100 @@
+module SafeBro
+  # Supervises every command typed into the console:
+  #
+  # * records it (before it runs, so a crash can't hide it)
+  # * validates it, blocking forbidden commands and flagging suspicious ones
+  # * runs it with the shield's protections on
+  # * flags attempts to reach protected resources that happen while it runs
+  class Executor
+    # console_path: the file name IRB gives the code it evaluates, e.g. "(irb)" or "(myapp)" (Rails
+    # names it after the app). It is how we tell typed code from library code.
+    def execute(commands, console_path: nil, &block)
+      @console_path = console_path if console_path
+      statements = Array(commands)
+      command = run_as_system { SafeBro.recorder.record_command(statements) }
+
+      if (suspicion = validate(command, statements))
+        flag(command, :suspicious, suspicion.message)
+      end
+
+      begin
+        execute_in_protected_mode(&block)
+      rescue ProtectedResource, ForbiddenCommand => error
+        flag(command, error.is_a?(ProtectedResource) ? :suspicious : :blocked, error.message)
+        raise masked(error)
+      rescue FrozenError => error
+        # Someone tried to alter a frozen SafeBro class.
+        flag(command, :blocked, "Attempt to modify protected code: #{error.message}")
+        raise masked(error)
+      rescue => error
+        raise masked(error)
+      end
+    end
+
+    # Runs the block with the shield's protections on. The mode itself decides what is
+    # protected, depending on what is currently unlocked.
+    def execute_in_protected_mode(&block)
+      run_as_user { SafeBro.shield.protect(&block) }
+    end
+
+    def run_as_user(&block)
+      run_command(true, &block)
+    end
+
+    def run_as_system(&block)
+      run_command(false, &block)
+    end
+
+    def executing_user_command?
+      @executing_user_command == true
+    end
+
+    # Was this method called straight from what the person typed (as opposed to from library code)?
+    # IRB evaluates input under a fixed file name, and C-implemented methods like send or
+    # instance_eval don't add frames, so the caller location is still the console.
+    def from_console?(locations)
+      executing_user_command? && locations.first&.path.to_s == (@console_path || "(irb)")
+    end
+
+    private
+      # Returns a suspicion (command still runs) or raises ForbiddenCommand (it doesn't).
+      def validate(command, statements)
+        run_as_system { SafeBro.validator.validate(statements, locked: SafeBro.shield.locked?) }
+        nil
+      rescue SuspiciousCommand => suspicion
+        suspicion
+      rescue ForbiddenCommand => error
+        flag(command, :blocked, error.message)
+        raise masked(error)
+      end
+
+      def flag(command, status, reason)
+        run_as_system { SafeBro.recorder.flag(command, status, reason) }
+        Terminal.alert "#{status == :blocked ? 'blocked' : 'flagged for review'} - #{reason}"
+      end
+
+      def run_command(by_user)
+        original = @executing_user_command
+        @executing_user_command = by_user
+        yield
+      ensure
+        @executing_user_command = original
+      end
+
+      # Error messages are built lazily and IRB prints them after the command finished, i.e.
+      # outside the shield. Build them inside it, so they can't leak what the command couldn't read.
+      def masked(error)
+        %i[ message to_s inspect detailed_message ].each do |name|
+          next unless error.respond_to?(name)
+
+          original = error.method(name)
+          error.define_singleton_method(name) do |*args, **kwargs|
+            SafeBro.executor.execute_in_protected_mode { original.call(*args, **kwargs) }
+          end
+        end
+        error
+      rescue FrozenError
+        error
+      end
+  end
+end

data/lib/safe_bro/guards/const_guard.rb

@@ -0,0 +1,39 @@
+module SafeBro
+  module Guards
+    # Constants can be built from strings (Object.const_get("Safe" + "Bro"), "SafeBro".constantize),
+    # which the validator can't see. Resolve them through the validator when asked from the console.
+    module ConstGuard
+      module Lookup
+        def const_get(name, *args)
+          ConstGuard.check!(name, caller_locations(1, 1)) if SafeBro.executor.executing_user_command?
+          super
+        end
+      end
+
+      module StringLookup
+        def constantize
+          ConstGuard.check!(self, caller_locations(1, 1)) if SafeBro.executor.executing_user_command?
+          super
+        end
+
+        def safe_constantize
+          ConstGuard.check!(self, caller_locations(1, 1)) if SafeBro.executor.executing_user_command?
+          super
+        end
+      end
+
+      def self.check!(name, locations)
+        return unless SafeBro.executor.from_console?(locations)
+
+        SafeBro.executor.run_as_system { SafeBro.validator.validate(name.to_s, locked: SafeBro.shield.locked?) }
+      rescue SuspiciousCommand
+        nil
+      end
+
+      def self.install
+        Module.prepend(Lookup)
+        String.prepend(StringLookup)
+      end
+    end
+  end
+end

data/lib/safe_bro/guards/credentials_guard.rb

@@ -0,0 +1,31 @@
+module SafeBro
+  module Guards
+    # Rails credentials, the keys that open them, and the secret everything is derived from.
+    module CredentialsGuard
+      # inspect prints the decrypted values once they have been loaded.
+      module Inspect
+        def inspect
+          if SafeBro.executor.executing_user_command? && SafeBro.shield.protects?(:credentials)
+            "#<#{self.class.name} [protected]>"
+          else
+            super
+          end
+        end
+      end
+
+      def self.install
+        if defined?(ActiveSupport::EncryptedConfiguration)
+          Guarded.install(ActiveSupport::EncryptedConfiguration,
+            %i[ read config options [] fetch dig method_missing instance_variable_get ], :credentials,
+            inherited: %i[ instance_variable_get ])
+          ActiveSupport::EncryptedConfiguration.prepend(Inspect)
+        end
+        if defined?(ActiveSupport::EncryptedFile)
+          Guarded.install(ActiveSupport::EncryptedFile, %i[ read write change key read_env_key read_key_file ], :credentials)
+        end
+        Guarded.install(Rails::Application, %i[ secret_key_base secrets key_generator message_verifier message_verifiers ], :credentials)
+        Guarded.install(Rails::Application::Configuration, %i[ secret_key_base ], :credentials)
+      end
+    end
+  end
+end

data/lib/safe_bro/guards/env_guard.rb

@@ -0,0 +1,67 @@
+module SafeBro
+  module Guards
+    # ENV holds secrets in most deployments. Reading a protected variable by name raises; dumping
+    # the whole thing returns it with the protected values filtered.
+    module EnvGuard
+      FILTERED = "[FILTERED]".freeze
+      KEYED = %i[ [] fetch ].freeze
+      MULTI = %i[ values_at fetch_values slice ].freeze
+      DUMPS = %i[ to_h to_hash to_a each each_pair select filter reject values key ].freeze
+      # Shown whenever the console prints a value, not only when typed directly.
+      DISPLAY = %i[ inspect ].freeze
+
+      def self.redacted
+        ENV.to_h.to_h { |name, value| [ name, SafeBro.config.protected_env_name?(name) ? FILTERED : value ] }
+      end
+
+      def self.guard_name!(name, caller_locations)
+        return unless SafeBro.config.protected_env_name?(name)
+
+        SafeBro.guard!(:env, "(#{name})", locations: caller_locations)
+      end
+
+      module Guard
+        EnvGuard::KEYED.each do |method_name|
+          define_method(method_name) do |name, *args, **kwargs, &block|
+            EnvGuard.guard_name!(name, caller_locations(1, 1)) if SafeBro.executor.executing_user_command?
+            super(name, *args, **kwargs, &block)
+          end
+        end
+
+        EnvGuard::MULTI.each do |method_name|
+          define_method(method_name) do |*names, **kwargs, &block|
+            if SafeBro.executor.executing_user_command?
+              locations = caller_locations(1, 1)
+              names.flatten.each { |name| EnvGuard.guard_name!(name, locations) }
+            end
+            super(*names, **kwargs, &block)
+          end
+        end
+
+        EnvGuard::DUMPS.each do |method_name|
+          define_method(method_name) do |*args, **kwargs, &block|
+            if SafeBro.executor.executing_user_command? && SafeBro.executor.from_console?(caller_locations(1, 1)) && SafeBro.shield.protects?(:env)
+              EnvGuard.redacted.public_send(method_name, *args, **kwargs, &block)
+            else
+              super(*args, **kwargs, &block)
+            end
+          end
+        end
+
+        EnvGuard::DISPLAY.each do |method_name|
+          define_method(method_name) do |*args, **kwargs, &block|
+            if SafeBro.executor.executing_user_command? && SafeBro.shield.protects?(:env)
+              EnvGuard.redacted.public_send(method_name, *args, **kwargs, &block)
+            else
+              super(*args, **kwargs, &block)
+            end
+          end
+        end
+      end
+
+      def self.install
+        ENV.singleton_class.prepend(Guard)
+      end
+    end
+  end
+end

data/lib/safe_bro/guards/file_guard.rb

@@ -0,0 +1,28 @@
+require "pathname"
+require "fileutils"
+
+module SafeBro
+  module Guards
+    # Files that hold secrets (master.key, .env) can't be read from the console while locked.
+    module FileGuard
+      def self.protected_path?(path)
+        return false unless path.respond_to?(:to_path) || path.is_a?(String)
+
+        expanded = File.expand_path(path.respond_to?(:to_path) ? path.to_path : path)
+        SafeBro.config.protected_file_patterns.any? { |pattern| pattern.match?(expanded) }
+      rescue ArgumentError, TypeError
+        false
+      end
+
+      def self.install
+        by_path = ->(_receiver, args) { protected_path?(args.first) }
+        Guarded.install(IO, %i[ read binread readlines foreach ], :files, condition: by_path, scope: :singleton)
+        Guarded.install(File, %i[ new open ], :files, condition: by_path, scope: :singleton, inherited: %i[ new open ])
+        copying = ->(_receiver, args) { Array(args.first).any? { |path| protected_path?(path) } }
+        Guarded.install(FileUtils, %i[ cp copy copy_file cp_r mv move install ], :files, condition: copying, scope: :singleton)
+        Guarded.install(Kernel, %i[ open ], :files, condition: by_path)
+        Guarded.install(Pathname, %i[ read binread readlines ], :files, condition: ->(receiver, _) { protected_path?(receiver) })
+      end
+    end
+  end
+end

data/lib/safe_bro/guards/guarded.rb

@@ -0,0 +1,43 @@
+module SafeBro
+  module Guards
+    # Builds and prepends a module that makes the given methods raise ProtectedResource when
+    # they are called straight from the console while the resource is locked. Library code
+    # calling the same methods is unaffected.
+    module Guarded
+      class << self
+        # condition: ->(receiver, args) { true } narrows which calls are guarded.
+        # inherited: names to guard even though the owner doesn't define them itself (the guard
+        # then sits in front of the inherited method).
+        def install(target, methods, resource, condition: nil, scope: :instance, inherited: [])
+          owner = scope == :singleton ? target.singleton_class : target
+          guard_module = Module.new
+          guarded = 0
+
+          Array(methods).each do |name|
+            visibility = visibility_of(owner, name) || (:public if inherited.include?(name)) or next
+            guard_module.define_method(name) do |*args, **kwargs, &block|
+              if SafeBro.executor.executing_user_command? && (condition.nil? || condition.call(self, args))
+                SafeBro.guard!(resource, "(#{name})", locations: caller_locations(1, 1))
+              end
+              super(*args, **kwargs, &block)
+            end
+            guard_module.send(visibility, name)
+            guarded += 1
+          end
+
+          owner.prepend(guard_module) if guarded > 0
+          guard_module
+        end
+
+        private
+          # Only methods the owner itself defines, so subclasses aren't guarded twice.
+          def visibility_of(owner, name)
+            if owner.public_instance_methods(false).include?(name) then :public
+            elsif owner.protected_instance_methods(false).include?(name) then :protected
+            elsif owner.private_instance_methods(false).include?(name) then :private
+            end
+          end
+      end
+    end
+  end
+end

data/lib/safe_bro/guards/irb_context.rb

@@ -0,0 +1,23 @@
+module SafeBro
+  module Guards
+    # Routes everything typed into IRB through the executor.
+    module IrbContext
+      # Printing the result of a command evaluates #inspect on it, which can read protected data.
+      def inspect_last_value(...)
+        SafeBro.executor.execute_in_protected_mode { super }
+      end
+
+      def evaluate(statement, ...)
+        # irb passes an IRB::Statement; its #code is what was typed.
+        code = statement.respond_to?(:code) ? statement.code : statement
+        SafeBro.executor.execute(Array(code), console_path: safe_bro_console_path) { super }
+      end
+
+      private
+        # The file name the evaluated code runs under.
+        def safe_bro_console_path
+          respond_to?(:eval_path) ? eval_path : irb_path
+        end
+    end
+  end
+end

data/lib/safe_bro/guards/method_guard.rb

@@ -0,0 +1,31 @@
+module SafeBro
+  module Guards
+    # Runtime backstop for config.forbidden_methods. The validator catches `eval(...)` written
+    # out, this catches `send(:eval, ...)`, `method(:eval).call`, and friends.
+    module MethodGuard
+      def self.install
+        SafeBro.config.forbidden_methods.each do |entry|
+          owner_name, separator, method_name = entry.partition(/[#.]/)
+          owner = owner_name.safe_constantize or next
+          scope = separator == "." ? :singleton : :instance
+          install_one(owner, method_name.to_sym, scope, entry)
+        end
+      end
+
+      def self.install_one(target, name, scope, entry)
+        owner = scope == :singleton ? target.singleton_class : target
+        visibility = %i[ public protected private ].find { |v| owner.send(:"#{v}_instance_methods", false).include?(name) } or return
+
+        guard = Module.new
+        guard.define_method(name) do |*args, **kwargs, &block|
+          if SafeBro.executor.executing_user_command? && SafeBro.executor.from_console?(caller_locations(1, 1))
+            raise ForbiddenCommand, "Calling #{entry} is not allowed."
+          end
+          super(*args, **kwargs, &block)
+        end
+        guard.send(visibility, name)
+        owner.prepend(guard)
+      end
+    end
+  end
+end

data/lib/safe_bro/guards/network_guard.rb

@@ -0,0 +1,98 @@
+require "socket"
+require "uri"
+
+module SafeBro
+  module Guards
+    # Stops connections to protected systems (Redis, Elasticsearch, ...) while the network
+    # resource is locked. It checks new connections and writes on existing ones, so a
+    # connection pool opened before the command started doesn't get a free pass.
+    module NetworkGuard
+      class << self
+        def check!(host:, port:)
+          return unless SafeBro.executor.executing_user_command? && SafeBro.shield.protects?(:network)
+          return unless protected?(host, port)
+
+          raise ProtectedResource.new(:network, "(#{host}:#{port})")
+        end
+
+        # Existing connection: look at who it is connected to.
+        def check_socket!(socket)
+          address = socket.respond_to?(:remote_address) ? socket.remote_address : socket.to_io.remote_address
+          check!(host: address.ip_address, port: address.ip_port) if address.ip?
+        rescue SocketError, Errno::ENOTCONN, IOError
+          nil # not connected (yet): nothing to protect
+        end
+
+        def protected?(host, port)
+          targets.any? do |target|
+            target[:port] == port.to_i && (target[:host] == host.to_s || target[:addresses].include?(host.to_s))
+          end
+        end
+
+        def reset!
+          @targets = nil
+        end
+
+        private
+          def targets
+            @targets ||= SafeBro.config.protected_urls.map do |url|
+              host, port = host_and_port(url)
+              { host: host, port: port.to_i, addresses: resolve(host, port) }
+            end
+          end
+
+          def resolve(host, port)
+            Addrinfo.getaddrinfo(host, port, nil, :STREAM).map(&:ip_address)
+          rescue SocketError
+            []
+          end
+
+          def host_and_port(url)
+            uri = URI.parse(url.to_s)
+            return [ uri.host, uri.port ] if uri.host
+
+            host, _, port = url.to_s.rpartition(":")
+            [ host, port ]
+          rescue URI::InvalidURIError
+            host, _, port = url.to_s.rpartition(":")
+            [ host, port ]
+          end
+      end
+
+      module Connect
+        def initialize(host, port, *args, **kwargs)
+          NetworkGuard.check!(host: host, port: port)
+          super
+        end
+      end
+
+      module Writes
+        %i[ write write_nonblock syswrite ].each do |name|
+          define_method(name) do |*args, **kwargs, &block|
+            NetworkGuard.check_socket!(self) if SafeBro.executor.executing_user_command?
+            super(*args, **kwargs, &block)
+          end
+        end
+      end
+
+      module SocketConnect
+        %i[ connect connect_nonblock ].each do |name|
+          define_method(name) do |remote, *args, **kwargs|
+            if SafeBro.executor.executing_user_command?
+              address = remote.is_a?(Addrinfo) ? remote : Addrinfo.new(remote)
+              NetworkGuard.check!(host: address.ip_address, port: address.ip_port) if address.ip?
+            end
+            super(remote, *args, **kwargs)
+          end
+        end
+      end
+
+      def self.install
+        TCPSocket.prepend(Connect)
+        BasicSocket.prepend(Writes)
+        Socket.prepend(SocketConnect)
+        OpenSSL::SSL::SSLSocket.prepend(Writes) if defined?(OpenSSL::SSL::SSLSocket)
+      end
+    end
+  end
+end

data/lib/safe_bro/guards/sql_guard.rb

@@ -0,0 +1,18 @@
+module SafeBro
+  module Guards
+    # Every statement ActiveRecord runs goes through the adapter's #log. A command that
+    # mentions SafeBro's tables (to read, change or delete the audit trail) is stopped here.
+    module SqlGuard
+      TABLES = /safe_bro_(sessions|sensitive_accesses|commands|audits)/i
+
+      private
+        def log(sql, *args, **kwargs, &block)
+          if SafeBro.executor.executing_user_command? && sql.to_s.match?(TABLES)
+            raise TamperingAttempt, "The audit trail can't be touched from the console."
+          end
+
+          super
+        end
+    end
+  end
+end

data/lib/safe_bro/parsed_command.rb

@@ -0,0 +1,66 @@
+require "ripper"
+
+module SafeBro
+  # A lenient lexical view of a console command. It uses Ripper's tokenizer, which keeps
+  # producing tokens for code that doesn't parse, so a syntax trick can't hide a constant
+  # or method name from the validations.
+  class ParsedCommand
+    attr_reader :source
+
+    def initialize(source)
+      @source = Array(source).join("\n")
+    end
+
+    def tokens
+      @tokens ||= Ripper.lex(source).map { |(_pos, type, text, _state)| [ type, text ] }
+    end
+
+    # Constant paths as written: "ActiveRecord::Encryption::Config" (leading :: dropped).
+    def constant_paths
+      @constant_paths ||= begin
+        paths = []
+        significant = tokens.reject { |type, _| type == :on_sp || type == :on_ignored_nl || type == :on_nl }
+        significant.each_with_index do |(type, text), i|
+          next unless type == :on_const
+
+          previous = significant[i - 1]
+          after_scope = i > 0 && previous == [ :on_op, "::" ]
+          qualified = after_scope && i > 1 && significant[i - 2][0] == :on_const
+          if qualified && paths.any?
+            paths[-1] = "#{paths.last}::#{text}"
+          else
+            paths << text
+          end
+        end
+        paths
+      end
+    end
+
+    # Names after `class`/`module`: the things this command (re)opens.
+    def reopened_constants
+      @reopened_constants ||= begin
+        significant = tokens.reject { |type, _| type == :on_sp }
+        significant.each_with_index.filter_map do |(type, text), i|
+          next unless type == :on_kw && %w[ class module ].include?(text)
+
+          name = +""
+          significant[(i + 1)..].each do |t, x|
+            break unless t == :on_const || (t == :on_op && x == "::")
+            name << x
+          end
+          name.delete_prefix("::").presence
+        end
+      end
+    end
+
+    # Identifiers that might be method calls, plus backtick/%x shell execution as "`".
+    def method_names
+      @method_names ||= tokens.filter_map do |type, text|
+        case type
+        when :on_ident, :on_const, :on_kw then text
+        when :on_backtick then "`"
+        end
+      end.uniq
+    end
+  end
+end

data/lib/safe_bro/recorder.rb

@@ -0,0 +1,77 @@
+module SafeBro
+  # Writes the audit trail. Everything here runs as the system (never as a user command),
+  # and silences SQL logging so the trail doesn't spill into the console.
+  class Recorder
+    attr_reader :session, :sensitive_access
+
+    def start_session(username:, reason:, source: "console")
+      quietly do
+        @session = Session.create!(
+          username: username, reason: reason, source: source,
+          hostname: Socket.gethostname, pid: Process.pid, started_at: Time.current
+        )
+      end
+      SafeBro.notify(:session_started, session: @session)
+      @session
+    end
+
+    def finish_session
+      return unless @session
+
+      quietly do
+        end_sensitive_access
+        @session.update!(ended_at: Time.current)
+      end
+      @session = nil
+    end
+
+    # resources: array of symbols, e.g. [:all] or [:credentials]
+    def start_sensitive_access(resources, justification)
+      quietly do
+        end_sensitive_access
+        @sensitive_access = session.sensitive_accesses.create!(
+          resources: resources.join(","), justification: justification, started_at: Time.current
+        )
+      end
+      SafeBro.notify(:unlocked, session: session, access: @sensitive_access)
+      @sensitive_access
+    end
+
+    def end_sensitive_access
+      return unless @sensitive_access
+
+      quietly { @sensitive_access.update!(ended_at: Time.current) }
+      @sensitive_access = nil
+    end
+
+    # Records a command before it runs, linked to the current unlock window if any.
+    def record_command(statements)
+      quietly do
+        session.commands.create!(statements: Array(statements).join("\n").strip, sensitive_access: sensitive_access)
+      end
+    end
+
+    def flag(command, status, reason)
+      quietly { command.update!(status: status, flag_reason: reason) }
+      SafeBro.notify(:command_flagged, session: session, command: command, status: status, reason: reason)
+      command
+    end
+
+    private
+      def quietly(&block)
+        SafeBro.executor.run_as_system do
+          if SafeBro.debug
+            ensure_connected(&block)
+          else
+            ActiveRecord::Base.logger.silence { ensure_connected(&block) }
+          end
+        end
+      end
+
+      def ensure_connected
+        connection = Session.connection
+        connection.reconnect! unless connection.active?
+        yield
+      end
+  end
+end