beskar 0.0.1 → 0.1.0

data/lib/beskar/services/device_detector.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Beskar
+  module Services
+    # Service for detecting device information from User-Agent strings
+    #
+    # This service provides comprehensive device, browser, and platform detection
+    # capabilities for security analysis and fingerprinting purposes.
+    #
+    # @example Basic usage
+    #   detector = Beskar::Services::DeviceDetector.new
+    #   info = detector.detect("Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)")
+    #   # => {
+    #   #   browser: "Safari 15",
+    #   #   platform: "iOS 15.0",
+    #   #   mobile: true,
+    #   #   bot: false
+    #   # }
+    #
+    class DeviceDetector
+      # Known bot patterns for security analysis
+      BOT_PATTERNS = %r{
+        bot|crawler|spider|scraper|fetcher|
+        googlebot|bingbot|slurp|duckduckgo|
+        facebookexternalhit|twitterbot|linkedinbot|
+        whatsapp|telegram|discord|
+        curl|wget|postman|httpie|
+        python-requests|ruby|php|java|
+        headless|phantom|selenium|playwright
+      }ix.freeze
+
+      # Mobile device patterns
+      MOBILE_PATTERNS = %r{
+        Mobile|Android|iPhone|iPad|iPod|
+        BlackBerry|IEMobile|Opera\s*Mini|
+        Windows\s*Phone|webOS|Kindle
+      }ix.freeze
+
+      # Browser patterns with version extraction
+      BROWSER_PATTERNS = {
+        chrome: /Chrome\/(\d+(?:\.\d+)*)/i,
+        firefox: /Firefox\/(\d+(?:\.\d+)*)/i,
+        safari: /Version\/(\d+(?:\.\d+)*).+Safari/i,
+        edge: /Edg(?:e|A|iOS)?\/(\d+(?:\.\d+)*)/i,
+        opera: /(?:Opera|OPR)\/(\d+(?:\.\d+)*)/i,
+        internet_explorer: /(?:MSIE\s+|Trident.*rv:)(\d+(?:\.\d+)*)/i
+      }.freeze
+
+      # Platform patterns with version extraction
+      PLATFORM_PATTERNS = {
+        windows: /Windows NT (\d+\.\d+)/i,
+        macos: /Mac OS X (\d+[._]\d+(?:[._]\d+)?)/i,
+        ios: /(?:iPhone|iPad).*OS (\d+[._]\d+(?:[._]\d+)?)/i,
+        android: /Android (\d+(?:\.\d+)*)/i,
+        linux: /Linux/i,
+        chromeos: /CrOS/i
+      }.freeze
+
+      class << self
+        # Convenience method for one-off detection
+        #
+        # @param user_agent [String] The User-Agent string to analyze
+        # @return [Hash] Device information
+        def detect(user_agent)
+          new.detect(user_agent)
+        end
+
+        # Check if a User-Agent represents a mobile device
+        #
+        # @param user_agent [String] The User-Agent string to check
+        # @return [Boolean] true if mobile device
+        def mobile?(user_agent)
+          return false if user_agent.blank?
+          user_agent.match?(MOBILE_PATTERNS)
+        end
+
+        # Check if a User-Agent represents a bot/crawler
+        #
+        # @param user_agent [String] The User-Agent string to check
+        # @return [Boolean] true if bot/crawler
+        def bot?(user_agent)
+          return false if user_agent.blank?
+          user_agent.match?(BOT_PATTERNS)
+        end
+      end
+
+      # Detect comprehensive device information from User-Agent
+      #
+      # @param user_agent [String] The User-Agent string to analyze
+      # @return [Hash] Hash containing browser, platform, mobile, and bot information
+      def detect(user_agent)
+        return empty_result if user_agent.blank?
+
+        {
+          browser: detect_browser(user_agent),
+          platform: detect_platform(user_agent),
+          mobile: mobile?(user_agent),
+          bot: bot?(user_agent),
+          raw_user_agent: truncate_user_agent(user_agent)
+        }.compact
+      end
+
+      # Extract browser information with version
+      #
+      # @param user_agent [String] The User-Agent string
+      # @return [String] Browser name and version, or "Unknown"
+      def detect_browser(user_agent)
+        return "Unknown" if user_agent.blank?
+
+        # Special case: Safari must be detected after Chrome check
+        # because Chrome user agents contain "Safari"
+        # Also check for Opera (OPR) before Chrome since it also contains Chrome
+        if user_agent.match?(/OPR|Opera/i)
+          if match = user_agent.match(BROWSER_PATTERNS[:opera])
+            return "Opera #{match[1]}"
+          end
+        elsif user_agent.match?(/Chrome/i) && !user_agent.match?(/Edg/i)
+          if match = user_agent.match(BROWSER_PATTERNS[:chrome])
+            return "Chrome #{match[1]}"
+          end
+        end
+
+        BROWSER_PATTERNS.each do |browser, pattern|
+          next if browser == :chrome # Already handled above
+
+          if match = user_agent.match(pattern)
+            return "#{browser.to_s.titleize} #{match[1]}"
+          end
+        end
+
+        "Unknown"
+      end
+
+      # Extract platform/operating system information with version
+      #
+      # @param user_agent [String] The User-Agent string
+      # @return [String] Platform name and version, or "Unknown"
+      def detect_platform(user_agent)
+        return "Unknown" if user_agent.blank?
+
+        PLATFORM_PATTERNS.each do |platform, pattern|
+          if match = user_agent.match(pattern)
+            version = match[1]&.tr("_", ".")
+
+            case platform
+            when :windows
+              return "Windows #{version}"
+            when :macos
+              return "macOS #{version}"
+            when :ios
+              return "iOS #{version}"
+            when :android
+              return "Android #{version}"
+            when :linux
+              return "Linux"
+            when :chromeos
+              return "Chrome OS"
+            end
+          end
+        end
+
+        "Unknown"
+      end
+
+      # Check if User-Agent represents a mobile device
+      #
+      # @param user_agent [String] The User-Agent string
+      # @return [Boolean] true if mobile device detected
+      def mobile?(user_agent)
+        self.class.mobile?(user_agent)
+      end
+
+      # Check if User-Agent represents a bot or crawler
+      #
+      # @param user_agent [String] The User-Agent string
+      # @return [Boolean] true if bot/crawler detected
+      def bot?(user_agent)
+        self.class.bot?(user_agent)
+      end
+
+      # Calculate a risk score based on User-Agent characteristics
+      #
+      # @param user_agent [String] The User-Agent string
+      # @return [Integer] Risk score from 0 to 50
+      def calculate_user_agent_risk(user_agent)
+        return 20 if user_agent.blank?
+
+        risk = 0
+
+        # Bot detection adds significant risk
+        if bot?(user_agent)
+                risk += 30
+        Rails.logger.info "Bot detected: #{user_agent}, adding 30 risk"
+        end
+
+        # Suspicious patterns
+        if user_agent.length < 20 || user_agent.length > 500
+                risk += 15
+        Rails.logger.info "Suspicious length: #{user_agent.length}, adding 15 risk"
+        end
+
+        if user_agent.match?(/test|debug|script/i)
+                risk += 10
+        Rails.logger.info "Suspicious pattern: #{user_agent}, adding 10 risk"
+        end
+
+        if user_agent.count("()") > 3
+                risk += 5
+        Rails.logger.info "Suspicious pattern: #{user_agent}, adding 5 risk"
+        end
+
+        # Very old browsers might be suspicious
+        if browser_info = detect_browser(user_agent)
+          if browser_info.match?(/Chrome (\d+)/) && $1.to_i < 90
+            risk += 5
+            Rails.logger.info "Suspicious browser: #{browser_info}, adding 5 risk"
+          elsif browser_info.match?(/Firefox (\d+)/) && $1.to_i < 90
+            risk += 5
+            Rails.logger.info "Suspicious browser: #{browser_info}, adding 5 risk"
+          end
+        end
+
+        [ risk, 50 ].min # Cap at 50 to leave room for other risk factors
+      end
+
+      private
+
+      # Return empty result structure
+      #
+      # @return [Hash] Empty device information
+      def empty_result
+        {
+          browser: "Unknown",
+          platform: "Unknown",
+          mobile: false,
+          bot: false
+        }
+      end
+
+      # Truncate user agent for storage (prevent DoS via long strings)
+      #
+      # @param user_agent [String] The User-Agent string
+      # @return [String] Truncated user agent (max 500 chars)
+      def truncate_user_agent(user_agent)
+        return user_agent if user_agent.length <= 500
+        "#{user_agent[0..496]}..."
+      end
+    end
+  end
+end

data/lib/beskar/services/geolocation_service.rb

@@ -0,0 +1,392 @@
+# frozen_string_literal: true
+
+begin
+  require 'maxminddb'
+rescue LoadError
+  # MaxMindDB gem not available
+end
+
+module Beskar
+  module Services
+    # Service for detecting geographic location from IP addresses
+    #
+    # This service provides IP-based geolocation capabilities for security analysis,
+    # impossible travel detection, and geographic anomaly detection.
+    #
+    # Features:
+    # - Efficient MaxMind database reading with singleton pattern
+    # - Automatic caching with configurable TTL
+    # - Private IP detection
+    # - Impossible travel detection using Haversine formula
+    #
+    # @example Basic usage
+    #   service = Beskar::Services::GeolocationService.new
+    #   location = service.locate("203.0.113.1")
+    #   # => {
+    #   #   ip: "203.0.113.1",
+    #   #   country: "United States",
+    #   #   country_code: "US",
+    #   #   city: "New York",
+    #   #   latitude: 40.7128,
+    #   #   longitude: -74.0060,
+    #   #   timezone: "America/New_York"
+    #   # }
+    #
+    class GeolocationService
+      # Private/internal IP ranges that should not be geolocated
+      PRIVATE_IP_RANGES = [
+        IPAddr.new('10.0.0.0/8'),      # RFC 1918 - Private networks
+        IPAddr.new('172.16.0.0/12'),   # RFC 1918 - Private networks
+        IPAddr.new('192.168.0.0/16'),  # RFC 1918 - Private networks
+        IPAddr.new('127.0.0.0/8'),     # Loopback
+        IPAddr.new('169.254.0.0/16'),  # Link-local
+        IPAddr.new('224.0.0.0/4'),     # Multicast
+        IPAddr.new('::1/128'),         # IPv6 loopback
+        IPAddr.new('fe80::/10'),       # IPv6 link-local
+        IPAddr.new('fc00::/7')         # IPv6 unique local
+      ].freeze
+
+      # Cache TTL for geolocation results (4 hours)
+      CACHE_TTL = 4.hours
+
+      # Thread-safe reader for MaxMind City database
+      @city_reader_mutex = Mutex.new
+      @city_reader = nil
+
+      class << self
+        attr_reader :city_reader_mutex
+        # Convenience method for one-off location lookup
+        #
+        # @param ip_address [String] The IP address to locate
+        # @return [Hash] Location information
+        def locate(ip_address)
+          new.locate(ip_address)
+        end
+
+        # Check if an IP address is private/internal
+        #
+        # @param ip_address [String] The IP address to check
+        # @return [Boolean] true if private/internal IP
+        def private_ip?(ip_address)
+          return true if ip_address.blank?
+
+          begin
+            ip = IPAddr.new(ip_address)
+            PRIVATE_IP_RANGES.any? { |range| range.include?(ip) }
+          rescue IPAddr::InvalidAddressError
+            true # Treat invalid IPs as private
+          end
+        end
+
+        # Calculate distance between two geographic points using Haversine formula
+        #
+        # @param lat1 [Float] Latitude of first point
+        # @param lon1 [Float] Longitude of first point
+        # @param lat2 [Float] Latitude of second point
+        # @param lon2 [Float] Longitude of second point
+        # @return [Float] Distance in kilometers
+        def calculate_distance(lat1, lon1, lat2, lon2)
+          return 0.0 if lat1.nil? || lon1.nil? || lat2.nil? || lon2.nil?
+
+          # Convert degrees to radians
+          lat1_rad = lat1 * Math::PI / 180
+          lon1_rad = lon1 * Math::PI / 180
+          lat2_rad = lat2 * Math::PI / 180
+          lon2_rad = lon2 * Math::PI / 180
+
+          # Haversine formula
+          dlat = lat2_rad - lat1_rad
+          dlon = lon2_rad - lon1_rad
+
+          a = Math.sin(dlat/2)**2 + Math.cos(lat1_rad) * Math.cos(lat2_rad) * Math.sin(dlon/2)**2
+          c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a))
+
+          # Earth's radius in kilometers
+          earth_radius = 6371.0
+          earth_radius * c
+        end
+      end
+
+      # Get or initialize the MaxMind City database reader
+      # Uses thread-safe singleton pattern for efficient database access
+      #
+      # @return [MaxMindDB::Reader, nil] The reader instance or nil if not configured
+      def self.city_reader
+        return @city_reader if @city_reader
+        return nil unless Beskar.configuration.maxmind_city_db_path
+        return nil unless defined?(MaxMindDB)
+
+        @city_reader_mutex.synchronize do
+          return @city_reader if @city_reader
+
+          db_path = Beskar.configuration.maxmind_city_db_path
+          if File.exist?(db_path)
+            @city_reader = MaxMindDB.new(db_path)
+            Beskar::Logger.info("MaxMind City database loaded from #{db_path}", component: :GeolocationService)
+          else
+            Beskar::Logger.warn("MaxMind City database not found at #{db_path}", component: :GeolocationService)
+          end
+          @city_reader
+        end
+      rescue => e
+        Beskar::Logger.error("Failed to load MaxMind City database: #{e.message}", component: :GeolocationService)
+        nil
+      end
+
+      # Reset the database reader (useful for testing or reloading configuration)
+      def self.reset_readers!
+        @city_reader_mutex.synchronize { @city_reader = nil }
+      end
+
+      # Initialize the geolocation service
+      #
+      # @param provider [Symbol] The geolocation provider to use (:maxmind, :mock)
+      def initialize(provider: nil)
+        @provider = provider || Beskar.configuration.geolocation_provider
+        @cache_key_prefix = "beskar:geolocation"
+        @cache_ttl = Beskar.configuration.geolocation_cache_ttl
+      end
+
+      # Locate an IP address and return geographic information
+      #
+      # @param ip_address [String] The IP address to locate
+      # @return [Hash] Location information with country, city, coordinates, etc.
+      def locate(ip_address)
+        if self.class.private_ip?(ip_address)
+          result = private_ip_result(ip_address)
+          result[:provider] = @provider
+          return result
+        end
+
+        # Check cache first
+        if cached_result = get_cached_location(ip_address)
+          return cached_result
+        end
+
+        # Perform lookup based on provider
+        case @provider
+        when :maxmind
+          result = lookup_maxmind(ip_address)
+        when :ip2location
+          result = lookup_ip2location(ip_address)
+        else
+          result = lookup_mock(ip_address)
+        end
+
+        # Cache the result
+        cache_location(ip_address, result)
+
+        result
+      rescue => e
+        Beskar::Logger.warn("Failed to locate IP #{ip_address}: #{e.message}", component: :GeolocationService)
+        unknown_location(ip_address)
+      end
+
+      # Check if travel between two locations is impossible given the time difference
+      #
+      # @param location1 [Hash] First location with latitude/longitude
+      # @param location2 [Hash] Second location with latitude/longitude
+      # @param time_diff_seconds [Integer] Time difference in seconds
+      # @param max_speed_kmh [Integer] Maximum realistic travel speed in km/h (default: 1000 for commercial flights)
+      # @return [Boolean] true if travel is impossible
+      def impossible_travel?(location1, location2, time_diff_seconds, max_speed_kmh: 1000)
+        return false if location1.nil? || location2.nil?
+        return false unless location1[:latitude] && location2[:latitude]
+
+        distance_km = self.class.calculate_distance(
+          location1[:latitude], location1[:longitude],
+          location2[:latitude], location2[:longitude]
+        )
+
+        # Calculate maximum possible distance at given speed
+        time_hours = time_diff_seconds / 3600.0
+        max_distance_km = max_speed_kmh * time_hours
+
+        distance_km > max_distance_km
+      end
+
+      # Calculate risk score based on geolocation factors
+      #
+      # @param ip_address [String] The IP address
+      # @param previous_locations [Array<Hash>] Array of previous location hashes
+      # @param time_since_last [Integer] Seconds since last login
+      # @return [Integer] Risk score from 0 to 30
+      def calculate_location_risk(ip_address, previous_locations = [], time_since_last = nil)
+        current_location = locate(ip_address)
+        risk = 0
+
+        # Private/unknown IPs have moderate risk
+        return 10 if current_location[:country] == "Unknown" || current_location[:country] == "Private"
+
+        # Check for impossible travel if we have previous locations
+        if previous_locations.any? && time_since_last
+          previous_locations.each do |prev_location|
+            if impossible_travel?(current_location, prev_location, time_since_last)
+              risk += 25
+              break
+            end
+          end
+        end
+
+        # Country change adds some risk
+        if previous_locations.any?
+          recent_countries = previous_locations.map { |loc| loc[:country] }.uniq
+          risk += 10 unless recent_countries.include?(current_location[:country])
+        end
+
+        # Known high-risk countries (this would be configurable in production)
+        high_risk_countries = ['Unknown']
+        risk += 15 if high_risk_countries.include?(current_location[:country])
+
+        [risk, 30].min # Cap at 30 to leave room for other risk factors
+      end
+
+      private
+
+      # Return result for private/internal IP addresses
+      #
+      # @param ip_address [String] The private IP address
+      # @return [Hash] Location information for private IP
+      def private_ip_result(ip_address)
+        {
+          ip: ip_address,
+          country: "Private",
+          country_code: nil,
+          city: "Local Network",
+          latitude: nil,
+          longitude: nil,
+          timezone: nil,
+          provider: @provider,
+          private_ip: true
+        }
+      end
+
+      # Return result for unknown/unlocatable IP addresses
+      #
+      # @param ip_address [String] The IP address
+      # @return [Hash] Unknown location information
+      def unknown_location(ip_address)
+        {
+          ip: ip_address,
+          country: "Unknown",
+          country_code: nil,
+          city: "Unknown",
+          latitude: nil,
+          longitude: nil,
+          timezone: nil,
+          provider: @provider,
+          private_ip: false
+        }
+      end
+
+      # Mock geolocation lookup for testing/development
+      #
+      # @param ip_address [String] The IP address
+      # @return [Hash] Mock location information
+      def lookup_mock(ip_address)
+        # Generate consistent mock data based on IP
+        country_codes = ['US', 'CA', 'GB', 'DE', 'FR', 'JP', 'AU']
+        cities = ['New York', 'Toronto', 'London', 'Berlin', 'Paris', 'Tokyo', 'Sydney']
+
+        index = ip_address.bytes.sum % country_codes.length
+
+        {
+          ip: ip_address,
+          country: case country_codes[index]
+                   when 'US' then 'United States'
+                   when 'CA' then 'Canada'
+                   when 'GB' then 'United Kingdom'
+                   when 'DE' then 'Germany'
+                   when 'FR' then 'France'
+                   when 'JP' then 'Japan'
+                   when 'AU' then 'Australia'
+                   end,
+          country_code: country_codes[index],
+          city: cities[index],
+          latitude: (40.0 + (index * 10)) % 90,
+          longitude: (-74.0 + (index * 15)) % 180,
+          timezone: "UTC#{index > 3 ? '+' : '-'}#{index + 1}",
+          provider: @provider,
+          private_ip: false
+        }
+      end
+
+      # Lookup using MaxMind GeoIP2 database
+      #
+      # @param ip_address [String] The IP address
+      # @return [Hash] Location information from MaxMind
+      def lookup_maxmind(ip_address)
+        result = { ip: ip_address, provider: @provider, private_ip: false }
+
+        # Lookup city/location data
+        if city_reader = self.class.city_reader
+          begin
+            city_data = city_reader.lookup(ip_address)
+            if city_data&.found?
+              city_hash = city_data.to_hash
+              result.merge!(
+                country: city_hash.dig("country", "names", "en") || "Unknown",
+                country_code: city_hash.dig("country", "iso_code"),
+                city: city_hash.dig("city", "names", "en") || "Unknown",
+                latitude: city_hash.dig("location", "latitude"),
+                longitude: city_hash.dig("location", "longitude"),
+                timezone: city_hash.dig("location", "time_zone"),
+                postal_code: city_hash.dig("postal", "code"),
+                subdivision: city_hash.dig("subdivisions", 0, "names", "en"),
+                subdivision_code: city_hash.dig("subdivisions", 0, "iso_code")
+              )
+            else
+              result.merge!(unknown_location(ip_address).except(:ip, :provider, :private_ip))
+            end
+          rescue => e
+            Beskar::Logger.warn("MaxMind City lookup failed for #{ip_address}: #{e.message}", component: :GeolocationService)
+            result.merge!(unknown_location(ip_address).except(:ip, :provider, :private_ip))
+          end
+        else
+          # No city database configured, return basic unknown location
+          result.merge!(unknown_location(ip_address).except(:ip, :provider, :private_ip))
+        end
+
+        result
+      rescue => e
+        Beskar::Logger.error("MaxMind lookup failed for #{ip_address}: #{e.message}", component: :GeolocationService)
+        unknown_location(ip_address)
+      end
+
+      # Lookup using IP2Location database
+      #
+      # @param ip_address [String] The IP address
+      # @return [Hash] Location information from IP2Location
+      def lookup_ip2location(ip_address)
+        # This would integrate with IP2Location in production
+        # For now, return unknown result
+        result = unknown_location(ip_address)
+        result[:provider] = @provider
+        result
+      end
+
+      # Get cached location result
+      #
+      # @param ip_address [String] The IP address
+      # @return [Hash, nil] Cached location or nil
+      def get_cached_location(ip_address)
+        cache_key = "#{@cache_key_prefix}:#{ip_address}"
+        Rails.cache.read(cache_key)
+      rescue => e
+        Beskar::Logger.debug("Cache read failed: #{e.message}", component: :GeolocationService)
+        nil
+      end
+
+      # Cache location result
+      #
+      # @param ip_address [String] The IP address
+      # @param result [Hash] The location result to cache
+      def cache_location(ip_address, result)
+        cache_key = "#{@cache_key_prefix}:#{ip_address}"
+        Rails.cache.write(cache_key, result, expires_in: @cache_ttl)
+      rescue => e
+        Beskar::Logger.debug("Cache write failed: #{e.message}", component: :GeolocationService)
+      end
+    end
+  end
+end