beskar 0.0.1 → 0.1.0

data/db/migrate/20251016000001_create_beskar_security_events.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class CreateBeskarSecurityEvents < ActiveRecord::Migration[8.0]
+  def change
+    create_table :beskar_security_events do |t|
+      t.references :user, polymorphic: true, null: true, index: true
+      t.string :event_type, null: false
+      t.string :ip_address
+      t.string :attempted_email
+      t.text :user_agent
+      t.json :metadata, default: {}
+      t.integer :risk_score
+
+      t.timestamps
+    end
+
+    add_index :beskar_security_events, :ip_address
+    add_index :beskar_security_events, :event_type
+    add_index :beskar_security_events, :attempted_email
+    add_index :beskar_security_events, :created_at
+    add_index :beskar_security_events, :risk_score
+    add_index :beskar_security_events, [:ip_address, :event_type, :created_at], 
+              name: 'index_security_events_on_ip_event_time'
+  end
+end

data/db/migrate/20251016000002_create_beskar_banned_ips.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class CreateBeskarBannedIps < ActiveRecord::Migration[8.0]
+  def change
+    create_table :beskar_banned_ips do |t|
+      t.string :ip_address, null: false
+      t.string :reason, null: false
+      t.text :details
+      t.datetime :banned_at, null: false
+      t.datetime :expires_at
+      t.boolean :permanent, default: false, null: false
+      t.integer :violation_count, default: 1, null: false
+      t.text :metadata # Using text to store JSON (compatible with SQLite and PostgreSQL)
+
+      t.timestamps
+    end
+
+    add_index :beskar_banned_ips, :ip_address, unique: true
+    add_index :beskar_banned_ips, :banned_at
+    add_index :beskar_banned_ips, :expires_at
+    add_index :beskar_banned_ips, [:ip_address, :expires_at]
+  end
+end

data/lib/beskar/configuration.rb

@@ -0,0 +1,214 @@
+module Beskar
+  class Configuration
+    attr_accessor :rate_limiting, :security_tracking, :risk_based_locking, :geolocation, :ip_whitelist, :waf, :authentication_models, :emergency_password_reset, :monitor_only, :authenticate_admin
+
+    def initialize
+      @monitor_only = false # Global monitor-only mode - logs everything but doesn't block
+      @ip_whitelist = [] # Array of IP addresses or CIDR ranges
+
+      # Dashboard authentication - configure this to restrict access to the dashboard
+      # Example: config.authenticate_admin = proc { authenticate_admin! }
+      @authenticate_admin = nil
+
+      # Authentication models configuration
+      # Auto-detect by default, or can be explicitly configured
+      @authentication_models = {
+        devise: [], # Will be auto-detected: [:devise_user, :admin, etc.]
+        rails_auth: [], # Will be auto-detected: [:user, etc.]
+        auto_detect: true # Set to false to use only explicitly configured models
+      }
+
+      @waf = {
+        enabled: false,                  # Master switch for WAF
+        auto_block: true,                # Automatically block IPs after threshold
+        score_threshold: 150,            # Cumulative risk score before blocking (replaces block_threshold)
+        violation_window: 6.hours,       # Maximum time window to track violations
+        block_durations: [1.hour, 6.hours, 24.hours, 7.days], # Escalating block durations
+        permanent_block_after: 500,      # Permanent block after cumulative score reaches this (nil = never)
+        create_security_events: true,    # Create SecurityEvent records
+        record_not_found_exclusions: [], # Regex patterns to exclude from RecordNotFound detection
+        decay_enabled: true,             # Enable exponential decay of violation scores over time
+        decay_rates: {                   # Decay rates by severity (half-life in minutes)
+          critical: 360,                 # Critical violations: 6 hour half-life
+          high: 120,                     # High violations: 2 hour half-life
+          medium: 45,                    # Medium violations: 45 minute half-life
+          low: 15                        # Low violations: 15 minute half-life
+        },
+        max_violations_tracked: 50       # Maximum number of violations to track per IP (oldest pruned)
+      }
+      @security_tracking = {
+        enabled: true,
+        track_successful_logins: true,
+        track_failed_logins: true,
+        auto_analyze_patterns: true
+      }
+      @rate_limiting = {
+        ip_attempts: {
+          limit: 10,
+          period: 1.hour,
+          exponential_backoff: true
+        },
+        account_attempts: {
+          limit: 5,
+          period: 15.minutes,
+          exponential_backoff: true
+        },
+        global_attempts: {
+          limit: 100,
+          period: 1.minute,
+          exponential_backoff: false
+        }
+      }
+      @risk_based_locking = {
+        enabled: false,                    # Master switch for risk-based locking
+        risk_threshold: 75,                # Lock account if risk score >= this value
+        lock_strategy: :devise_lockable,   # Strategy: :devise_lockable, :custom, :none
+        auto_unlock_time: 1.hour,          # Time until automatic unlock (if supported by strategy)
+        notify_user: true,                 # Send notification on lock
+        log_lock_events: true,             # Create security event for locks
+        immediate_signout: false           # Sign out user immediately via Warden callback (requires :lockable)
+      }
+      @geolocation = {
+        provider: :mock,                   # Provider: :maxmind, :mock
+        maxmind_city_db_path: nil,         # Path to MaxMind GeoLite2-City.mmdb or GeoIP2-City.mmdb
+        cache_ttl: 4.hours                 # How long to cache geolocation results
+      }
+      @emergency_password_reset = {
+        enabled: false,                    # Master switch for emergency password reset
+        impossible_travel_threshold: 3,    # Reset after N impossible travel events in 24h
+        suspicious_device_threshold: 5,    # Reset after N suspicious device events in 24h
+        total_locks_threshold: 5,          # Reset after N total locks in 24h (any reason)
+        send_notification: true,           # Send email to user about reset
+        notify_security_team: true,        # Alert security team about automatic resets
+        require_manual_unlock: false       # Require manual admin unlock after reset
+      }
+    end
+
+    def security_tracking_enabled?
+      @security_tracking[:enabled]
+    end
+
+    def track_successful_logins?
+      security_tracking_enabled? && @security_tracking[:track_successful_logins]
+    end
+
+    def track_failed_logins?
+      security_tracking_enabled? && @security_tracking[:track_failed_logins]
+    end
+
+    def auto_analyze_patterns?
+      security_tracking_enabled? && @security_tracking[:auto_analyze_patterns]
+    end
+
+    # Risk-based locking configuration helpers
+    def risk_based_locking_enabled?
+      @risk_based_locking[:enabled]
+    end
+
+    def risk_threshold
+      @risk_based_locking[:risk_threshold] || 75
+    end
+
+    def lock_strategy
+      @risk_based_locking[:lock_strategy] || :devise_lockable
+    end
+
+    def auto_unlock_time
+      @risk_based_locking[:auto_unlock_time] || 1.hour
+    end
+
+    def notify_user_on_lock?
+      @risk_based_locking[:notify_user] != false
+    end
+
+    def log_lock_events?
+      @risk_based_locking[:log_lock_events] != false
+    end
+
+    def immediate_signout?
+      @risk_based_locking[:immediate_signout] == true
+    end
+
+    # Geolocation configuration helpers
+    def geolocation_provider
+      @geolocation[:provider] || :mock
+    end
+
+    def maxmind_city_db_path
+      @geolocation[:maxmind_city_db_path]
+    end
+
+    def geolocation_cache_ttl
+      @geolocation[:cache_ttl] || 4.hours
+    end
+
+    # WAF configuration helpers
+    def waf_enabled?
+      @waf && @waf[:enabled]
+    end
+
+    def waf_auto_block?
+      waf_enabled? && @waf[:auto_block] && !@monitor_only
+    end
+
+    # General monitor-only mode check (affects all blocking)
+    def monitor_only?
+      @monitor_only == true
+    end
+
+    # IP Whitelist configuration helpers
+    def ip_whitelist_enabled?
+      @ip_whitelist.is_a?(Array) && @ip_whitelist.any?
+    end
+
+    # Authentication models helpers
+    def devise_scopes
+      return @authentication_models[:devise] unless @authentication_models[:auto_detect]
+
+      # Auto-detect Devise models
+      detected = []
+      if defined?(Devise)
+        Devise.mappings.keys.each do |scope|
+          detected << scope
+        end
+      end
+
+      # Merge with explicitly configured models
+      (detected + Array(@authentication_models[:devise])).uniq
+    end
+
+    def rails_auth_scopes
+      return @authentication_models[:rails_auth] unless @authentication_models[:auto_detect]
+
+      # Auto-detect Rails authentication models (has_secure_password)
+      detected = []
+      if defined?(ActiveRecord::Base)
+        # Try to find models with has_secure_password
+        # This is a heuristic - models that have password_digest column
+        ActiveRecord::Base.descendants.each do |model|
+          next unless model.table_exists?
+          if model.column_names.include?("password_digest")
+            scope = model.name.underscore.to_sym
+            detected << scope unless devise_scopes.include?(scope)
+          end
+        rescue => e
+          # Ignore errors during detection
+          Beskar::Logger.debug("Error detecting Rails auth model #{model.name}: #{e.message}")
+        end
+      end
+
+      # Merge with explicitly configured models
+      (detected + Array(@authentication_models[:rails_auth])).uniq
+    end
+
+    def all_auth_scopes
+      (devise_scopes + rails_auth_scopes).uniq
+    end
+
+    def model_class_for_scope(scope)
+      scope.to_s.camelize.constantize
+    rescue NameError
+      nil
+    end
+  end
+end

data/lib/beskar/engine.rb

@@ -1,5 +1,110 @@
 module Beskar
   class Engine < ::Rails::Engine
     isolate_namespace Beskar
+
+    initializer "beskar.middleware" do |app|
+      app.config.middleware.use ::Beskar::Middleware::RequestAnalyzer
+    end
+
+    # Preload banned IPs into cache on startup
+    config.after_initialize do
+      if defined?(Beskar::BannedIp)
+        Rails.application.executor.wrap do
+          Beskar::BannedIp.preload_cache!
+          Beskar::Logger.info("Preloaded banned IPs into cache")
+        rescue => e
+          Beskar::Logger.warn("Failed to preload banned IPs: #{e.message}")
+        end
+      end
+    end
+
+    initializer "beskar.warden_callbacks", after: :load_config_initializers do |app|
+      if defined?(Warden)
+        # Track successful authentication and check for high-risk locks
+        Warden::Manager.after_set_user except: :fetch do |user, auth, opts|
+          # Only proceed if Beskar security tracking is available and enabled
+          if user.respond_to?(:track_authentication_event) && auth.request
+            # Track the authentication event (creates security event)
+            security_event = user.track_authentication_event(auth.request, :success)
+
+            # Check if account was locked due to high risk (only if immediate_signout is enabled)
+            # This happens AFTER successful authentication but BEFORE the request completes
+            # Requires :lockable module to be enabled on the user model
+            if Beskar.configuration.immediate_signout? &&
+               Beskar.configuration.risk_based_locking_enabled? &&
+               security_event &&
+               user_was_just_locked?(user, security_event) &&
+               user.respond_to?(:access_locked?) && user.access_locked?
+              Beskar::Logger.warn("Signing out user #{user.id} due to high-risk lock")
+              auth.logout
+              throw :warden, scope: opts[:scope], message: :account_locked_due_to_high_risk
+            end
+          end
+        end
+
+        # Alternative approach using after_authentication is available but not enabled by default
+        # Uncomment this to use the alternative approach (more targeted, only on authentication)
+        # Warden::Manager.after_authentication do |user, auth, opts|
+        #   if user.respond_to?(:check_high_risk_lock_and_signout)
+        #     user.check_high_risk_lock_and_signout(auth)
+        #   end
+        # end
+
+        Warden::Manager.before_failure do |env, opts|
+          if env
+            request = ActionDispatch::Request.new(env)
+            scope = opts[:scope]
+            
+            # Try to get model class from configuration
+            model_class = Beskar.configuration&.model_class_for_scope(scope)
+            
+            if model_class && model_class.respond_to?(:track_failed_authentication)
+              model_class.track_failed_authentication(request, scope)
+            else
+              Beskar::Logger.debug("No trackable model found for scope: #{scope}")
+            end
+          end
+        end
+      end
+    end
+
+    # Helper method to check if user was just locked
+    def self.user_was_just_locked?(user, security_event)
+      return false unless Beskar.configuration.risk_based_locking_enabled?
+      return false unless security_event
+      return false unless user&.respond_to?(:security_events)
+
+      # Check if an account_locked or lock_attempted event was just created
+      recent_lock = user.security_events
+        .where(event_type: [ "account_locked", "lock_attempted" ])
+        .where("created_at >= ?", 10.seconds.ago)
+        .order(created_at: :desc)
+        .first
+
+      recent_lock.present?
+    end
+
+    # Add engine migrations to host app's migration paths
+    initializer "beskar.append_migrations" do |app|
+      # Don't add migrations if we're inside the engine itself (testing)
+      if !root.to_s.include?(app.root.to_s) && !app.root.to_s.include?(root.to_s)
+        engine_migrations = root.join("db", "migrate").to_s
+
+        # Add to Rails paths
+        app.config.paths["db/migrate"] << engine_migrations
+      end
+    end
+
+    # Ensure ActiveRecord sees the engine migrations after initialization
+    # config.after_initialize do |app|
+    #   unless root.to_s.include?(app.root.to_s)
+    #     engine_migrations = root.join("db", "migrate").to_s
+
+    #     # Update ActiveRecord::Tasks paths
+    #     current_paths = Array(ActiveRecord::Tasks::DatabaseTasks.migrations_paths)
+    #     current_paths << engine_migrations
+    #     ActiveRecord::Tasks::DatabaseTasks.migrations_paths = current_paths.uniq
+    #   end
+    # end
   end
 end

data/lib/beskar/logger.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module Beskar
+  # Centralized logging module for consistent log formatting and flexible output handling
+  module Logger
+    class << self
+      # Available log levels
+      LOG_LEVELS = %i[debug info warn error fatal].freeze
+
+      # Generate logging methods for each level
+      LOG_LEVELS.each do |level|
+        define_method(level) do |message, component: nil|
+          log(level, message, component: component)
+        end
+      end
+
+      # Main logging method that handles formatting and output
+      #
+      # @param level [Symbol] The log level (:debug, :info, :warn, :error, :fatal)
+      # @param message [String] The message to log
+      # @param component [String, Symbol, nil] Optional component name for more specific prefixes
+      #
+      # @example Basic usage
+      #   Beskar::Logger.info("User authenticated successfully")
+      #   # => [Beskar] User authenticated successfully
+      #
+      # @example With component
+      #   Beskar::Logger.warn("Rate limit exceeded", component: :WAF)
+      #   # => [Beskar::WAF] Rate limit exceeded
+      #
+      # @example With class as component
+      #   Beskar::Logger.error("Failed to lock account", component: self.class)
+      #   # => [Beskar::AccountLocker] Failed to lock account
+      def log(level, message, component: nil)
+        return unless should_log?(level)
+
+        formatted_message = format_message(message, component)
+        logger.send(level, formatted_message)
+      rescue StandardError => e
+        # Fallback to stderr if logging fails
+        $stderr.puts "[Beskar::Logger] Failed to log message: #{e.message}"
+        $stderr.puts "[Beskar::Logger] Original message: #{formatted_message}"
+      end
+
+      # Configure the logger instance
+      #
+      # @param logger_instance [Logger, nil] The logger to use, defaults to Rails.logger
+      def logger=(logger_instance)
+        @logger = logger_instance
+      end
+
+      # Get the current logger instance
+      #
+      # @return [Logger] The configured logger or Rails.logger as default
+      def logger
+        @logger ||= default_logger
+      end
+
+      # Configure log level threshold
+      #
+      # @param level [Symbol, String] Minimum log level to output
+      def level=(level)
+        @level = level.to_sym if LOG_LEVELS.include?(level.to_sym)
+      end
+
+      # Get the current log level
+      #
+      # @return [Symbol] Current log level
+      def level
+        @level ||= :debug
+      end
+
+      # Reset logger configuration to defaults
+      def reset!
+        @logger = nil
+        @level = nil
+        @component_aliases = nil
+      end
+
+      # Configure component name aliases for cleaner output
+      #
+      # @param aliases [Hash] Mapping of classes/modules to display names
+      #
+      # @example
+      #   Beskar::Logger.component_aliases = {
+      #     'Beskar::Services::Waf' => 'WAF',
+      #     'Beskar::Services::AccountLocker' => 'AccountLocker'
+      #   }
+      def component_aliases=(aliases)
+        @component_aliases = aliases
+      end
+
+      # Get component aliases
+      #
+      # @return [Hash] Current component aliases
+      def component_aliases
+        @component_aliases ||= default_component_aliases
+      end
+
+      private
+
+      # Format the log message with appropriate prefix
+      #
+      # @param message [String] The message to format
+      # @param component [String, Symbol, Class, nil] Component identifier
+      # @return [String] Formatted message with prefix
+      def format_message(message, component)
+        prefix = build_prefix(component)
+        "#{prefix} #{message}"
+      end
+
+      # Build the log prefix based on component
+      #
+      # @param component [String, Symbol, Class, nil] Component identifier
+      # @return [String] Formatted prefix
+      def build_prefix(component)
+        return "[Beskar]" if component.nil?
+
+        component_name = normalize_component_name(component)
+
+        if component_name.nil? || component_name.empty?
+          "[Beskar]"
+        else
+          "[Beskar::#{component_name}]"
+        end
+      end
+
+      # Normalize component name from various input types
+      #
+      # @param component [String, Symbol, Class] Component identifier
+      # @return [String, nil] Normalized component name
+      def normalize_component_name(component)
+        case component
+        when String
+          apply_component_alias(component)
+        when Symbol
+          component.to_s
+        when Class
+          apply_component_alias(component.name)
+        when Module
+          apply_component_alias(component.name)
+        else
+          component.to_s
+        end
+      end
+
+      # Apply component alias if configured
+      #
+      # @param component_name [String] Original component name
+      # @return [String] Aliased name or original
+      def apply_component_alias(component_name)
+        return nil if component_name.nil?
+
+        # First check exact matches
+        aliased = component_aliases[component_name]
+        return aliased if aliased
+
+        # Remove Beskar:: prefix if present for lookup
+        clean_name = component_name.sub(/^Beskar::/, '')
+        aliased = component_aliases[clean_name]
+        return aliased if aliased
+
+        # Check if it's already a simple component name (no ::)
+        return clean_name unless clean_name.include?('::')
+
+        # Extract the last component for nested classes
+        # e.g., "Beskar::Services::Waf" -> "Waf"
+        last_component = clean_name.split('::').last
+        component_aliases[clean_name] || last_component
+      end
+
+      # Check if message should be logged based on current level
+      #
+      # @param message_level [Symbol] Level of the message
+      # @return [Boolean] True if message should be logged
+      def should_log?(message_level)
+        level_value(message_level) >= level_value(level)
+      end
+
+      # Convert log level to numeric value for comparison
+      #
+      # @param level_sym [Symbol] Log level
+      # @return [Integer] Numeric value
+      def level_value(level_sym)
+        LOG_LEVELS.index(level_sym) || 0
+      end
+
+      # Get the default logger instance
+      #
+      # @return [Logger] Default logger (Rails.logger or stdlib Logger)
+      def default_logger
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger
+        else
+          require 'logger'
+          ::Logger.new($stdout)
+        end
+      end
+
+      # Default component name aliases for cleaner output
+      #
+      # @return [Hash] Default aliases
+      def default_component_aliases
+        {
+          'Beskar::Services::Waf' => 'WAF',
+          'Beskar::Services::WAF' => 'WAF',
+          'Services::Waf' => 'WAF',
+          'Services::WAF' => 'WAF',
+          'Beskar::Services::AccountLocker' => 'AccountLocker',
+          'Services::AccountLocker' => 'AccountLocker',
+          'Beskar::Services::RateLimiter' => 'RateLimiter',
+          'Services::RateLimiter' => 'RateLimiter',
+          'Beskar::Services::IpWhitelist' => 'IpWhitelist',
+          'Services::IpWhitelist' => 'IpWhitelist',
+          'Beskar::Services::GeolocationService' => 'GeolocationService',
+          'Services::GeolocationService' => 'GeolocationService',
+          'Beskar::Services::DeviceDetector' => 'DeviceDetector',
+          'Services::DeviceDetector' => 'DeviceDetector',
+          'Beskar::Middleware::RequestAnalyzer' => 'Middleware',
+          'Middleware::RequestAnalyzer' => 'Middleware',
+          'Beskar::Models::SecurityTrackableDevise' => 'SecurityTracking',
+          'Models::SecurityTrackableDevise' => 'SecurityTracking',
+          'Beskar::Models::SecurityTrackableAuthenticable' => 'SecurityTracking',
+          'Models::SecurityTrackableAuthenticable' => 'SecurityTracking',
+          'Beskar::Models::SecurityTrackableGeneric' => 'SecurityTracking',
+          'Models::SecurityTrackableGeneric' => 'SecurityTracking'
+        }
+      end
+    end
+
+    # Module to include in classes for instance-level logging
+    module ClassMethods
+      # Log a debug message with automatic component detection
+      def log_debug(message)
+        Beskar::Logger.debug(message, component: self)
+      end
+
+      # Log an info message with automatic component detection
+      def log_info(message)
+        Beskar::Logger.info(message, component: self)
+      end
+
+      # Log a warning message with automatic component detection
+      def log_warn(message)
+        Beskar::Logger.warn(message, component: self)
+      end
+
+      # Log an error message with automatic component detection
+      def log_error(message)
+        Beskar::Logger.error(message, component: self)
+      end
+
+      # Log a fatal message with automatic component detection
+      def log_fatal(message)
+        Beskar::Logger.fatal(message, component: self)
+      end
+    end
+
+    # Module to include in classes for instance-level logging
+    module InstanceMethods
+      # Log a debug message with automatic component detection
+      def log_debug(message)
+        Beskar::Logger.debug(message, component: self.class)
+      end
+
+      # Log an info message with automatic component detection
+      def log_info(message)
+        Beskar::Logger.info(message, component: self.class)
+      end
+
+      # Log a warning message with automatic component detection
+      def log_warn(message)
+        Beskar::Logger.warn(message, component: self.class)
+      end
+
+      # Log an error message with automatic component detection
+      def log_error(message)
+        Beskar::Logger.error(message, component: self.class)
+      end
+
+      # Log a fatal message with automatic component detection
+      def log_fatal(message)
+        Beskar::Logger.fatal(message, component: self.class)
+      end
+    end
+
+    # Convenience method to include both class and instance methods
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(InstanceMethods)
+    end
+  end
+end