Add anonymizer property documentation and tests for IPAddress model

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: oschwald

HISTORY.rst

@@ -11,6 +11,11 @@ History
 * The version is now retrieved from package metadata at runtime using
   ``importlib.metadata``. This reduces the chance of version inconsistencies
   during releases.
+* Added documentation for the ``anonymizer`` attribute on the
+  ``minfraud.models.IPAddress`` class. This attribute is inherited from
+  ``geoip2.models.Insights`` and provides data about anonymizers associated
+  with the IP address, including confidence score, anonymizer type flags
+  (VPN, proxy, Tor, etc.), network last seen date, and provider name.
 
 3.2.0 (2025-11-20)
 ++++++++++++++++++

src/minfraud/models.py

@@ -113,6 +113,29 @@ class IPAddress(geoip2.models.Insights):
     to the attributes provided by that class, it provides the ``risk`` and
     ``risk_reasons`` attributes. It also overrides the ``location`` attribute
     to use :py:class:`GeoIP2Location`.
+
+    .. attribute:: anonymizer
+
+       A :py:class:`geoip2.records.Anonymizer` object containing data about
+       the anonymizer associated with the IP address. This object has the
+       following attributes:
+
+       * ``confidence`` - A number from 0 to 100 indicating our confidence that
+         the IP address is an anonymizer based on analysis of our data.
+       * ``is_anonymous`` - ``True`` if the IP address belongs to any sort of
+         anonymous network.
+       * ``is_anonymous_vpn`` - ``True`` if the IP address is registered to an
+         anonymous VPN provider.
+       * ``is_hosting_provider`` - ``True`` if the IP address belongs to a
+         hosting or VPN provider (see description of ``is_anonymous_vpn``).
+       * ``is_public_proxy`` - ``True`` if the IP address belongs to a public
+         proxy.
+       * ``is_residential_proxy`` - ``True`` if the IP address is on a suspected
+         anonymizing network and belongs to a residential ISP.
+       * ``is_tor_exit_node`` - ``True`` if the IP address is a Tor exit node.
+       * ``network_last_seen`` - A ``datetime.date`` object indicating
+         when the network was last seen as an anonymizer.
+       * ``provider_name`` - The name of the anonymizer provider, if known.
     """
 
     location: GeoIP2Location

tests/data/factors-response.json

@@ -19,6 +19,16 @@
         "reason": "Suspicious activity has been seen on this IP address across minFraud customers."
       }
     ],
+    "anonymizer": {
+      "confidence": 99,
+      "is_anonymous": true,
+      "is_anonymous_vpn": true,
+      "is_hosting_provider": true,
+      "is_public_proxy": true,
+      "is_tor_exit_node": true,
+      "network_last_seen": "2025-01-15",
+      "provider_name": "TestVPN"
+    },
     "city": {
       "confidence": 42,
       "geoname_id": 2643743,

tests/data/insights-response.json

@@ -19,6 +19,16 @@
         "reason": "Suspicious activity has been seen on this IP address across minFraud customers."
       }
     ],
+    "anonymizer": {
+      "confidence": 99,
+      "is_anonymous": true,
+      "is_anonymous_vpn": true,
+      "is_hosting_provider": true,
+      "is_public_proxy": true,
+      "is_tor_exit_node": true,
+      "network_last_seen": "2025-01-15",
+      "provider_name": "TestVPN"
+    },
     "city": {
       "confidence": 42,
       "geoname_id": 2643743,

tests/test_models.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import datetime
 import unittest
 from typing import Any
 
@@ -187,6 +188,16 @@ def test_ip_address(self) -> None:
                     "across minFraud customers.",
                 },
             ],
+            anonymizer={
+                "confidence": 99,
+                "is_anonymous": True,
+                "is_anonymous_vpn": True,
+                "is_hosting_provider": True,
+                "is_public_proxy": True,
+                "is_tor_exit_node": True,
+                "network_last_seen": "2025-01-15",
+                "provider_name": "TestVPN",
+            },
             traits={
                 "is_anonymous": True,
                 "is_anonymous_proxy": True,
@@ -215,6 +226,16 @@ def test_ip_address(self) -> None:
         self.assertEqual("310", address.traits.mobile_country_code)
         self.assertEqual("004", address.traits.mobile_network_code)
 
+        # Test anonymizer attribute
+        self.assertEqual(99, address.anonymizer.confidence)
+        self.assertEqual(True, address.anonymizer.is_anonymous)
+        self.assertEqual(True, address.anonymizer.is_anonymous_vpn)
+        self.assertEqual(True, address.anonymizer.is_hosting_provider)
+        self.assertEqual(True, address.anonymizer.is_public_proxy)
+        self.assertEqual(True, address.anonymizer.is_tor_exit_node)
+        self.assertEqual(datetime.date(2025, 1, 15), address.anonymizer.network_last_seen)
+        self.assertEqual("TestVPN", address.anonymizer.provider_name)
+
         self.assertEqual("ANONYMOUS_IP", address.risk_reasons[0].code)
         self.assertEqual(
             "The IP address belongs to an anonymous network. "