Fraud Detection Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview

              1.1.1. Monitored 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. Monitored 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/dat
abase")
...

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_thr
esh")
...

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_thr
esh")
...

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_thres
h")
...

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_thres
h")
...

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_t
hresh")
...

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_t
hresh")
...

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_t
hresh")
...

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_t
hresh")
...

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 the
   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 its threshold value,
   the appropriate event will also be raised (see further details
   below).

   Designed to only work with initial INVITE messages! If a dialog
   is not already present, one will be created (equivalent of
   create_dialog()).

   Meaning of the parameters is as follows:
     * user (string) - 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 to keep different stats for
       different registered users.
     * number (string) - the number the user is calling to.
     * profile_id (int) - 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)
     Name DevScore Commits Lines ++ Lines --
   1. Liviu Chircu (@liviuchircu) 51 42 383 284
   2. Andrei Datcu (@andrei-datcu) 38 11 2665 235
   3. Razvan Crainea (@razvancrainea) 8 6 14 11
   4. Vlad Patrascu (@rvlad-patrascu) 8 5 73 114
   5. Bogdan-Andrei Iancu (@bogdan-iancu) 7 5 20 31
   6. Maksym Sobolyev (@sobomax) 5 3 7 8
   7. Ionut Ionita (@ionutrazvanionita) 3 1 21 6
   8. Peter Lemenkov (@lemenkov) 3 1 1 1

   (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
                     Name                   Commit Activity
   1. Maksym Sobolyev (@sobomax)          Jan 2021 - Feb 2023
   2. Liviu Chircu (@liviuchircu)         Mar 2015 - Aug 2022
   3. Razvan Crainea (@razvancrainea)     Feb 2015 - Oct 2021
   4. Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   5. Bogdan-Andrei Iancu (@bogdan-iancu) Oct 2014 - Apr 2019
   6. Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   7. Ionut Ionita (@ionutrazvanionita)   Jan 2016 - Jan 2016
   8. 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), Vlad Patrascu
   (@rvlad-patrascu), Peter Lemenkov (@lemenkov), Bogdan-Andrei
   Iancu (@bogdan-iancu), Andrei Datcu (@andrei-datcu).

   Documentation Copyrights:

   Copyright © 2014 www.opensips-solutions.com
