Documentation -> Tutorials -> Using the Fraud Detection module

This page has been visited 11521 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

In order to create the fraud_detection table, first make sure your opensipsctlrc file contains the desired SQL engine, DB name and access credentials:

    vim /usr/local/etc/opensips/opensipsctlrc

Now you can add the extra OpenSIPS tables:

    opensipsdbctl extra

Table provisioning

The following is an example of a fraud detecting profile for destination prefix "99". Note that all of the 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 (i.e each time a call is made). For each set of number, prefix and username , 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("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] {

	fetch_event_params("$var(param);$var(val);$var(thr);$var(user);$var(number);$var(ruleid)");
	xlog("E_FRD_WARNING: $var(param);$var(val);$var(thr);$var(user);$var(number);$var(ruleid)\n");
}

event_route[E_FRD_CRITICAL] {

	fetch_event_params("$var(param);$var(val);$var(thr);$var(user);$var(number);$var(ruleid)");
	xlog("E_FRD_CRITICAL: $var(param);$var(val);$var(thr);$var(user);$var(number);$var(ruleid)\n");
}