Risk Modules in depth
Currently, there are two Risk Modules in the TrustFactor Services:
LRC
With the current location of the user’s Agents and the location of the transaction creation, a distance calculation is performed to find the nearest Agent to the transaction creation location. That way if the Agent is not within the margin of error the risk module returns a high risk result. This margin of error is a distance derived from the sum of the accuracy of both locations, the closest Agent and the transaction creation.
There are two ways we can get the location from the transaction. One way is to send the precise location of the transaction creation on the riskModules parameter with the LRC key and RiskModuleInputLRC object. The other way we take the transaction metadata IP to extrapolate a location from it. If the precise location is not sent the TrustFactor services will fallback to the transaction metadata IP for the location.
For the RiskModuleInputLRC the possible inputs are:
| Parameter | Mandatory | Data Type | Data Format |
|---|---|---|---|
lat | Yes | float | Decimal Degrees |
lon | Yes | float | Decimal Degrees |
accuracy | Yes | float | Kilometers |
Keep in mind that the coordinates format used in the TrustFactor services is the Decimal Degrees (e.g. lat = 41.25, lon = -8.5437), and the accuracy is expressed in kilometers (e.g. accuracy = 50).
IP Reputation
Taking in account the transaction metadata IP we use threat intelligence sources to check if the source IP of the transaction has been flagged as the origin of suspicious activity. If the IP is flagged as suspicious, the risk module will return a high risk result.
Risk Modules parameters
We can divide the risk modules parameters in three parts:
riskModules- Used for additional parameters for the TrustFactor risk modules calculationriskModulesToCalculate- Defines which risk modules should be used for transaction risk calculation and whether they are mandatoryriskModulesAdded- Additional risk modules information that application might send that is directly mapped to mobiles agents UI
Risk Modules
This parameter’s purpose is to send additional information that might be used during Risk Module processing, such as giving a precise location for the transaction origin.
The additional parameters are defined through the TransactionAgentInput object that contains an HashMap. This HashMap has RiskModule enum as its key and IRiskModuleInput interface as its value. The use of an interface as the value of the dictionary allows the creation of new inputs without the need of breaking changes for the already existing ones and support several classes generically.
The current possible classes for the IRiskModuleInput interface are:
| Class | Corresponding Key |
|---|---|
RiskModuleInputLRC | RiskModule.LRC |
RiskModuleInputIPRep | RiskModule.IPREP |
This risk module is supported in these transactions types:
In the code snippet below we have an example of a generic transaction with only the risk modules parameter filled.
import com.securityside.trustfactor.constants.enums.RiskModule;
import com.securityside.trustfactor.model.transaction.creation.v3.GenericTransaction;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.IRiskModuleInput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.RiskModuleInputIPRep;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.RiskModuleInputLRC;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.TransactionAgentInput;
import java.util.HashMap;
public class Main {
public static void main(String[] args) {
GenericTransaction transaction = GenericTransaction.builder()
.riskModules(TransactionAgentInput.builder()
.input(new HashMap<RiskModule, IRiskModuleInput>() {{
put(RiskModule.LRC, RiskModuleInputLRC.builder()
.lat(41.25F)
.lon(-8.5437F)
.accuracy(50F)
.build());
put(RiskModule.IPREP, RiskModuleInputIPRep.builder()
.build());
}})
.build())
.build();
}
}
Risk Modules To Calculate
This parameter’s purpose is to define which TrustFactor Risk Modules should be calculated and whether they are mandatory. A mandatory risk module means that if the transaction fails in the calculation of a Risk Module, the transaction will not be successful. This module only appears where there is no operation defined, as an operation has this functionality in it.
To define the risk modules to be calculated it is needed to instantiate a TransactionRiskModulesToUse object, that consists of a HashMap with RiskModule as key and TransactionRiskModuleToUse as the value. We can set that a risk module as mandatory by simply setting the mandatory parameter as true. If a risk module is absent from riskModulesToCalculate parameter it will not be calculated.
This risk module appears on the following transactions:
In the code snippet below we have an example of a generic transaction with only the risk modules to calculate parameter filled.
import com.securityside.trustfactor.constants.enums.RiskModule;
import com.securityside.trustfactor.model.transaction.creation.v3.GenericTransaction;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.TransactionRiskModuleToUse;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.TransactionRiskModulesToUse;
import java.util.HashMap;
public class Main {
public static void main(String[] args) {
GenericTransaction transaction = GenericTransaction.builder()
.riskModulesToCalculate(TransactionRiskModulesToUse.builder()
.transactionRiskModulesToUse(
new HashMap<RiskModule, TransactionRiskModuleToUse>(){{
put(RiskModule.LRC, TransactionRiskModuleToUse.builder()
.mandatory(true)
.build());
put(RiskModule.IPREP, TransactionRiskModuleToUse.builder()
.mandatory(true)
.build());
}}
)
.build())
.build();
}
}
Risk Modules Added
This module serves to add new Risk Modules that is directly mapped to mobiles agents UI. These risk modules can be used by the customer freely if they wish. For example if they want to alert in a more general way to something risky in the transaction.
To add additional risk modules to show to the user, one should instantiate a TransactionAgentOutput object that consists of an HashMap of string as keys and TransactionRiskModuleOutput as value. TransactionRiskModuleOutput contains only one parameter agentModuleOutput used in the Agents. ModuleOutput contains the information to be shown to the user, such as risk, message or a trigger with RiskModuleOutputData object.
RiskModuleOutputData class is a placeholder and should not be instantiated directly, instead it should be created a Map or Webview object and call the respective create output method. For the case of Map class call CreateMapOutput method and CreateWebviewOutput method for the Webview class.
Mapclass has information about a location, for example the origin location of the transaction.Webviewon the other hand has the information for a webview on the Agent device.
The onTap parameter is accessed when the user presses the Risk module on the Agent.
This risk module appears on the following transactions:
In the code snippet below we have an example of a generic transaction with only the risk modules added parameter filled.
import com.securityside.trustfactor.constants.enums.RiskLevel;
import com.securityside.trustfactor.model.transaction.creation.v3.GenericTransaction;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.TransactionAgentOutput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.TransactionRiskModuleOutput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.ModuleOutput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Coordinates;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Map;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Pinpoint;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Webview;
import java.util.HashMap;
public class Main {
public static void main(String[] args) {
GenericTransaction transaction = GenericTransaction.builder()
.riskModulesAdded(TransactionAgentOutput.builder()
.output(new HashMap<String, TransactionRiskModuleOutput>(){{
put("new_risk_module", TransactionRiskModuleOutput.builder()
.agentModuleOutput(ModuleOutput.builder()
.risk(RiskLevel.HIGH)
.message("Some message to notify the risk level")
.onTap(Map.builder()
.title("Origin Location")
.coordinates(Coordinates.builder()
.lat(41.25F)
.lon(-8.5437F)
.accuracy(50F)
.build())
.pinpoint(Pinpoint.builder()
.country("Portugal")
.city("Porto")
.build())
.build().CreateMapOutput())
.build())
.build());
}})
.build())
.build();
}
}