Merge pull request #75 from maxmind/greg/ip-risk-reasons

Add support for IP risk reasons

Author: horgh

HISTORY.rst

@@ -16,6 +16,10 @@ History
   address and sends an MD5 hash of it to the web service rather than the
   plain-text address. Note that the email domain will still be sent in plain
   text.
+* Added support for the IP address risk reasons in the minFraud Insights and
+  Factors responses. This is available at ``.ip_address.risk_reasons``. It is
+  an array of ``IPRiskReason`` objects.
+
 
 2.2.0 (2020-10-13)
 ++++++++++++++++++

minfraud/models.py

@@ -59,6 +59,63 @@ def new(cls, *args, **kwargs):
     return new_cls
 
 
+@_inflate_to_namedtuple
+class IPRiskReason:
+    """Reason for the IP risk.
+
+    This class provides both a machine-readable code and a human-readable
+    explanation of the reason for the IP risk score.
+
+    Although more codes may be added in the future, the current codes are:
+
+    - ``ANONYMOUS_IP`` - The IP address belongs to an anonymous network. See
+      the object at ``->ipAddress->traits`` for more details.
+    - ``BILLING_POSTAL_VELOCITY`` - Many different billing postal codes have
+      been seen on this IP address.
+    - ``EMAIL_VELOCITY`` - Many different email addresses have been seen on this
+      IP address.
+    - ``HIGH_RISK_DEVICE`` - A high risk device was seen on this IP address.
+    - ``HIGH_RISK_EMAIL`` - A high risk email address was seen on this IP
+      address in your past transactions.
+    - ``ISSUER_ID_NUMBER_VELOCITY`` - Many different issuer ID numbers have been
+      seen on this IP address.
+    - ``MINFRAUD_NETWORK_ACTIVITY`` - Suspicious activity has been seen on this
+      IP address across minFraud customers.
+
+    .. attribute:: code
+
+      This value is a machine-readable code identifying the
+      reason.
+
+      :type: str | None
+
+    .. attribute:: reason
+
+      This property provides a human-readable explanation of the
+      reason. The text may change at any time and should not be matched
+      against.
+
+      :type: str | None
+    """
+
+    code: Optional[str]
+    reason: Optional[str]
+
+    __slots__ = ()
+    _fields = {
+        "code": None,
+        "reason": None,
+    }
+
+
+def _create_ip_risk_reasons(
+    reasons: Optional[List[Dict[str, str]]]
+) -> Tuple[IPRiskReason, ...]:
+    if not reasons:
+        return ()
+    return tuple([IPRiskReason(x) for x in reasons])  # type: ignore
+
+
 class GeoIP2Location(geoip2.records.Location):
     """Location information for the IP address.
 
@@ -126,6 +183,14 @@ class IPAddress(geoip2.models.Insights):
 
       :type: float | None
 
+    .. attribute:: risk_reasons
+
+      This tuple contains :class:`.IPRiskReason` objects identifying the
+      reasons why the IP address received the associated risk. This will be
+      an empty tuple if there are no reasons.
+
+      :type: tuple[IPRiskReason]
+
     .. attribute:: city
 
       City object for the requested IP address.
@@ -189,6 +254,7 @@ class IPAddress(geoip2.models.Insights):
     country: GeoIP2Country
     location: GeoIP2Location
     risk: Optional[float]
+    risk_reasons: Tuple[IPRiskReason, ...]
 
     def __init__(self, ip_address: Dict[str, Any]) -> None:
         if ip_address is None:
@@ -200,6 +266,7 @@ def __init__(self, ip_address: Dict[str, Any]) -> None:
         self.country = GeoIP2Country(locales, **ip_address.get("country", {}))
         self.location = GeoIP2Location(**ip_address.get("location", {}))
         self.risk = ip_address.get("risk", None)
+        self.risk_reasons = _create_ip_risk_reasons(ip_address.get("risk_reasons"))
         self._finalized = True
 
     # Unfortunately the GeoIP2 models are not immutable, only the records. This
@@ -1058,7 +1125,7 @@ class Factors:
     risk_score: float
     shipping_address: ShippingAddress
     subscores: Subscores
-    warnings: List[ServiceWarning]
+    warnings: Tuple[ServiceWarning, ...]
 
     __slots__ = ()
     _fields = {
@@ -1182,7 +1249,7 @@ class Insights:
     queries_remaining: int
     risk_score: float
     shipping_address: ShippingAddress
-    warnings: List[ServiceWarning]
+    warnings: Tuple[ServiceWarning, ...]
 
     __slots__ = ()
     _fields = {
@@ -1266,7 +1333,7 @@ class Score:
     ip_address: ScoreIPAddress
     queries_remaining: int
     risk_score: float
-    warnings: List[ServiceWarning]
+    warnings: Tuple[ServiceWarning, ...]
 
     __slots__ = ()
     _fields = {

tests/data/factors-response.json

@@ -9,6 +9,16 @@
   },
   "ip_address": {
     "risk": 0.01,
+    "risk_reasons": [
+      {
+        "code": "ANONYMOUS_IP",
+        "reason": "The IP address belongs to an anonymous network. See /ip_address/traits for more details."
+      },
+      {
+        "code": "MINFRAUD_NETWORK_ACTIVITY",
+        "reason": "Suspicious activity has been seen on this IP address across minFraud customers."
+      }
+    ],
     "city": {
       "confidence": 42,
       "geoname_id": 2643743,

tests/data/insights-response.json

@@ -9,6 +9,16 @@
   },
   "ip_address": {
     "risk": 0.01,
+    "risk_reasons": [
+      {
+        "code": "ANONYMOUS_IP",
+        "reason": "The IP address belongs to an anonymous network. See /ip_address/traits for more details."
+      },
+      {
+        "code": "MINFRAUD_NETWORK_ACTIVITY",
+        "reason": "Suspicious activity has been seen on this IP address across minFraud customers."
+      }
+    ],
     "city": {
       "confidence": 42,
       "geoname_id": 2643743,

tests/test_models.py

@@ -8,6 +8,7 @@ def test_model_immutability(self):
         """This tests some level of _shallow_ immutability for these classes"""
         T = namedtuple("T", ["obj", "attr"])
         models = [
+            T(IPRiskReason(), "code"),
             T(Issuer(), "name"),
             T(CreditCard(), "country"),
             T(Device(), "id"),
@@ -152,6 +153,16 @@ def test_ip_address(self):
                     "local_time": time,
                 },
                 "risk": 99,
+                "risk_reasons": [
+                    {
+                        "code": "ANONYMOUS_IP",
+                        "reason": "The IP address belongs to an anonymous network. See /ip_address/traits for more details.",
+                    },
+                    {
+                        "code": "MINFRAUD_NETWORK_ACTIVITY",
+                        "reason": "Suspicious activity has been seen on this IP address across minFraud customers.",
+                    },
+                ],
                 "traits": {
                     "is_anonymous": True,
                     "is_anonymous_proxy": True,
@@ -179,6 +190,22 @@ def test_ip_address(self):
         self.assertEqual(True, address.traits.is_tor_exit_node)
         self.assertEqual(True, address.country.is_high_risk)
 
+        self.assertEqual("ANONYMOUS_IP", address.risk_reasons[0].code)
+        self.assertEqual(
+            "The IP address belongs to an anonymous network. See /ip_address/traits for more details.",
+            address.risk_reasons[0].reason,
+        )
+
+        self.assertEqual("MINFRAUD_NETWORK_ACTIVITY", address.risk_reasons[1].code)
+        self.assertEqual(
+            "Suspicious activity has been seen on this IP address across minFraud customers.",
+            address.risk_reasons[1].reason,
+        )
+
+    def test_empty_address(self):
+        address = IPAddress({})
+        self.assertEqual((), address.risk_reasons)
+
     def test_score_ip_address(self):
         address = ScoreIPAddress({"risk": 99})
         self.assertEqual(99, address.risk)

tests/test_webservice.py

@@ -193,6 +193,7 @@ def test_200(self):
         if self.has_ip_location():
             self.assertEqual("United Kingdom", model.ip_address.country.name)
             self.assertEqual(True, model.ip_address.traits.is_residential_proxy)
+            self.assertEqual("ANONYMOUS_IP", model.ip_address.risk_reasons[0].code)
 
     @httprettified
     def test_200_on_request_with_nones(self):