Login | Register


Documentation -> Tutorials -> Using the Fraud Detection module

This page has been visited 1841 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 rules belong to 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:01', '23:59', 'Mon-Fri', 3, 5, 9600, 16000, 21, 35, 3, 5, 8, 26), \
(1, '99', '00:00', '08:59', '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);

rule idprofile idprefixstart hourend hourdays of the weekcpm warningcpm criticalcall duration warningcall duration criticaltotal calls warningtotal calls criticalconcurrent calls warningconcurrent calls criticalsequential calls warningsequential calls critical

fraud_detection table example

Data interpretation:

  • Rule 1 will obviously match from 09:00 to 17:00, Monday to Friday. It will trigger a fraud warning event/error each time a user either:
    • has made 3 or 4 calls within the last minute
    • makes one call lasting between 7200 and 13119 seconds
    • makes a new call, having made between 15 and 33 calls in the current interval
    • attempts to make 3 or 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:
    • has made at least 5 calls within the last minute
    • makes one call lasting at least 13120 seconds
    • makes a new call, having made at least 34 calls in the current interval
    • attempts to make at least 5 simultaneous calls
    • makes at least 20 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

	if (has_totag()) {
	else {
		check_fraud("$fU", "$rU", "1");
		if ($rc < 0) {
			xlog("Problems for user $fU rc=$rc\n");

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: $var(param);$var(val);$var(thr);$var(user);$var(number);$var(ruleid)\n");

event_route[E_FRD_CRITICAL] {

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

Page last modified on November 10, 2016, at 04:02 PM