Documentation -> Tutorials -> Using the Fraud Detection module

This page has been visited 2610 times.

1.  Introduction

Fraudulent calls have been a part of VoIP since its very beginnings. Typically, there are two ways through which a malicious user can gain permission to place calls through a VoIP platform: account hijacking and weak platform security.

The module provides a way of detecting suspicious calls from the same users to the same destinations might would otherwise likely end up costing the affected VoIP account (or the VoIP provider!) considerable amounts of money. This is done by closely monitoring a set of call-related parameters for each [user,destination] pair, together with sets of provisioned alerting thresholds.

2.  Module Overview

2.1  Functionality

With the help of the dialog module, fraud_detection is able to monitor the following call-related statistics for each [user,destination] pair:

• calls-per-minute
• call duration
• total calls
• concurrent calls
• consecutive calls to the same destination

Note: the above statistics require a user-provisioned time interval to be sampled upon (see 'Table provisioning' below)

2.2  DB provisioning

Table creation

The fraud_detection table is not part of the standard set of tables created by opensips-cli, unless you provide the "database_modules = ALL" setting in your opensips-cli.cfg file during the creation of your opensips database. If you don't have it, you can easily add it as follows:

    opensips-cli -x database add fraud_detection

Table provisioning

The following is an example of a fraud detecting profile for destination prefix "99". Note that all rules below are part of the same profile: 1.

INSERT INTO fraud_detection(profileid, prefix, start_hour, end_hour, daysoftheweek, cpm_warning, cpm_critical, call_duration_warning, \
call_duration_critical, total_calls_warning, total_calls_critical, concurrent_calls_warning, concurrent_calls_critical, \
sequential_calls_warning, sequential_calls_critical) VALUES(1, '99', '09:00', '17:00', 'Mon-Fri', 3, 5, 7200, 13200, 16, 35, 3, 5, 6, 20), \
(1, '99', '17:00', '23:59', 'Mon-Fri', 3, 5, 9600, 16000, 21, 35, 3, 5, 8, 26), \
(1, '99', '00:00', '09:00', 'Mon-Fri', 3, 4, 4800, 9600, 10, 20, 3, 4, 5, 15), \
(1, '99', '00:00', '23:59', 'Sat,Sun', 3, 5, 11400, 17400, 24, 40, 3, 5, 12, 30);

fraud_detection table example

Data interpretation:

• Rule 1 will match from 09:00 to 17:00, Monday to Friday. It will trigger a fraud warning event/error each time a user either:
  • makes between 3 and 4 calls within one minute
  • makes one call lasting between 7200 and 13119 seconds
  • makes between 16 and 34 calls in the current interval
  • makes between 3 and 4 simultaneous calls
  • makes between 6 and 19 consecutive calls to the same destination
• The same Rule 1 will trigger a fraud critical event/error each time a user either:
  • makes 5 or more calls within one minute
  • makes one call lasting 13120 or more seconds
  • makes 35 or more calls in the current interval
  • makes 5 or more simultaneous calls
  • makes 20 or more consecutive calls to the same destination

2.3  How does it work?

As stated in the Chapter 1 of the documentation, the module monitors 5 parameters which are updated every time the check_fraud() function is called. For each (username, prefix) tuple, unique values of the 5 parameters will be kept and monitored. Each time a value is altered, it will be compared to a threshold value. There are two threshold values for each of the 5 parameters (warning and critical thresholds), thus making a total of 10 values. This threshold values along with a time interval in which they are applicable form a so-called rule. It's the admin's job to provide the fraud rules to OpenSIPs through the db interface.

3.  Example script

Firstly, we load the dependencies and the fraud_detection module

loadmodule "drouting.so"
loadmodule "dialog.so"
loadmodule "fraud_detection.so"

Then we set the mandatory parameters

modparam("drouting", "db_partitions_url", "mysql://root:123456@localhost/opensips")
modparam("drouting", "use_partitions", 1)
modparam("fraud_detection", "db_url", "mysql://root:123456@localhost/opensips")

Optionally, we load the event_route module to bind the warning and critical events to an event route

loadmodule "event_route.so"

Let's assume that for each INITIAL INVITE we want to check and update the fraud parameters

route {
	if (has_totag()) {
		loose_route();
	} else {
		record_route();
		check_fraud($fU, $rU, 1);
		if ($rc < 0) {
			xlog("[$ci] Problems for user $fU rc=$rc\n");
		}
	}
	t_relay();
}

Some issues can be identified on the spot, hence the check of the return code. Please refer to the module's documentation for the return code's meaning. Please note the last parameter of the check_fraud function: it's the profile id we set earlier.

Optionally, we can bind the warning and critical events:

event_route [E_FRD_WARNING]
{
	xlog("E_FRD_WARNING: $param(param);$param(val);$param(thr);$param(user);$param(number);$param(ruleid)\n");
}

event_route [E_FRD_CRITICAL]
{
	xlog("E_FRD_CRITICAL: $param(param);$param(val);$param(thr);$param(user);$param(number);$param(ruleid)\n");
}