Fraud Detection Module


Table of Contents

1. Admin Guide
1.1. Overview
1.1.1. Monitorized Stats
1.1.2. Fraud rules
1.2. Dependencies
1.2.1. OpenSIPS modules
1.2.2. External libraries or applications
1.3. Exported Parameters
1.3.1. db_url (string)
1.3.2. use_utc_time (integer)
1.3.3. table_name (string)
1.3.4. rid_col (string)
1.3.5. pid_col (string)
1.3.6. prefix_col (string)
1.3.7. start_h (string)
1.3.8. end_h (string)
1.3.9. days_col (string)
1.3.10. cpm_thresh_warn_col (string)
1.3.11. cpm_thresh_crit_col (string)
1.3.12. calldur_thresh_warn_col (string)
1.3.13. calldur_thresh_crit_col (string)
1.3.14. totalc_thresh_warn_col (string)
1.3.15. totalc_thresh_crit_col (string)
1.3.16. concalls_thresh_warn_col (string)
1.3.17. concalls_thresh_crit_col (string)
1.3.18. seqcalls_thresh_warn_col (string)
1.3.19. seqcalls_thresh_crit_col (string)
1.4. Exported Functions
1.4.1. check_fraud(user, number, profile_id)
1.5. Exported MI Functions
1.5.1. show_fraud_stats
1.5.2. fraud_reload
1.6. Exported Events
1.6.1. E_FRD_WARNING
1.6.2. E_FRD_CRITICAL
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors

List of Tables

2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
2.2. Most recently active contributors(1) to this module

List of Examples

1.1. Set the db_url parameter
1.2. Set the use_utc_time parameter
1.3. Set the table_name parameter
1.4. Set rid_col parameter
1.5. Set pid_col parameter
1.6. Set prefix_col parameter
1.7. Set start_h parameter
1.8. Set end_h parameter
1.9. Set days_col parameter
1.10. Set cpm_thresh_warn_col parameter
1.11. Set cpm_thresh_crit_col parameter
1.12. Set calldur_thresh_warn_col parameter
1.13. Set calldur_thresh_crit_col parameter
1.14. Set totalc_thresh_warn_col parameter
1.15. Set totalc_thresh_crit_col parameter
1.16. Set concalls_thresh_warn_col parameter
1.17. Set concalls_thresh_crit_col parameter
1.18. Set seqcalls_thresh_warn_col parameter
1.19. Set seqcalls_thresh_crit_col parameter

Chapter 1. Admin Guide

1.1. Overview

This module provides a way to prevent some basic fraud attacks. Alerts are provided through return codes and events.

1.1.1. Monitorized Stats

Basically, this module watches the following parameters:

  • Total calls

  • Calls per minute

  • Concurrent calls

  • Number of sequential calls

  • Call duration

Each of the above parameters is monitored for every user and every called prefix separately. The stats are altered whenever the check_fraud function is called. The function assumes a new call is made, and checks the called number against all the rules from the supplied profile. The rule's prefix is considered to be the called prefix which along with the provided user will be used to monitor values for the 5 parameters.

1.1.2. Fraud rules

A rule is a set of two thresholds (warning and critical thresholds) for each of the five parameters (as described above) and is only available for a specified prefix. Further more, a rule will only match between the indicated hours in the indicated days of the week (similarly to a dr rule). A fraud profile is simply a group of fraud rules and is used to only to limit the list of rules to match when calling the check_fraud function.

1.2. Dependencies

1.2.1. OpenSIPS modules

The following modules must be loaded before this module:

  • drouting

  • dialog

1.2.2. External libraries or applications

The following libraries or applications must be installed before running OpenSIPS with this module:

  • none.

1.3. Exported Parameters

1.3.1. db_url (string)

Database where to load the rules from.

Default value is NULL. At least one db_url should be defined for the fraud_detection module to work.

Example 1.1. Set the db_url parameter

...
modparam("fraud_detection", "db_url", "mysql://user:passwb@localhost/database")
...

1.3.2. use_utc_time (integer)

Set this parameter to non-zero in order to enable UTC-based interval matching and statistics resets, rather than local time-based.

The default value is 0 (use local time).

Example 1.2. Set the use_utc_time parameter

...
modparam("fraud_detection", "use_utc_time", 1)
...

1.3.3. table_name (string)

If you want to load the rules from the database you must set this parameter as the database name.

The default value is fraud_detection.

Example 1.3. Set the table_name parameter

...
modparam("fraud_detection", "table_name", "my_fraud")
...

1.3.4. rid_col (string)

The column's name in the database storing the fraud rule's id.

Default value is ruleid.

Example 1.4. Set rid_col parameter

...
modparam("fraud_detection", "rid_col", "theruleid"")
...

1.3.5. pid_col (string)

The column's name in the database storing the fraud profile's id.

Please keep in mind that a profile is merely a set of rules.

Default value is profileid.

Example 1.5. Set pid_col parameter

...
modparam("fraud_detection", "pid_col", "profile"")
...

1.3.6. prefix_col (string)

The column's name in the database storing the prefix for which the fraud rule will match.

Default value is prefix.

Example 1.6. Set prefix_col parameter

...
modparam("fraud_detection", "prefix_col", "myprefix")
...

1.3.7. start_h (string)

The column's name in the database storing the the start time of the interval in which the rule will match.

The time needs to be specified as string using the format: HH:MM

Default value is start_hour.

Example 1.7. Set start_h parameter

...
modparam("fraud_detection", "start_h", "the_start_time")
...

1.3.8. end_h (string)

The column's name in the database storing the the end time of the interval in which the rule will match.

The time needs to be specified as string using the format: HH:MM

Default value is end_hour.

Example 1.8. Set end_h parameter

...
modparam("fraud_detection", "end_h", "the_end_time")
...

1.3.9. days_col (string)

The column's name in the database storing the week days in which the fraud rule's interval is available.

The daysoftheweek needs to be specified as a string containing a list of days or intervals. Each day must be specified using the first three letters of its name. A valid string would be: "Fri-Mon, Wed, Thu"

Default value is daysoftheweek.

Example 1.9. Set days_col parameter

...
modparam("fraud_detection", "days_col", "days")
...

1.3.10. cpm_thresh_warn_col (string)

The column's name in the database storing the warning threshold value for calls per minute.

Default value is cpm_warning.

Example 1.10. Set cpm_thresh_warn_col parameter

...
modparam("fraud_detection", "cpm_thresh_warn_col", "cpm_warn_thresh")
...

1.3.11. cpm_thresh_crit_col (string)

The column's name in the database storing the critical threshold value for calls per minute.

Default value is cpm_critical.

Example 1.11. Set cpm_thresh_crit_col parameter

...
modparam("fraud_detection", "cpm_thresh_crit_col", "cpm_crit_thresh")
...

1.3.12. calldur_thresh_warn_col (string)

The column's name in the database storing the warning threshold value for call duration.

Default value is call_duration_warning.

Example 1.12. Set calldur_thresh_warn_col parameter

...
modparam("fraud_detection", "calldur_thresh_warn_col", "calldur_warn_thresh")
...

1.3.13. calldur_thresh_crit_col (string)

The column's name in the database storing the critical threshold value for call duration.

Default value is call_duration_critical.

Example 1.13. Set calldur_thresh_crit_col parameter

...
modparam("fraud_detection", "calldur_thresh_crit_col", "calldur_crit_thresh")
...

1.3.14. totalc_thresh_warn_col (string)

The column's name in the database storing the warning threshold value for the number of total calls.

Default value is total_calls_warning.

Example 1.14. Set totalc_thresh_warn_col parameter

...
modparam("fraud_detection", "totalc_thresh_warn_col", "totalc_warn_thresh")
...

1.3.15. totalc_thresh_crit_col (string)

The column's name in the database storing the critical threshold value for the number of total calls.

Default value is total_calls_critical.

Example 1.15. Set totalc_thresh_crit_col parameter

...
modparam("fraud_detection", "totalc_thresh_crit_col", "totalc_crit_thresh")
...

1.3.16. concalls_thresh_warn_col (string)

The column's name in the database storing the warning threshold value for the number of concurrent calls.

Default value is concurrent_calls_warning.

Example 1.16. Set concalls_thresh_warn_col parameter

...
modparam("fraud_detection", "concalls_thresh_warn_col", "concalls_warn_thresh")
...

1.3.17. concalls_thresh_crit_col (string)

The column's name in the database storing the critical threshold value for the number of concurrent calls.

Default value is concurrent_calls_critical.

Example 1.17. Set concalls_thresh_crit_col parameter

...
modparam("fraud_detection", "concalls_thresh_crit_col", "concalls_crit_thresh")
...

1.3.18. seqcalls_thresh_warn_col (string)

The column's name in the database storing the warning threshold value for the number of sequential calls.

Default value is sequential_calls_warning.

Example 1.18. Set seqcalls_thresh_warn_col parameter

...
modparam("fraud_detection", "seqcalls_thresh_warn_col", "seqcalls_warn_thresh")
...

1.3.19. seqcalls_thresh_crit_col (string)

The column's name in the database storing the critical threshold value for the number of sequential calls.

Default value is sequential_calls_critical.

Example 1.19. Set seqcalls_thresh_crit_col parameter

...
modparam("fraud_detection", "seqcalls_thresh_crit_col", "seqcalls_crit_thresh")
...

1.4. Exported Functions

1.4.1.  check_fraud(user, number, profile_id)

This method should be called each time a given user calls a given number. It will try to match a fraud rule within de given fraud profile and update the stats (see above). Furthermore, the stats will be checked against the rule's thresholds. If any of the stats is above it's threshold value the appropriate event will also be raised (see further details below).

Meaning of the parameters is as follows:

  • user - the user who is making the call. Please keep in mind that the user doesn't have to be registered. This string is only used do keep different stats for different registered users.

  • number - the number the user is calling to.

  • profile_id - the fraud profile id (i.e. the subset of fraud rules) in which to try and find a matching fraud rule.

The meaning of the return code is as follows:

  • 2 - no matching fraud rule was found

  • 1 - a matching rule was found, but there is no parameter above the rule's threshlod, i.e - everything is ok

  • -1 - there is a parameter above the warning threshold value. Check the raised event for more info

  • -2 - there is a parameter above the critical threshold value. Check the raised event for more info

  • -3 - something went wrong (internal mechanism failed)

This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.

1.5. Exported MI Functions

1.5.1.  show_fraud_stats

Show the current statistics for all dials of a user to a prefix.

NOTE: Since the fraud statistics are refreshed on-the-fly, as check_fraud() is called, this function will return stale data if check_fraud() has not been called at least once for the (user, prefix) pair within a newly matching time interval!

Name: show_fraud_stats

Parameters:

  • user

  • prefix

1.5.2.  fraud_reload

Reload the all the fraud rules.

Name: fraud_reload

Parameters: none

1.6. Exported Events

1.6.1.  E_FRD_WARNING

This event is raised whenever one of the 5 monitored parameters is above the warning threshold value

Parameters:

  • param - the name of the parameter.

  • value - the current value of the parameter.

  • threshold - the warning threshold value.

  • user - the user who initiated the call.

  • called_number - the number that was called.

  • rule_id - the id of the fraud rule that matched when the call was initiated

1.6.2.  E_FRD_CRITICAL

This event is raised whenever one of the 5 monitored parameters is above the warning threshold value

Parameters:

  • param - the name of the parameter.

  • value - the current value of the parameter.

  • threshold - the warning threshold value.

  • user - the user who initiated the call.

  • called_number - the number that was called.

  • rule_id - the id of the fraud rule that matched when the call was initiated

Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

 NameDevScoreCommitsLines ++Lines --
1. Liviu Chircu (@liviuchircu)3932286211
2. Andrei Datcu (@andrei-datcu)37112665235
3. Bogdan-Andrei Iancu (@bogdan-iancu)751931
4. Razvan Crainea (@razvancrainea)751310
5. Vlad Patrascu (@rvlad-patrascu)42104
6. Ionut Ionita (@ionutrazvanionita)31216

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

2.2. By Commit Activity

Table 2.2. Most recently active contributors(1) to this module

 NameCommit Activity
1. Liviu Chircu (@liviuchircu)Mar 2015 - Jan 2021
2. Razvan Crainea (@razvancrainea)Feb 2015 - Sep 2019
3. Bogdan-Andrei Iancu (@bogdan-iancu)Oct 2014 - Jun 2018
4. Vlad Patrascu (@rvlad-patrascu)May 2017 - Mar 2018
5. Ionut Ionita (@ionutrazvanionita)Jan 2016 - Jan 2016
6. Andrei Datcu (@andrei-datcu)Aug 2014 - Sep 2014

(1) including any documentation-related commits, excluding merge commits

Chapter 3. Documentation

3.1. Contributors

Last edited by: Liviu Chircu (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Andrei Datcu (@andrei-datcu).

doc copyrights:

Copyright © 2014 www.opensips-solutions.com