Add IP risk and anonymizer outputs to Insights

oschwald · claude · oschwald · commit 846e55c3e929 · 2025-11-07T13:06:03.000-08:00
This adds support for new risk and anonymizer data fields available in the GeoIP2 Insights web service: - New anonymizer object with VPN confidence scoring, provider name detection, and network last seen date - New ip_risk_snapshot field in traits for static IP risk scoring - Deprecated anonymizer-related methods in traits (anonymous?, anonymous_vpn?, hosting_provider?, public_proxy?, residential_proxy?, and tor_exit_node?) in favor of the new anonymizer object The deprecated methods continue to work for backward compatibility but direct users to the new anonymizer object location. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.5.0
+
+* A new `anonymizer` object has been added to the `MaxMind::GeoIP2::Model::Insights`
+  model. This object indicates whether the IP address is part of an anonymizing
+  network, including VPN confidence scoring, provider name detection, and network
+  last seen date. This is only available from the GeoIP2 Insights web service.
+* A new `ip_risk_snapshot` method has been added to `MaxMind::GeoIP2::Record::Traits`.
+  This field contains the risk associated with the IP address, ranging from 0.01 to
+  99 (a higher score indicates a higher risk). This is only available from the GeoIP2
+  Insights web service.
+* The `anonymous?`, `anonymous_vpn?`, `hosting_provider?`, `public_proxy?`,
+  `residential_proxy?`, and `tor_exit_node?` methods in
+  `MaxMind::GeoIP2::Record::Traits` have been deprecated. Please use the
+  corresponding methods in the `anonymizer` object from the GeoIP2 Insights
+  response instead.
+
 ## 1.4.0
 
 * Ruby 3.2+ is now required. If you're using Ruby 3.0 or 3.1, please use
diff --git a/lib/maxmind/geoip2/model/insights.rb b/lib/maxmind/geoip2/model/insights.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'maxmind/geoip2/model/city'
+require 'maxmind/geoip2/record/anonymizer'
 
 module MaxMind
   module GeoIP2
@@ -10,6 +11,19 @@ module Model
       # See https://dev.maxmind.com/geoip/docs/web-services?lang=en for more
       # details.
       class Insights < City
+        # Data indicating whether the IP address is part of an anonymizing
+        # network.
+        #
+        # @return [MaxMind::GeoIP2::Record::Anonymizer]
+        attr_reader :anonymizer
+
+        # @!visibility private
+        def initialize(record, locales)
+          super
+          @anonymizer = MaxMind::GeoIP2::Record::Anonymizer.new(
+            record['anonymizer'],
+          )
+        end
       end
     end
   end
diff --git a/lib/maxmind/geoip2/record/anonymizer.rb b/lib/maxmind/geoip2/record/anonymizer.rb
@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'maxmind/geoip2/record/abstract'
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # Contains data indicating whether an IP address is part of an
+      # anonymizing network.
+      #
+      # This record is returned by the Insights web service.
+      class Anonymizer < Abstract
+        # A score ranging from 1 to 99 that represents our percent confidence
+        # that the network is currently part of an actively used VPN service.
+        # This property is only available from Insights.
+        #
+        # @return [Integer, nil]
+        def confidence
+          get('confidence')
+        end
+
+        # This is true if the IP address belongs to any sort of anonymous
+        # network. This property is only available from Insights.
+        #
+        # @return [Boolean]
+        def anonymous?
+          get('is_anonymous')
+        end
+
+        # This is true if the IP address is registered to an anonymous VPN
+        # provider. If a VPN provider does not register subnets under names
+        # associated with them, we will likely only flag their IP ranges using
+        # the hosting_provider? property. This property is only available from
+        # Insights.
+        #
+        # @return [Boolean]
+        def anonymous_vpn?
+          get('is_anonymous_vpn')
+        end
+
+        # This is true if the IP address belongs to a hosting or VPN provider
+        # (see description of the anonymous_vpn? property). This property is
+        # only available from Insights.
+        #
+        # @return [Boolean]
+        def hosting_provider?
+          get('is_hosting_provider')
+        end
+
+        # This is true if the IP address belongs to a public proxy. This
+        # property is only available from Insights.
+        #
+        # @return [Boolean]
+        def public_proxy?
+          get('is_public_proxy')
+        end
+
+        # This is true if the IP address is on a suspected anonymizing network
+        # and belongs to a residential ISP. This property is only available from
+        # Insights.
+        #
+        # @return [Boolean]
+        def residential_proxy?
+          get('is_residential_proxy')
+        end
+
+        # This is true if the IP address is a Tor exit node. This property is
+        # only available from Insights.
+        #
+        # @return [Boolean]
+        def tor_exit_node?
+          get('is_tor_exit_node')
+        end
+
+        # The last day that the network was sighted in our analysis of
+        # anonymized networks. This value is parsed lazily. This property is
+        # only available from Insights.
+        #
+        # @return [Date, nil] A Date object representing the last seen date,
+        #   or nil if the date is not available.
+        def network_last_seen
+          return @network_last_seen if defined?(@network_last_seen)
+
+          date_string = get('network_last_seen')
+
+          if !date_string
+            return nil
+          end
+
+          @network_last_seen = Date.parse(date_string)
+        end
+
+        # The name of the VPN provider (e.g., NordVPN, SurfShark, etc.)
+        # associated with the network. This property is only available from
+        # Insights.
+        #
+        # @return [String, nil]
+        def provider_name
+          get('provider_name')
+        end
+      end
+    end
+  end
+end
diff --git a/lib/maxmind/geoip2/record/traits.rb b/lib/maxmind/geoip2/record/traits.rb
@@ -76,7 +76,11 @@ def ip_address
         # This is true if the IP address belongs to any sort of anonymous network.
         # This property is only available from Insights.
         #
+        # This method is deprecated as of version 1.5.0. Use the anonymizer object
+        # from the Insights response instead.
+        #
         # @return [Boolean]
+        # @deprecated since 1.5.0
         def anonymous?
           get('is_anonymous')
         end
@@ -86,7 +90,11 @@ def anonymous?
         # associated with them, we will likely only flag their IP ranges using the
         # hosting_provider? property. This property is only available from Insights.
         #
+        # This method is deprecated as of version 1.5.0. Use the anonymizer object
+        # from the Insights response instead.
+        #
         # @return [Boolean]
+        # @deprecated since 1.5.0
         def anonymous_vpn?
           get('is_anonymous_vpn')
         end
@@ -107,7 +115,11 @@ def anycast?
         # description of the anonymous_vpn? property). This property is only
         # available from Insights.
         #
+        # This method is deprecated as of version 1.5.0. Use the anonymizer object
+        # from the Insights response instead.
+        #
         # @return [Boolean]
+        # @deprecated since 1.5.0
         def hosting_provider?
           get('is_hosting_provider')
         end
@@ -146,7 +158,11 @@ def mobile_network_code
         # This is true if the IP address belongs to a public proxy. This property
         # is only available from Insights.
         #
+        # This method is deprecated as of version 1.5.0. Use the anonymizer object
+        # from the Insights response instead.
+        #
         # @return [Boolean]
+        # @deprecated since 1.5.0
         def public_proxy?
           get('is_public_proxy')
         end
@@ -155,15 +171,23 @@ def public_proxy?
         # and belongs to a residential ISP. This property is only available
         # from Insights.
         #
+        # This method is deprecated as of version 1.5.0. Use the anonymizer object
+        # from the Insights response instead.
+        #
         # @return [Boolean]
+        # @deprecated since 1.5.0
         def residential_proxy?
           get('is_residential_proxy')
         end
 
         # This is true if the IP address is a Tor exit node. This property is only
         # available from Insights.
         #
+        # This method is deprecated as of version 1.5.0. Use the anonymizer object
+        # from the Insights response instead.
+        #
         # @return [Boolean]
+        # @deprecated since 1.5.0
         def tor_exit_node?
           get('is_tor_exit_node')
         end
@@ -212,6 +236,19 @@ def user_count
           get('user_count')
         end
 
+        # This field contains the risk associated with the IP address. The value
+        # ranges from 0.01 to 99. A higher score indicates a higher risk.
+        # Please note that the IP risk score provided in GeoIP products and
+        # services is more static than the IP risk score provided in minFraud
+        # and is not responsive to traffic on your network. If you need realtime
+        # IP risk scoring based on behavioral signals on your own network, please
+        # use minFraud. This property is only available from Insights.
+        #
+        # @return [Float, nil]
+        def ip_risk_snapshot
+          get('ip_risk_snapshot')
+        end
+
         # The user type associated with the IP address. This can be one of the
         # following values:
         #
diff --git a/test/test_client.rb b/test/test_client.rb
@@ -28,6 +28,17 @@ class ClientTest < Minitest::Test
   }.freeze
 
   INSIGHTS = {
+    'anonymizer' => {
+      'confidence' => 85,
+      'is_anonymous' => true,
+      'is_anonymous_vpn' => true,
+      'is_hosting_provider' => false,
+      'is_public_proxy' => false,
+      'is_residential_proxy' => true,
+      'is_tor_exit_node' => false,
+      'network_last_seen' => '2025-10-15',
+      'provider_name' => 'NordVPN',
+    },
     'continent' => {
       'code' => 'NA',
       'geoname_id' => 42,
@@ -43,6 +54,7 @@ class ClientTest < Minitest::Test
     },
     'traits' => {
       'ip_address' => '1.2.3.40',
+      'ip_risk_snapshot' => 45.5,
       'is_anycast' => true,
       'is_residential_proxy' => true,
       'network' => '1.2.3.0/24',
@@ -86,11 +98,24 @@ def test_insights
 
     assert_equal(42, record.continent.geoname_id)
 
+    # Test anonymizer object
+    assert_equal(85, record.anonymizer.confidence)
+    assert(record.anonymizer.anonymous?)
+    assert(record.anonymizer.anonymous_vpn?)
+    refute(record.anonymizer.hosting_provider?)
+    refute(record.anonymizer.public_proxy?)
+    assert(record.anonymizer.residential_proxy?)
+    refute(record.anonymizer.tor_exit_node?)
+    assert_equal(Date.parse('2025-10-15'), record.anonymizer.network_last_seen)
+    assert_equal('NordVPN', record.anonymizer.provider_name)
+
+    # Test traits
     assert(record.traits.anycast?)
     assert(record.traits.residential_proxy?)
     assert_equal('1.2.3.0/24', record.traits.network)
     assert_in_delta(1.3, record.traits.static_ip_score)
     assert_equal(2, record.traits.user_count)
+    assert_in_delta(45.5, record.traits.ip_risk_snapshot)
   end
 
   def test_city
