safe_bro 0.1.0

data/lib/safe_bro/shield.rb

@@ -0,0 +1,83 @@
+module SafeBro
+  # The shield decides what is protected right now. Everything starts locked. unlock! asks for
+  # a justification, records it, and opens the requested resources until lock!.
+  #
+  # Resources:
+  #   encrypted_data - Active Record encrypted attributes read as ciphertext
+  #   credentials    - Rails credentials, their keys, secret_key_base
+  #   env            - ENV values whose names look secret
+  #   files          - master.key, .env files
+  #   network        - connections to config.protected_urls
+  class Shield
+    RESOURCES = %i[ encrypted_data credentials env files network ].freeze
+
+    def initialize
+      @unlocked = Set.new
+    end
+
+    def locked?
+      @unlocked.empty?
+    end
+
+    def unlocked?(resource)
+      @unlocked.include?(:all) || @unlocked.include?(resource)
+    end
+
+    # Is this resource protected from the console right now?
+    def protects?(resource)
+      SafeBro.config.protected_resources.include?(resource) && !unlocked?(resource)
+    end
+
+    def unlock(resources = [ :all ])
+      unknown = resources - RESOURCES - SafeBro.config.protected_resources - [ :all ]
+      raise ArgumentError, "Unknown resource #{unknown.first.inspect}. Choose from #{(RESOURCES | SafeBro.config.protected_resources).join(', ')}." if unknown.any?
+
+      SafeBro.executor.run_as_system do
+        justification = Terminal.ask(SafeBro.config.unlock_prompt)
+        SafeBro.recorder.start_sensitive_access(resources, justification)
+        @unlocked = Set.new(resources)
+        Terminal.say(SafeBro.config.unlocked_message, :yellow)
+      end
+    end
+
+    def lock(silent: false)
+      SafeBro.executor.run_as_system do
+        was_unlocked = !locked?
+        SafeBro.recorder.end_sensitive_access if SafeBro.recorder.session
+        @unlocked = Set.new
+        Terminal.say(SafeBro.config.locked_message, :yellow) if was_unlocked && !silent
+      end
+    end
+
+    # Runs the block with the protections that work by wrapping execution switched on.
+    def protect(&block)
+      if protects?(:encrypted_data) && encryption_available?
+        ActiveRecord::Encryption.protecting_encrypted_data(&block)
+      else
+        block.call
+      end
+    end
+
+    def install
+      ActiveRecord::ConnectionAdapters::AbstractAdapter.prepend(Guards::SqlGuard)
+      Guards::NetworkGuard.install if SafeBro.config.protected_urls.any?
+      Guards::CredentialsGuard.install
+      Guards::EnvGuard.install
+      Guards::FileGuard.install
+      Guards::ConstGuard.install
+      Guards::MethodGuard.install
+      install_irb
+    end
+
+    private
+      def install_irb
+        IRB::Context.prepend(Guards::IrbContext)
+        IRB::Command.register(:unlock!, Commands::Unlock)
+        IRB::Command.register(:lock!, Commands::Lock)
+      end
+
+      def encryption_available?
+        defined?(ActiveRecord::Encryption) && ActiveRecord::Encryption.respond_to?(:protecting_encrypted_data)
+      end
+  end
+end

data/lib/safe_bro/supervisor.rb

@@ -0,0 +1,68 @@
+module SafeBro
+  # Entry point for a console (or runner) process: installs the protections once, then
+  # identifies the person, asks why, and opens a session.
+  class Supervisor
+    def run_console
+      install
+      start
+    end
+
+    def run_runner
+      start(source: "runner", reason: runner_reason, username: runner_username, interactive: false)
+      SafeBro.recorder.record_command(runner_statements)
+    end
+
+    def install
+      return if @installed
+
+      # Loaded ahead of time: without this, the first command in a real console raised
+      # "uninitialized constant ActiveRecord::QueryMethods::Relation" (console1984 hit the same).
+      require "active_record/relation"
+      SafeBro.shield.install
+      SafeBro.lock_down! if SafeBro.config.freeze_internals
+      @installed = true
+    end
+
+    def start(source: "console", reason: nil, username: nil, interactive: true)
+      SafeBro.shield.lock(silent: true)
+      Terminal.say(SafeBro.config.welcome_message, :yellow) if interactive
+      username ||= current_username
+      reason ||= session_reason(username)
+      SafeBro.recorder.start_session(username: username, reason: reason, source: source)
+      at_exit { stop }
+    end
+
+    def stop
+      SafeBro.recorder.finish_session
+    end
+
+    def current_username
+      SafeBro.config.username_resolver.call.to_s.strip.presence ||
+        (SafeBro.config.ask_for_username_if_empty && Terminal.interactive? && Terminal.ask("Please, enter your name:")) ||
+        raise(MissingUsername)
+    end
+
+    private
+      # CONSOLE_REASON answers without a terminal; otherwise ask, and refuse to continue without one.
+      def session_reason(username)
+        env_reason = ENV["CONSOLE_REASON"].to_s.squish.first(255).presence
+        return env_reason if env_reason
+        raise MissingReason unless Terminal.interactive?
+
+        Terminal.ask("#{username}, why are you using this console today?")
+      end
+
+      # Runners are usually automation: don't refuse, but record that nobody said who or why.
+      def runner_reason
+        ENV["CONSOLE_REASON"].to_s.squish.first(255).presence || "(no reason given)"
+      end
+
+      def runner_username
+        SafeBro.config.username_resolver.call.to_s.strip.presence || "(unattributed)"
+      end
+
+      def runner_statements
+        "rails runner #{ARGV.join(' ')}".strip
+      end
+  end
+end

data/lib/safe_bro/terminal.rb

@@ -0,0 +1,55 @@
+module SafeBro
+  # Talking to the person at the console.
+  module Terminal
+    COLORS = { green: 32, yellow: 33, red: 31, blue: 34 }.freeze
+
+    class << self
+      # Tests silence console output.
+      attr_accessor :muted
+
+      def interactive?
+        $stdin.tty?
+      end
+
+      def say(message, color = nil)
+        return if muted
+
+        text = "\n#{message}\n"
+        $stdout.puts(color && $stdout.tty? ? "\e[#{COLORS.fetch(color)}m#{text}\e[0m" : text)
+      end
+
+      # Something worth the person's attention, on stderr so it doesn't mix with output they pipe.
+      def alert(message)
+        $stderr.puts("SafeBro: #{message}") unless muted
+      end
+
+      # Asks until it gets a non-blank answer. Raises NotInteractive when there's nobody to ask.
+      def ask(question)
+        raise NotInteractive unless interactive?
+
+        say(question, :green)
+        answer = nil
+        with_plain_output do
+          loop do
+            line = Reline.readline("> ", false)
+            raise NotInteractive, "No answer given." if line.nil?
+
+            answer = line.strip
+            break unless answer.empty?
+          end
+        end
+        answer
+      end
+
+      private
+        # IRB colorizes what you type; the answer should look like plain text.
+        def with_plain_output
+          original = Reline.output_modifier_proc
+          Reline.output_modifier_proc = nil
+          yield
+        ensure
+          Reline.output_modifier_proc = original
+        end
+    end
+  end
+end

data/lib/safe_bro/validator.rb

@@ -0,0 +1,74 @@
+module SafeBro
+  # Static analysis of a console command, before it runs. Each validation raises
+  # ForbiddenCommand (blocked) or SuspiciousCommand (runs, but is flagged).
+  #
+  # This is a speed bump for honest mistakes and a tripwire for dishonest attempts. It is not
+  # a sandbox: Ruby is too dynamic for that. The runtime guards (see Guards) cover the most
+  # obvious ways around it, and the rest is what the audit trail is for.
+  class Validator
+    class Validation
+      def initialize(config)
+        @config = config
+      end
+
+      attr_reader :config
+    end
+
+    # class Foo / module Foo for a protected Foo or Foo::Bar.
+    class ForbiddenReopening < Validation
+      def validate(command, locked:)
+        command.reopened_constants.each do |name|
+          if config.forbidden_reopening.any? { |forbidden| name == forbidden || name.start_with?("#{forbidden}::") }
+            raise ForbiddenCommand, "Reopening #{name} is not allowed."
+          end
+        end
+      end
+    end
+
+    class ForbiddenConstantReference < Validation
+      def validate(command, locked:)
+        forbidden = config.forbidden_constants.fetch(:always, [])
+        forbidden += config.forbidden_constants.fetch(:locked, []) if locked
+        command.constant_paths.each do |path|
+          match = forbidden.find { |f| path == f || path.start_with?("#{f}::") }
+          raise ForbiddenCommand, "Referencing #{match} is not allowed#{' while locked' unless config.forbidden_constants.fetch(:always, []).include?(match)}." if match
+        end
+      end
+    end
+
+    # Method names from forbidden_methods ("Kernel#eval" -> eval), wherever they appear.
+    class ForbiddenMethods < Validation
+      def validate(command, locked:)
+        names = config.forbidden_methods.map { |entry| entry.split(/[#.]/, 2).last }.uniq
+        used = command.method_names & names
+        raise ForbiddenCommand, "Calling #{used.first} is not allowed." if used.any?
+      end
+    end
+
+    class SuspiciousTerms < Validation
+      def validate(command, locked:)
+        term = config.suspicious_terms.find { |t| command.source.include?(t) }
+        raise SuspiciousCommand, "Command mentions #{term}." if term
+      end
+    end
+
+    VALIDATIONS = [ ForbiddenReopening, ForbiddenConstantReference, ForbiddenMethods, SuspiciousTerms ].freeze
+
+    def initialize(config = SafeBro.config)
+      @validations = VALIDATIONS.map { |klass| klass.new(config) }
+    end
+
+    # Raises on the first failing validation. Forbidden beats suspicious, so run every
+    # validation and only then raise a suspicion.
+    def validate(source, locked: true)
+      command = ParsedCommand.new(source)
+      suspicion = nil
+      @validations.each do |validation|
+        validation.validate(command, locked: locked)
+      rescue SuspiciousCommand => error
+        suspicion ||= error
+      end
+      raise suspicion if suspicion
+    end
+  end
+end

data/lib/safe_bro/version.rb

@@ -0,0 +1,3 @@
+module SafeBro
+  VERSION = "0.1.0"
+end

data/lib/safe_bro.rb

@@ -0,0 +1,98 @@
+require "irb"
+require "reline"
+require "set"
+require "socket"
+
+require "bro_hub"
+require "safe_bro/version"
+require "safe_bro/errors"
+require "safe_bro/configuration"
+require "safe_bro/cipher"
+require "safe_bro/parsed_command"
+require "safe_bro/validator"
+require "safe_bro/terminal"
+require "safe_bro/recorder"
+require "safe_bro/executor"
+require "safe_bro/guards/guarded"
+require "safe_bro/guards/sql_guard"
+require "safe_bro/guards/network_guard"
+require "safe_bro/guards/credentials_guard"
+require "safe_bro/guards/env_guard"
+require "safe_bro/guards/file_guard"
+require "safe_bro/guards/method_guard"
+require "safe_bro/guards/const_guard"
+require "safe_bro/guards/irb_context"
+require "safe_bro/commands"
+require "safe_bro/shield"
+require "safe_bro/supervisor"
+require "safe_bro/engine"
+
+# = SafeBro
+#
+# Audited, guarded Rails console access.
+#
+# * Every console session is recorded: who, why, and every command (encrypted at rest).
+# * Sensitive data (encrypted attributes, credentials, ENV secrets, protected systems) is
+#   locked until the person runs unlock! and explains why. Everything done while unlocked
+#   is linked to that justification.
+# * Commands are checked before they run: forbidden ones are blocked, suspicious ones flagged.
+# * The audit trail itself can't be changed from the console.
+# * Auditors review sessions in a mountable engine.
+#
+# Access from the console is a deterrent plus an audit trail, not a sandbox. See the README.
+module SafeBro
+  class << self
+    attr_accessor :debug
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset_config!
+      @config = nil
+    end
+
+    def enabled?
+      config.enabled?
+    end
+
+    # The collaborators are created on first use and then shared.
+    def supervisor = @supervisor ||= Supervisor.new
+    def shield = @shield ||= Shield.new
+    def executor = @executor ||= Executor.new
+    def recorder = @recorder ||= Recorder.new
+    def validator = @validator ||= Validator.new(config)
+
+    # For gems that expose sensitive things (e.g. a credentials reveal): call this first.
+    # Raises ProtectedResource when running under a console command while the resource is
+    # locked. With `locations:` (caller_locations) it only raises for calls made directly
+    # from what the person typed.
+    def guard!(resource, detail = nil, locations: nil)
+      return unless executor.executing_user_command? && shield.protects?(resource)
+      return if locations && !executor.from_console?(locations)
+
+      raise ProtectedResource.new(resource, detail)
+    end
+
+    # Subscribe with ActiveSupport::Notifications.subscribe(/\.safe_bro\z/) to alert people.
+    # Events: session_started, unlocked, command_flagged, session_flagged.
+    def notify(event, **payload)
+      ActiveSupport::Notifications.instrument("#{event}.safe_bro", payload)
+    rescue => error
+      Rails.logger&.error("SafeBro: notification #{event} failed: #{error.class}: #{error.message}")
+    end
+
+    # Freezes configuration and SafeBro's own classes so they can't be monkey patched from a console.
+    def lock_down!
+      config.lock_down!
+      [ Executor, Shield, Recorder, Supervisor, Validator, Validator::Validation, *Validator::VALIDATIONS,
+        ParsedCommand, Terminal, Commands::Unlock, Commands::Lock, Guards::Guarded, Guards::SqlGuard,
+        Guards::EnvGuard, Guards::FileGuard, Guards::MethodGuard, Guards::ConstGuard, Guards::CredentialsGuard, Guards::CredentialsGuard::Inspect,
+        Guards::IrbContext ].each(&:freeze)
+    end
+  end
+end

data/lib/tasks/safe_bro.rake

@@ -0,0 +1,7 @@
+namespace :safe_bro do
+  desc "Delete console sessions older than config.retention (flagged ones are kept unless keep_flagged is off)"
+  task purge: :environment do
+    deleted = SafeBro::Session.purge!
+    puts "SafeBro: purged #{deleted} session#{'s' unless deleted == 1}"
+  end
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: safe_bro
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ruby Dev SRL
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: bro_hub
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: Records Rails console sessions (who, why, what), asks for a justification
+  before sensitive data is touched, blocks tampering and risky methods, and ships
+  a mountable engine where auditors review sessions. One gem instead of console1984
+  plus audits1984.
+email:
+- office@rubydev.ro
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/safe_bro/application_controller.rb
+- app/controllers/safe_bro/audits_controller.rb
+- app/controllers/safe_bro/flagged_commands_controller.rb
+- app/controllers/safe_bro/rules_controller.rb
+- app/controllers/safe_bro/sessions_controller.rb
+- app/controllers/safe_bro/unlocks_controller.rb
+- app/helpers/safe_bro/application_helper.rb
+- app/jobs/safe_bro/purge_job.rb
+- app/models/safe_bro/application_record.rb
+- app/models/safe_bro/audit.rb
+- app/models/safe_bro/command.rb
+- app/models/safe_bro/sensitive_access.rb
+- app/models/safe_bro/session.rb
+- app/views/safe_bro/flagged_commands/index.html.erb
+- app/views/safe_bro/rules/show.html.erb
+- app/views/safe_bro/sessions/index.html.erb
+- app/views/safe_bro/sessions/show.html.erb
+- app/views/safe_bro/shared/forbidden.html.erb
+- app/views/safe_bro/unlocks/index.html.erb
+- config/routes.rb
+- db/migrate/20261114000001_create_safe_bro_tables.rb
+- lib/generators/safe_bro/install/install_generator.rb
+- lib/generators/safe_bro/install/templates/safe_bro.rb
+- lib/safe_bro.rb
+- lib/safe_bro/cipher.rb
+- lib/safe_bro/commands.rb
+- lib/safe_bro/configuration.rb
+- lib/safe_bro/encrypted_type.rb
+- lib/safe_bro/engine.rb
+- lib/safe_bro/errors.rb
+- lib/safe_bro/executor.rb
+- lib/safe_bro/guards/const_guard.rb
+- lib/safe_bro/guards/credentials_guard.rb
+- lib/safe_bro/guards/env_guard.rb
+- lib/safe_bro/guards/file_guard.rb
+- lib/safe_bro/guards/guarded.rb
+- lib/safe_bro/guards/irb_context.rb
+- lib/safe_bro/guards/method_guard.rb
+- lib/safe_bro/guards/network_guard.rb
+- lib/safe_bro/guards/sql_guard.rb
+- lib/safe_bro/parsed_command.rb
+- lib/safe_bro/recorder.rb
+- lib/safe_bro/shield.rb
+- lib/safe_bro/supervisor.rb
+- lib/safe_bro/terminal.rb
+- lib/safe_bro/validator.rb
+- lib/safe_bro/version.rb
+- lib/tasks/safe_bro.rake
+homepage: https://www.rubydev.ro
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://www.rubydev.ro
+  source_code_uri: https://github.com/rubydevro/safe_bro
+  bug_tracker_uri: https://github.com/rubydevro/safe_bro/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Audited, guarded Rails console access, with a built-in review UI.
+test_files: []