reputable 0.1.17 → 0.1.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8767ca87c7fdd5abc6584e738599020cbd6977bc6193371caeef1425eedb8dfd
-  data.tar.gz: 5196f00349ec3b380bec72db3b98c5f09d08965d297e7f43a8c639b9d1eed3dd
+  metadata.gz: 40be87edb5494144f499f263572e00d98331cd07913239fca32b5ce71450df26
+  data.tar.gz: 63cfe644b94396a6d72b05a75a45076e8bc41196f6c4970307992e6260d6f86f
 SHA512:
-  metadata.gz: 36285df97965903af8e913d3f0937969ae4e48399f0468fd2e00b22d3b0e7c6d50d51682d9ec82a31483729ca7f0d69d4d0ec47115b12dce62ff01948d18b3ec
-  data.tar.gz: 6aea15486988795b5ce444581be796e33d15906c871f5cc28208d876b0604053603f455f8d16536b4879773991905f85882f56b4fed47d85b71b1ea9abb34a42
+  metadata.gz: ed8aee9a76c98611718621fde0c1dada4aff7449092c9fc6cd1990d545b91ee1641c169d841eea12b2b0eeb56edc399e2f8db612041565a2d90dbf76bad34d92
+  data.tar.gz: 5b2eeb4fb8ddbf12beeb989b0a33aa5f42352c6a131ca1211ad5475b19978ba8244dbf52504555256aa0d79eb58935ab23be05cd503405d11d35b835bca506c0

data/Gemfile.lock

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

data/README.md

@@ -305,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`.
@@ -501,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

@@ -60,6 +60,7 @@ module Reputable
       @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)
@@ -318,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
@@ -327,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 = {

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.17"
+  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)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reputable
 version: !ruby/object:Gem::Version
-  version: 0.1.17
+  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