Add support for IP risk reasons

Author: oschwald

CHANGELOG.md

@@ -9,6 +9,9 @@ CHANGELOG
   * `APS_PAYMENTS`
 * Added additional normalizing of the email address if `hashAddress` is
   enabled.
+* Added support for the IP address risk reasons in the minFraud Insights and
+  Factors responses. This is available at `response.getIpAddress().getRiskReasons()`.
+  It is a list of `IpRiskReason` objects.
 
 1.16.0 (2020-10-14)
 -------------------

src/main/java/com/maxmind/minfraud/response/IpAddress.java

@@ -4,6 +4,8 @@
 import com.maxmind.geoip2.model.InsightsResponse;
 import com.maxmind.geoip2.record.*;
 
+import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 
 /**
@@ -13,6 +15,7 @@ public final class IpAddress extends InsightsResponse implements IpAddressInterf
     private final GeoIp2Country country;
     private final GeoIp2Location location;
     private final Double risk;
+    private final List<IpRiskReason> riskReasons;
 
     public IpAddress(
             @JsonProperty("city") City city,
@@ -24,13 +27,36 @@ public IpAddress(
             @JsonProperty("registered_country") Country registeredCountry,
             @JsonProperty("represented_country") RepresentedCountry representedCountry,
             @JsonProperty("risk") Double risk,
+            @JsonProperty("risk_reasons") List<IpRiskReason> riskReasons,
             @JsonProperty("subdivisions") List<Subdivision> subdivisions,
             @JsonProperty("traits") Traits traits
     ) {
         super(city, continent, country, location, maxmind, postal, registeredCountry, representedCountry, subdivisions, traits);
         this.country = country == null ? new GeoIp2Country() : country;
         this.location = location == null ? new GeoIp2Location() : location;
         this.risk = risk;
+        this.riskReasons = Collections.unmodifiableList(riskReasons == null ? new ArrayList<>() : riskReasons);
+    }
+
+    /**
+     * @deprecated This constructor only exists for backward compatibility
+     * and will be removed in the next major release.
+     */
+    public IpAddress(
+            City city,
+            Continent continent,
+            GeoIp2Country country,
+            GeoIp2Location location,
+            MaxMind maxmind,
+            Postal postal,
+            Country registeredCountry,
+            RepresentedCountry representedCountry,
+            Double risk,
+            List<Subdivision> subdivisions,
+            Traits traits
+    ) {
+        this(city, continent, country, location, maxmind, postal, registeredCountry, representedCountry,
+                risk, null, subdivisions, traits);
     }
 
     public IpAddress() {
@@ -63,4 +89,14 @@ public GeoIp2Location getLocation() {
     public Double getRisk() {
         return risk;
     }
+
+    /**
+     * @return An unmodifiable list contains risk reason objects identifying
+     * the reasons why the IP address received the associated risk. This will
+     * be an empty list if there are no reasons.
+     */
+    @JsonProperty("risk_reasons")
+    public final List<IpRiskReason> getRiskReasons() {
+        return riskReasons;
+    }
 }

src/main/java/com/maxmind/minfraud/response/IpRiskReason.java

@@ -0,0 +1,66 @@
+package com.maxmind.minfraud.response;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.maxmind.minfraud.AbstractModel;
+
+/**
+ * This class represents the reason for the IP risk.
+ */
+public final class IpRiskReason extends AbstractModel {
+    private final String code;
+    private final String reason;
+
+    public IpRiskReason(
+            @JsonProperty("code") String code,
+            @JsonProperty("reason") String reason
+    ) {
+        this.code = code;
+        this.reason = reason;
+    }
+
+    /**
+     * This provides a machine-readable code identifying the reason. Although
+     * more codes may be added in the future, the current codes are:
+     * <dl>
+     *     <dt>ANONYMOUS_IP</dt>
+     *     <dd>The IP address belongs to an anonymous network. See the
+     *     object at <c>.IPAddress.Traits</c> for more details.</dd>
+     *
+     *     <dt>BILLING_POSTAL_VELOCITY</dt>
+     *     <dd>Many different billing postal codes have been seen on
+     *     this IP address.</dd>
+     *
+     *     <dt>EMAIL_VELOCITY</dt>
+     *     <dd>Many different email addresses have been seen on this
+     *     IP address.</dd>
+     *
+     *     <dt>HIGH_RISK_DEVICE</dt>
+     *     <dd>A high risk device was seen on this IP address.</dd>
+     *
+     *     <dt>HIGH_RISK_EMAIL</dt>
+     *     <dd>A high risk email address was seen on this IP address in
+     *     your past transactions.</dd>
+     *
+     *     <dt>ISSUER_ID_NUMBER_VELOCITY</dt>
+     *     <dd>Many different issuer ID numbers have been seen on this
+     *     IP address.</dd>
+     *
+     *     <dt>MINFRAUD_NETWORK_ACTIVITY</dt>
+     *     <dd>Suspicious activity has been seen on this IP address
+     *     across minFraud customers.</dd>
+     * </dl>
+     *
+     * @return The reason code.
+     */
+    public String getCode() {
+        return this.code;
+    }
+
+    /**
+     * @return This field provides a human-readable explanation of the reason.
+     * The description may change at any time and should not be matched against.
+     */
+    public String getReason() {
+        return this.reason;
+    }
+}

src/test/java/com/maxmind/minfraud/WebServiceClientTest.java

@@ -8,6 +8,7 @@
 import com.maxmind.minfraud.request.TransactionReport;
 import com.maxmind.minfraud.response.FactorsResponse;
 import com.maxmind.minfraud.response.InsightsResponse;
+import com.maxmind.minfraud.response.IpRiskReason;
 import com.maxmind.minfraud.response.ScoreResponse;
 import junitparams.JUnitParamsRunner;
 import junitparams.Parameters;
@@ -17,6 +18,7 @@
 import org.skyscreamer.jsonassert.JSONAssert;
 
 import java.net.InetAddress;
+import java.util.List;
 
 import static com.github.tomakehurst.wiremock.client.WireMock.*;
 import static com.jcabi.matchers.RegexMatchers.matchesPattern;
@@ -89,6 +91,12 @@ public void testFullInsightsTransaction() throws Exception {
             assertEquals("81.2.69.0/24", response.getIpAddress().getTraits().getNetwork().toString());
 
             assertTrue(response.getCreditCard().isVirtual());
+
+            List<IpRiskReason> reasons = response.getIpAddress().getRiskReasons();
+
+            assertEquals("two IP risk reasons", 2, reasons.size());
+            assertEquals("second IP risk reason code", "MINFRAUD_NETWORK_ACTIVITY",
+                    reasons.get(1).getCode());
         }
     }
 

src/test/java/com/maxmind/minfraud/response/IpAddressTest.java

@@ -3,8 +3,7 @@
 import com.fasterxml.jackson.jr.ob.JSON;
 import org.junit.Test;
 
-import static org.junit.Assert.assertEquals;
-import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.*;
 
 public class IpAddressTest extends AbstractOutputTest {
 
@@ -18,6 +17,12 @@ public void testIpAddress() throws Exception {
                         .composeString()
                         .startObject()
                         .put("risk", 99)
+                        .startArrayField("risk_reasons")
+                        .startObject()
+                        .put("code", "ANONYMOUS_IP")
+                        .put("reason", "some reason")
+                        .end()
+                        .end()
                         .startObjectField("country")
                         .put("is_high_risk", true)
                         .end()
@@ -46,6 +51,19 @@ public void testIpAddress() throws Exception {
         assertTrue("isHostingProvider", address.getTraits().isHostingProvider());
         assertTrue("isPublicProxy", address.getTraits().isPublicProxy());
         assertTrue("isTorExitNode", address.getTraits().isTorExitNode());
+        assertEquals("IP risk reason code", "ANONYMOUS_IP",
+                address.getRiskReasons().get(0).getCode());
+        assertEquals("IP risk reason", "some reason",
+                address.getRiskReasons().get(0).getReason());
+    }
+
+    @Test
+    public void testEmptyObject() throws Exception {
+        IpAddress address = this.deserialize(
+                IpAddress.class,
+                "{}"
+        );
 
+        assertNotNull(address.getRiskReasons());
     }
 }

src/test/resources/test-data/factors-response.json

@@ -5,6 +5,16 @@
   "queries_remaining": 1000,
   "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,

src/test/resources/test-data/insights-response.json

@@ -5,6 +5,16 @@
   "queries_remaining": 1000,
   "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,