reputable 0.1.16 → 0.1.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d33fb1c68fdaca4082540ed61021d61ec5d687779c6c290635327dfe58a83ec7
-  data.tar.gz: 8a217cc36dcc8eef21623025b2dca9b0ccd697b1a312fd46bcfa814c7958e189
+  metadata.gz: 40be87edb5494144f499f263572e00d98331cd07913239fca32b5ce71450df26
+  data.tar.gz: 63cfe644b94396a6d72b05a75a45076e8bc41196f6c4970307992e6260d6f86f
 SHA512:
-  metadata.gz: d9470847736221d9aa4b0c0012487f18b32ed15bba2f22d5e85bbcd3f376263aa66899b8e14eda2058b0aa0e52e1c659845a516dee09709f379d9ef660cd2ed4
-  data.tar.gz: 879cc235f75b50f054db621572dbd2dfb58020102bc784d14fed109b921bfa82a4f91f0fe4fff7c7c3f2811ff0f292d5638ab2864323bcf93ddbcd18ecf18a3c
+  metadata.gz: ed8aee9a76c98611718621fde0c1dada4aff7449092c9fc6cd1990d545b91ee1641c169d841eea12b2b0eeb56edc399e2f8db612041565a2d90dbf76bad34d92
+  data.tar.gz: 5b2eeb4fb8ddbf12beeb989b0a33aa5f42352c6a131ca1211ad5475b19978ba8244dbf52504555256aa0d79eb58935ab23be05cd503405d11d35b835bca506c0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    reputable (0.1.15)
+    reputable (0.1.18)
       connection_pool (~> 2.2)
       redis (>= 4.0, < 6.0)
 

data/README.md

@@ -275,6 +275,10 @@ config.middleware.use Reputable::Middleware,
   # Falls back to ENV REPUTABLE_TRACK_REQUEST if not set
   track_request: true,
 
+  # Ignore XHR requests (default: false)
+  # Useful for suppressing tracking of background widgets or polling
+  ignore_xhr: true,
+
   # Expose reputation flags in request env for views/controllers (default: true)
   # Sets request.env['reputable.ignore_analytics'] for any untrusted_* status
   expose_reputation: true
@@ -301,6 +305,44 @@ Notes:
 - Use `blocked_page_path` only for local blocked pages (or to build a custom `failure_url`).
 - Override `challenge_redirect_status` (default `302`) or `verification_force_challenge` if needed.
 
+### ASN Fallback
+
+When an IP has no reputation, the middleware can fall back to checking ASN reputation. This is useful for blocking/challenging entire ASNs (e.g., datacenter ASNs known for abuse).
+
+**Enable via environment variable:**
+```bash
+REPUTABLE_ASN_FALLBACK=true
+REPUTABLE_ASN_HEADER=HTTP_X_ASN  # Optional, defaults to HTTP_X_ASN
+```
+
+**Enable via configuration:**
+```ruby
+Reputable.configure do |config|
+  config.asn_fallback = true
+  config.asn_header = "HTTP_X_ASN"  # Or HTTP_CF_ASN for Cloudflare, etc.
+end
+```
+
+**Enable via middleware option:**
+```ruby
+config.middleware.use Reputable::Middleware,
+  reputation_gate: true,
+  asn_fallback: true
+```
+
+**How it works:**
+1. Middleware looks up IP reputation first
+2. If IP has no reputation and ASN fallback is enabled, it extracts ASN from the configured header
+3. If ASN has a reputation (blocked, challenged), that decision is applied
+4. The `env['reputable.reputation_source']` is set to `'asn'` when using ASN-based decision
+
+**Providing ASN from your app:**
+If your app has its own GeoIP lookup, set the ASN directly:
+```ruby
+# In a before_action or middleware
+request.env['reputable.asn'] = lookup_asn_for_ip(request.remote_ip)
+```
+
 ### Server/JS Request Reconciliation
 
 When using both server-side tracking (Rack middleware) and client-side JavaScript tracking, requests can be double-counted. The reconciliation system prevents this by correlating requests using a unique `request_id`.
@@ -497,6 +539,33 @@ Reputable.lookup_reputation(:ip, request.ip)
 #      expires_at: 0, metadata: { order_id: "123" } }
 ```
 
+### ASN Reputation
+
+Apply and lookup reputations for entire ASNs (Autonomous System Numbers). Useful for blocking datacenter traffic or known-bad networks.
+
+```ruby
+# Apply reputation to an ASN
+Reputable.block_asn("15169", reason: "datacenter_abuse")
+Reputable.challenge_asn("7922", reason: "suspicious_traffic")
+Reputable.trust_asn("16509", reason: "known_partner")
+Reputable.ignore_asn("32934", reason: "internal_monitoring")
+
+# Quick boolean checks
+Reputable.blocked_asn?("15169")    # => true/false
+Reputable.challenged_asn?("7922")  # => true/false
+Reputable.trusted_asn?("16509")    # => true/false
+
+# Get status string
+Reputable.lookup_asn("15169")
+# => "untrusted_block" or nil
+
+# Full lookup with metadata
+Reputable.lookup_reputation(:asn, "15169")
+# => { status: "untrusted_block", reason: "datacenter_abuse", ... }
+```
+
+**Note:** ASNs are normalized automatically - both `"15169"` and `"AS15169"` work.
+
 ---
 
 ## User Verification & Trust Flow

data/lib/reputable/configuration.rb

@@ -15,7 +15,8 @@ module Reputable
                   :connect_timeout, :read_timeout, :write_timeout,
                   :ssl_params, :trusted_proxies, :ip_header_priority,
                   :on_error, :trusted_keys, :base_url,
-                  :site_name, :support_email, :support_url
+                  :site_name, :support_email, :support_url,
+                  :asn_fallback, :asn_header
 
     # Alias for backward compatibility
     alias_method :verification_base_url, :base_url
@@ -82,6 +83,10 @@ module Reputable
       @site_name = ENV["REPUTABLE_SITE_NAME"]
       @support_email = ENV["REPUTABLE_SUPPORT_EMAIL"]
       @support_url = ENV["REPUTABLE_SUPPORT_URL"]
+      
+      # ASN fallback: when IP has no reputation, check ASN reputation
+      @asn_fallback = env_truthy?("REPUTABLE_ASN_FALLBACK")
+      @asn_header = ENV.fetch("REPUTABLE_ASN_HEADER", "HTTP_X_ASN")
     end
 
     # Alias for backward compatibility
@@ -158,5 +163,20 @@ module Reputable
     rescue IPAddr::InvalidAddressError
       false
     end
+
+    # Check if ASN fallback is enabled
+    def asn_fallback?
+      @asn_fallback
+    end
+
+    private
+
+    # Helper to check if an environment variable is truthy
+    def env_truthy?(name)
+      value = ENV[name]
+      return false if value.nil?
+      
+      %w[1 true yes on enabled].include?(value.to_s.downcase)
+    end
   end
 end

data/lib/reputable/middleware.rb

@@ -59,6 +59,8 @@ module Reputable
       @verified_session_keys = Array(options.fetch(:verified_session_keys, [:reputable_verified_at, :reputable_verified]))
       @blocked_page_options = options.fetch(:blocked_page, {})
       @blocked_page_path = options[:blocked_page_path]
+      @ignore_xhr = options.fetch(:ignore_xhr, false)
+      @asn_fallback = options.key?(:asn_fallback) ? options[:asn_fallback] : nil
     end
 
     def call(env)
@@ -317,6 +319,17 @@ module Reputable
       ip = extract_ip(env)
       env["reputable.ip"] = ip
       status = Reputable::Reputation.lookup_ip(ip)
+      
+      # Fallback to ASN reputation if IP has no status and ASN fallback is enabled
+      if status.nil? && asn_fallback_enabled?
+        asn = extract_asn(env)
+        if asn
+          env["reputable.asn"] = asn
+          status = Reputable::Reputation.lookup_asn(asn)
+          env["reputable.reputation_source"] = "asn" if status
+        end
+      end
+      
       env["reputable.reputation_status"] = status
       env["reputable.ignore_analytics"] = status.to_s.start_with?("untrusted")
       status
@@ -326,6 +339,28 @@ module Reputable
       nil
     end
 
+    def asn_fallback_enabled?
+      # Middleware option takes precedence, then config
+      return @asn_fallback unless @asn_fallback.nil?
+      
+      Reputable.configuration.asn_fallback?
+    end
+
+    def extract_asn(env)
+      # First check if app explicitly set it
+      return env["reputable.asn"] if env["reputable.asn"]
+      
+      # Then check the configured header
+      header = Reputable.configuration.asn_header
+      value = env[header]
+      return nil if value.nil? || value.empty?
+      
+      # Normalize: strip "AS" prefix if present
+      value.to_s.strip.sub(/^AS/i, "")
+    rescue StandardError
+      nil
+    end
+
     def blocked_page_options
       config = Reputable.configuration
       defaults = {
@@ -356,6 +391,7 @@ module Reputable
 
     def skip_request?(env)
       return true if @skip_if&.call(env)
+      return true if @ignore_xhr && xhr_request?(env)
 
       path = env["PATH_INFO"] || "/"
 
@@ -522,5 +558,9 @@ module Reputable
     rescue StandardError
       nil
     end
+
+    def xhr_request?(env)
+      env["HTTP_X_REQUESTED_WITH"].to_s.downcase == "xmlhttprequest"
+    end
   end
 end

data/lib/reputable/reputation.rb

@@ -205,8 +205,113 @@ module Reputable
         lookup_ip(ip) == "untrusted_challenge"
       end
 
+      # ========================================================================
+      # ASN LOOKUP METHODS
+      # ========================================================================
+
+      # Quick lookup for ASN reputation status
+      # Returns just the status string (or nil)
+      # ASN is normalized (strips "AS" prefix if present)
+      #
+      # @param asn [String] ASN (e.g., "15169" or "AS15169")
+      # @return [String, nil] Status string or nil
+      #
+      # @example
+      #   status = Reputable::Reputation.lookup_asn("15169")
+      #   # => "untrusted_block" or nil
+      def lookup_asn(asn)
+        result = lookup(:asn, normalize_asn(asn))
+        result&.dig(:status)
+      end
+
+      # Check if an ASN is trusted (any trusted_* status)
+      #
+      # @param asn [String] ASN
+      # @return [Boolean] Returns false if disabled, nil lookup, or not trusted
+      def trusted_asn?(asn)
+        status = lookup_asn(asn)
+        return false if status.nil?
+        
+        status.start_with?("trusted")
+      end
+
+      # Check if an ASN should be blocked
+      #
+      # @param asn [String] ASN
+      # @return [Boolean]
+      def blocked_asn?(asn)
+        lookup_asn(asn) == "untrusted_block"
+      end
+
+      # Check if an ASN should be challenged
+      #
+      # @param asn [String] ASN
+      # @return [Boolean]
+      def challenged_asn?(asn)
+        lookup_asn(asn) == "untrusted_challenge"
+      end
+
+      # ========================================================================
+      # ASN APPLY CONVENIENCE METHODS
+      # ========================================================================
+
+      # Convenience method: Trust an ASN (behavioral by default)
+      def trust_asn(asn, reason: "manual_trust", status: :trusted_behavior, ttl: nil, **metadata)
+        apply(
+          entity_type: :asn,
+          entity_id: normalize_asn(asn),
+          status: status,
+          reason: reason,
+          ttl: ttl,
+          metadata: metadata
+        )
+      end
+
+      # Convenience method: Block an ASN
+      def block_asn(asn, reason: "manual_block", ttl: nil, **metadata)
+        apply(
+          entity_type: :asn,
+          entity_id: normalize_asn(asn),
+          status: :untrusted_block,
+          reason: reason,
+          ttl: ttl,
+          metadata: metadata
+        )
+      end
+
+      # Convenience method: Challenge an ASN (CAPTCHA, etc.)
+      def challenge_asn(asn, reason: "suspicious_traffic", ttl: nil, **metadata)
+        apply(
+          entity_type: :asn,
+          entity_id: normalize_asn(asn),
+          status: :untrusted_challenge,
+          reason: reason,
+          ttl: ttl,
+          metadata: metadata
+        )
+      end
+
+      # Convenience method: Mark ASN to be ignored in analytics
+      def ignore_asn(asn, reason: "datacenter_traffic", ttl: nil, **metadata)
+        apply(
+          entity_type: :asn,
+          entity_id: normalize_asn(asn),
+          status: :untrusted_ignore,
+          reason: reason,
+          ttl: ttl,
+          metadata: metadata
+        )
+      end
+
       private
 
+      # Normalize ASN by stripping "AS" prefix if present
+      # @param asn [String] ASN with or without prefix
+      # @return [String] ASN without prefix
+      def normalize_asn(asn)
+        asn.to_s.sub(/^AS/i, "")
+      end
+
       def valid_entity_type?(entity_type)
         VALID_ENTITY_TYPES.include?(entity_type.to_sym)
       end

data/lib/reputable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Reputable
-  VERSION = "0.1.16"
+  VERSION = "0.1.18"
 end

data/lib/reputable.rb

@@ -126,6 +126,39 @@ module Reputable
       Reputation.challenged_ip?(ip)
     end
 
+    # Delegate ASN reputation methods to Reputation module
+    def lookup_asn(asn)
+      Reputation.lookup_asn(asn)
+    end
+
+    def trusted_asn?(asn)
+      Reputation.trusted_asn?(asn)
+    end
+
+    def blocked_asn?(asn)
+      Reputation.blocked_asn?(asn)
+    end
+
+    def challenged_asn?(asn)
+      Reputation.challenged_asn?(asn)
+    end
+
+    def trust_asn(asn, reason: "manual_trust", status: :trusted_behavior, ttl: nil, **metadata)
+      Reputation.trust_asn(asn, reason: reason, status: status, ttl: ttl, **metadata)
+    end
+
+    def block_asn(asn, reason: "manual_block", ttl: nil, **metadata)
+      Reputation.block_asn(asn, reason: reason, ttl: ttl, **metadata)
+    end
+
+    def challenge_asn(asn, reason: "suspicious_traffic", ttl: nil, **metadata)
+      Reputation.challenge_asn(asn, reason: reason, ttl: ttl, **metadata)
+    end
+
+    def ignore_asn(asn, reason: "datacenter_traffic", ttl: nil, **metadata)
+      Reputation.ignore_asn(asn, reason: reason, ttl: ttl, **metadata)
+    end
+
     # Generate a signed verification URL
     # @param return_url [String] URL to redirect to after successful verification
     # @param failure_url [String, nil] URL to redirect to on failure (optional)

data/reputable.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/reputable/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "reputable"
+  spec.version = Reputable::VERSION
+  spec.authors = ["Reputable"]
+  spec.email = ["support@reputable.click"]
+
+  spec.summary = "Ruby client for Reputable - bot detection and reputation scoring"
+  spec.description = "Track requests and manage IP reputation through Redis/Dragonfly integration with Reputable"
+  spec.homepage = "https://github.com/reputable-click/reputable-rb"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)}) || f.end_with?(".gem")
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "redis", ">= 4.0", "< 6.0"
+  spec.add_dependency "connection_pool", "~> 2.2"
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rack", "~> 2.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reputable
 version: !ruby/object:Gem::Version
-  version: 0.1.16
+  version: 0.1.18
 platform: ruby
 authors:
 - Reputable
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-29 00:00:00.000000000 Z
+date: 2026-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -137,6 +137,7 @@ files:
 - lib/reputable/reputation.rb
 - lib/reputable/tracker.rb
 - lib/reputable/version.rb
+- reputable.gemspec
 homepage: https://github.com/reputable-click/reputable-rb
 licenses:
 - MIT