Difference between revisions of "Dynamic Blacklist Functionality"

From Kolmisoft Wiki
Jump to navigationJump to search
 
(30 intermediate revisions by 7 users not shown)
Line 1: Line 1:
=Description=
=Dynamic Blacklisting=


Blacklist functionality is part of [[ Monitorings_Addon | Monitorings add-on]].
'''NOTE:''' This functionality can be used with a [http://wiki.kolmisoft.com/index.php/Monitorings_Addon Monitorings Addon] enabled only.


Blacklist functionality Dynamic Routing is based on a smart logic which puts a 'score' on the call by its SRC, DST or SIP signaling IP and allows routing calls with high score over different route. This functionality gives you an ability to define LCR as Blacklist Providers group. These Providers work like any other [[Providers | Provider]] in MOR system. MOR reroutes all the calls, that have a score more than a defined threshold, to this Blacklist LCR.  
Dynamic Blacklist functionality is based on a smart logic that puts a 'score' on the call by its Source Number, Destination Number, and SIP signaling IP and allows routing calls with a high score over a different route.  


This functionality is useful when system owner wants to route 'suspect' calls through different route than 'normal' calls.
This functionality gives you the ability to define Blacklist LCR. MOR reroutes all the calls, that have a score more than a defined threshold, to this Blacklist LCR. Dynamic Blacklisting is useful when the system owner wants to route 'suspect' calls through a different route than 'normal' calls.


Example: calls from such countries as Nigeria, Sudan, etc. based on their IP/CallerID can be marked as 'suspects' and routed to some IVR or to the dead-end.
Example: calls from such countries as Nigeria, Sudan, etc. based on their IP/CallerID can be marked as 'suspects' and routed to some IVR or to the dead-end.
If you are looking for simple Blacklisting implementation, refer to [[Static_Blacklist_and_Whitelist_functionality#Blacklists_.2F_Whitelists|Static Blacklist/Whitelist]]


<br><br>
<br><br>
==Dynamic Blacklisting settings==


=Configuration=
Dynamic Blacklisting settings are located in '''ADDONS''' -> '''Monitorings''' -> '''Dynamic Blacklisting''':


You can manage
[[File:Dynamic bl menu.png]]


* Single User settings in [[User_Details#Blacklists | User Details]]
* Global settings in '''ADDONS  –> Monitorings –> [[Monitorings_Addon#Monitorings_Settings | Settings]]'''
<br><br>
<br><br>
[[File:Monitorings_settings.png]]
==How does it work==
 
When calls come to MOR, the system tries to find the score for the Source Number, Destination Number, and SIP signaling IP. These scores are summed into a single value:
 
TOTAL SCORE = DST SCORE + SRC SCORE + IP SCORE
 
The total score is compared against the defined Blacklisting Threshold value. If the total score is equal to or higher than the Blacklisting Threshold value, the system changes LCR to the defined Backlisting LCR.
 
It is important to understand that Dynamic Blacklisting checks all three scores (DST, SRC, and IP) before deciding whether calls should be blacklisted (changed LCR) or not.
 
<br><br>
<br><br>
'''Blacklist Feature enabled''' – enables Blacklists functionality in all system.
==Threshold==


'''Threshold #1 - #3''' – sum of SRC, DST and SIP signaling IP limit. If SRC, DST or SIP signaling IP scores sum, received during the call, is bigger than particular Threshold, call will be routed through selected LCR.
Before using Dynamic Blacklisting you need to define Blacklisting Threshold values in '''ADDONS''' -> '''Monitoring''' -> '''Dynamic Blacklisting''' -> '''Settings''':


Threshold #1 must be lower than Threshold #2, Threshold #2 must be lower than Threshold #3. 0 stand for Disabled Threshold.
[[File:Dynamic bl settings thresholds.png]]


'''LCR''' – [[LCR]] with Balcklist Providers. First one will be used when SRC, DST it IP scores sum will be between Threshold #1 and Threshold #2. Second LCR will be used when SRC, DST it IP scores sum will be between Threshold #2 and Threshold #3. And third LCR will be used when SRC, DST it IP scores sum will be higher than Threshold #3.
You can use up to 3 different Threshold values but for simplicity, we will use only the first one.


'''Default scores''' – Default scores of SRC, DST or SIP signaling IP. There will be cases where MOR will not find a score for a given SRC, DST or SIP signaling IP. In each of the cases MOR will add the missing values from these settings.
The calculated Blacklisting total score will be compared to this value. If the calculated Blacklisting total score is equal to or higher than 100, the User’s current LCR will be changed to Blacklisting LCR. If the total score is lower than 100, the User’s LCR will not be changed.


'''Use default blacklisting rules''' – check this to use [[Blacklists#Blacklisting_Script | Blacklisting Script]] for SRC, DST or SIP signaling IP scoring.
<br><br>
==Blacklisting LCR==


This feature is designed to stop the score manipulation done by the blacklisting script (Intelligence). This feature is used in the situation where we want to disable the score number manipulation done by the blacklisting script but still keep the blacklist functionality.  
When the calculated Blacklisting score is higher than Blacklisting Threshold, User’s LCR is changed to Blacklisting LCR.


As an example, maybe we will notice in the future that we have incorrectly setup the blacklisting script rules and as a result we are getting some false positives into our blacklist. In this case we don't want to completely disable the blacklisting feature but just disable the blacklisting script until we have had enough time to go back to the CDR analyses and figure out the correct values that need to be defined for the correct functioning of the blacklisting script.
This LCR may contain specific Providers or can be completely empty. In case of an empty LCR, the call will be hangup with the code:


If the Use default blacklisting rules is set to no then the MOR system should continue to add source numbers, destination numbers and source IP addresses to the blacklist database, but the blacklist script should not run and change the database values.
204 No suitable providers found


<br><br>
<br><br>
==Blacklisting Script (Intelligence) ==
==How score is calculated==


'''MOR does not know anything about the script and does not care about it. This script is INDEPENDENT from MOR.'''
When a call comes to MOR, the Blacklisting score is calculated by finding the score for SRC, DST, and IP in the Blacklisting database.


What it will do is to try to figure out what a blacklisted call could look like. For example it could be that a customer of a customer tries to call one specific number more than 10 times a day or more than 5 times within one hour. Or there are many calls generated by one source phone number or one source IP media. It all depends on experience and assumptions and that may be different for all customers.
For example, let’s explain how the score is calculated for the Destination Number (DST). Source and IP score is calculated in the same way.


<br>
When a new number is dialed and it is not yet in the Blacklisting database, MOR tries to assign a score to the number by checking the Blacklisting prefix database, which can be defined in '''ADDONS''' -> '''Monitoring''' -> '''Dynamic Blacklisting''' -> '''Destinations (DST)''' -> '''Prefix scores''':
To use default blacklisting rules you have to create your own script:


* Script can be done in any language.
[[File:Dynamic bl prefix scores.png]]
* Script can be placed anywhere in the system
* It is advisable to run this script periodically with Cron
* It should analyze CDRs and make decisions based on various criteria.
* After that it should populate appropriate DB fields to put scores for various values.


<br>
For example, if someone dials 93xxxxxx, MOR assigns a score of 70 to this number and puts this number along with the score into the Blacklisting database. Next time this number is dialed, MOR will know the score by looking in the Blacklisting database.
The script to change scores could work like this:<br>


If a destination_number was called more than DST-n1 times within DST-t1 minutes then DST-Score = DST-Score + DST-v1<br>
What happens when the score is not set for the prefix? For example, if someone dials 370xxxx but the Prefix scores database does not have a prefix for this number, then the default score will be used. You can set default score in '''ADDONS''' -> '''Monitoring''' -> '''Dynamic Blacklisting''' -> '''Settings''':
If a destination_number was called more than DST-n2 times within DST-t2 hours then DST-Score = DST-Score + DST-v2<br>
If a source_number was calling more than SRC-n1 times within SRC-t1 minutes then SRC-Score = SRC-Score + SRC-v1<br>
If a source_number was calling more than SRC-n2 times within SRC-t2 hours then SRC-Score = SRC-Score + SRC-v2<br>
If a source_IP_number was calling more than SRC-IP-n1 times within SRC-IP-t1 minutes then SRC-IP-Score = SRC-IP-Score + SRC-IP-v1<br>
If a source_IP_number was calling more than SRC-IP-n2 times within SRC-IP-t2 hours then SRC-IP-Score = SRC-IP-Score + SRC-IP-v2<br>
If a source_number was calling more than SRC-n1 times within SRC-t1 minutes then DST-Score = DST-Score + DST-v1<br>
<br>
Variables like DST-n1 to SRC-IP-v2 need to be defined manually.
<br>
===Example===


If a destination_number was called more than 5 times within 60 minutes then DST-Score = DST-Score + 100<br>
[[File:Dynamic bl settings default scores.png]]
or<br>
If a source_IP_number was calling more than 40 times within 5 hours then SRC-IP-Score = SRC-IP-Score + 100<br>
or<br>
If a source_number was calling more than 1 time within 5 minutes then DST-Score = DST-Score + 50<br>


<br>
'''Note:''' numbers with default scores will not be saved to the Blacklisting database. The system will assume that numbers that are not present in the Blacklisting database have a default score and use that score when calculating the Blacklisting score.
'''NOTE:'''  
It is '''not possible''' to set X amount of times within X amount of '''seconds'''


It '''should be''' set X amount of times within X amount of '''minutes''' (not seconds).
The same principle is used for SRC and IP score - ''' when call comes MOR, Dynamic Blacklisting checks if DST/SRC/IP is in Backlisting database, if not then check if prefix exists in Blacklisting prefixes database, if not then uses default Blacklisting score.'''


Moreover, script will not block immediately. It depends on how often '''cron''' launch blacklisting script.
These 3 scores are summed (DST score + SRC score + IP Score) and compared against the Blacklisting Threshold value. If the total score is equal or higher, then User’s LCR will be changed to Blacklisting LCR.


If you use only DST blacklisting, you may leave Default SRC and Default IP scores 0. This way it will be easier to calculate the Blacklisting score (DST score + 0 + 0).


If you want to create such script, please contact Kolmisoft, we will consult how to do this, will provide necessary database info and all other details.
<br><br>
==Blacklisting database==
 
You can check already blacklisted numbers in '''ADDONS''' -> '''Monitoring''' -> '''Dynamic Blacklisting''' -> '''Destinations (DST)''':
 
[[File:Dynamic bl scores.png]]
 
On this page, you can find, add, update or delete numbers.
 
If you want to import numbers to the Blacklisting database, use the following format in a CSV file:
 
number1;score
number2;score
number3;score


<br><br>
<br><br>
==SIP signaling IP==


==Blacklisting configuration file with examples==
Due to technical limitations, Dynamic Blacklisting will use SIP signaling IP which may be different from the RTP (media) of the Originator.


  ; ABOUT THIS FILE
==Dynamic Blacklisting for specific Users==
  ;
 
  ; This configuration file describes blacklisting rules
Dynamic Blacklisting blacklisting can be enabled globally for all Users or for specific Users only.
 
 
 
If you want to enable Dynamic Blacklisting globally, go to '''ADDONS''' -> '''Monitoring''' -> '''Dynamic Blacklisting''' -> '''Settings''' and check '''Blacklist Feature enabled''' checkbox.
  ; Rules have the following structure:
 
  ;
If you want to enable Dynamic Blacklisting for a specific User, go to the User’s edit page and change settings under '''Blacklisting / Whitelisting''' section:
  ; type,prefix,count,period,score
 
  ;
[[File:Dynamic bl user settings.png]]
  ; type  - type of rule (src/dst/ip/dstsrc/dstduration/srcduration/srclength/dstlength/srcbldst)
 
  ; prefix - prefix or keyword (only for src) used to match the target (src/dst/ip)
<br><br>
  ; count  - how many TIMES this target can be dialed/make calls during specified period of time (in minutes), before this rule is applied
=Dynamic Blacklisting script (advanced)=
  ; period - defines the PERIOD of time (in minutes) which is used to check calls (takes all calls made within last X minutes)
 
  ; score  - score that will be ADDED to previous score of the target
Dynamic Blacklisting script allows to add numbers to the Dynamic Blacklisting database based on Blacklisting rules.
  ;
 
  ; Note1: to match all the targets of the same rule type, use * symbol instead of prefix
Some examples of Blacklisting rules:
  ; Note2: in case of dstduration and srcduration, count is time in seconds of a call
 
  ; Note3: in case of dstlength and srclength, count is the length of the number
* Set score 100 to DST number if there are 2 or more calls during 5 minutes to the same number
  ; Note4: in case of dstsrc rule, you can you EMPTY keyword instead prefix. This allows to block dst if numbers without src are calling to this dst
* Set score 100 to DST number if there are 5 or more calls with a duration lower than 30 seconds to the same number
  ; Note5: in case of srcbldst rule, count is blacklisting score of dst number
* Set score 100 to DST number if there are 3 or more calls to the same number and the number length is lower than 6 digits
  ;
 
  ; Rule types explained
The minimal check time is 1 minute (you cannot create a rule 'set score X if there are 10 or more calls during 30 seconds). Maximum time 24 hours.
 
The script is set to run every minute, so if the script is set to block new calls as in 1st example, the script will check if calls should be blocked every minute.
 
 
  ; Type: src
 
   ; Description: put a score on src, based on src number and number of calls FROM that src in a defined time period
These rules are defined in:
  ;
 
  ; Examples:
/usr/local/mor/blacklist.conf
  ;
 
  ; src,mor,1,5,10
The configuration file contains all rules with examples:
  ; src,1001,1,10,20
 
  ;
; Rules have the following structure:
  ; Examples explained:
;
  ;
; type,prefix,count,period,score
  ; 1. If src 'accountant_mor_25' makes 1 or more calls during 5 minutes period, its blacklisting score will be updated by 10
;
  ; 2. If src '1001' makes 1 or more calls during 10 minutes period, its blacklisting score will be updated by 20
; type   - type of rule (src/dst/ip/dstsrc/dstduration/srcduration/srclength/dstlength/srcbldst)
 
; prefix - prefix or keyword (only for src) used to match the target (src/dst/ip)
 
; count  - how many TIMES this target can be dialed/make calls during specified period of time (in minutes), before this rule is applied
  ; Type: dst
; period - defines the PERIOD of time (in minutes) which is used to check calls (takes all calls made within last X minutes)
  ; Description: put a score on dst, based on dst number and number of calls TO that dst in a defined time period
; score  - score that will be ADDED to previous score of the target
  ;
;
  ; Examples:
; Note1: to match all the targets of the same rule type, use * symbol instead of prefix
  ;
; Note2: in case of dstduration and srcduration, count is time in seconds of a call
  ; dst,370,5,60,50
; Note3: in case of dstlength and srclength, count is the length of the number
  ; dst,37621,5,60,30
; Note4: in case of dstsrc rule, you can you EMPTY keyword instead prefix. This allows to block dst if numbers without src are calling to this dst
  ; dst,*,10,10,10
; Note5: in case of srcbldst rule, count is blacklisting score of dst number
  ;
;
  ; Examples explained:
; Rule types explained
  ;
  ; 1. If dst '37062255555' is dialed 5 or more times during 60 minutes period, its blacklisting score will be increased by 50
  ; 2. If dst '37062155555' is dialed 5 or more times during 60 minutes period, its blacklisting score will be increased by 30
; Type: src
  ; 3. If any dst is dialed 10 or more times during 10 minutes period, its blacklisting score will be increased by 10
; Description: put a score on src, based on src number and number of calls FROM that src in a defined time period
 
;
 
; Examples:
  ; Type: ip
;
  ; Description: put a score on ip, based on ip address and number of calls FROM that ip address in a defined time period
; src,mor,1,5,10
  ;
; src,1001,1,10,20
  ; Examples:
;
  ;
; Examples explained:
  ; ip,78.35,1,15,1
;
  ;
; 1. If src 'accountant_mor_25' makes 1 or more calls during 5 minutes period, its blacklisting score will be updated by 10
  ; Examples explained:
; 2. If src '1001' makes 1 or more calls during 10 minutes period, its blacklisting score will be updated by 20
  ;
  ; 1. If ip '78.35.45.21' makes 1 or more calls during 15 minutes period, its blacklisting score will be increased by 1
 
; Type: dst
 
; Description: put a score on dst, based on dst number and number of calls TO that dst in a defined time period
  ; Type: dstsrc
;
  ; Description: put a score on dst, based on src number and number of calls FROM that src in a defined time period
; Examples:
  ;
;
  ; Examples:
; dst,370,5,60,50
  ;
; dst,37621,5,60,30
  ; dstsrc,anonymous,1,5,50
; dst,*,10,10,10
  ; dstsrc,EMPTY,1,5,50
;
  ;  
; Examples explained:
  ; 1. If src 'anonymous' makes 1 or more calls during 5 minutes period, then blacklisting score will be increased by 50 TO THE NUMBER USER HAS DIALED (dst number)
;
  ; 2. If call with no src makes 1 or more calls during 5 minutes period, then blacklisting score will be increased by 50 TO THE NUMBER USER HAS DIALED (dst number)
; 1. If dst '37062255555' is dialed 5 or more times during 60 minutes period, its blacklisting score will be increased by 50
 
; 2. If dst '37062155555' is dialed 5 or more times during 60 minutes period, its blacklisting score will be increased by 30
 
; 3. If any dst is dialed 10 or more times during 10 minutes period, its blacklisting score will be increased by 10
  ; Type: dstduration
  ; Description: put a score on dst, based on lowest call duration to this dst number in a defined time period
  ;
; Type: IP
  ; Examples:
; Description: put a score on ip, based on ip address and number of calls FROM that ip address in a defined time period
  ;
;
  ; dstduration,370,30,5,45
; Examples:
  ;  
;
  ; 1. If within last 5 minutes there are calls to dst number 370xxxxxx that have duration shorter than 30 seconds, then dst number's score will be increased by 45
; ip,78.35,1,15,1
 
;
 
; Examples explained:
  ; Type: srcduration
;
  ; Description: put a score on src, based on lowest call duration from this src number in a defined time period
; 1. If ip '78.35.45.21' makes 1 or more calls during 15 minutes period, its blacklisting score will be increased by 1
  ;
  ; Examples:
  ;
; Type: dstsrc
  ; srcduration,*,60,1,45
; Description: put a score on dst, based on src number and number of calls FROM that src in a defined time period
  ;  
;
  ; 1. If within last minute there are calls from any src number that have duration shorter than 60 seconds, then src number's score will be increased by 45
; Examples:
 
;
 
; dstsrc,anonymous,1,5,50
  ; Type: dstlength
; dstsrc,EMPTY,1,5,50
  ; Description: put a score on dst, based on length of dst number and number of calls to this dst in a defined time period
;  
  ;
; 1. If src 'anonymous' makes 1 or more calls during 5 minutes period, then blacklisting score will be increased by 50 TO THE NUMBER USER HAS DIALED (dst number)
  ; Examples:
; 2. If call with no src makes 1 or more calls during 5 minutes period, then blacklisting score will be increased by 50 TO THE NUMBER USER HAS DIALED (dst number)
  ;
  ; dstlength,*,6,1,10
  ;  
; Type: dstduration
  ; 1. If within last minute there are calls to any dst number that has length shorter or equal to 6 charaters, then dst number's score will be increased by 10
; Description: put a score on dst, based on lowest call duration to this dst number in a defined time period
  ;
;
  ; In this case:
; Examples:
  ;
;
  ; Number 370621 will be blacklisted
; dstduration,370,30,5,45
  ; Number 3706215 will not be blacklisted
;
 
; 1. If within last 5 minutes there are calls to dst number 370xxxxxx that have duration shorter than 30 seconds, then dst number's score will be increased by 45
 
  ; Type: srclength
  ; Description: put a score on src, based on length of src number and number of calls to this dst in a defined time period
; Type: srcduration
  ;
; Description: put a score on src, based on lowest call duration from this src number in a defined time period
  ; Examples:
;
  ;
; Examples:
  ; srclength,*,2,5,30
;
  ;  
; srcduration,*,60,1,45
  ; 1. If within last 5 minutes there are calls from any src number that has length shorter or equal to 2 charaters, then src number's score will be increased by 30
;
 
; 1. If within last minute there are calls from any src number that have duration shorter than 60 seconds, then src number's score will be increased by 45
 
  ; Type: srcbldst
  ; Description: put a score on src if user calls to dst which has equal or higher score than defined
; Type: dstlength
  ;
; Description: put a score on dst, based on length of dst number and number of calls to this dst in a defined time period
  ; Examples:
;
  ;
; Examples:
  ; srcbldst,*,60,2,30
;
  ;
; dstlength,*,6,1,10
  ; 1. If within last 2 minutes any src number made a call to dst which has blacklisting score 60 or higher, then src number's score will be increased by 30
;  
 
; 1. If within last minute there are calls to any dst number that has length shorter or equal to 6 charaters, then dst number's score will be increased by 10
 
;
  ; To comment out a rule, use ; character before rule
; In this case:
  ;
;
  ; Note: only one rule will be applied to the same src/dst/ip so rules should be ordered by prefix length (from longest to shortest (or *))
; Number 370621 will be blacklisted
 
; Number 3706215 will not be blacklisted
  ; Rules start here, please modify them
 
 
; Type: srclength
  src,mor,1,5,10
; Description: put a score on src, based on length of src number and number of calls to this dst in a defined time period
  src,1001,1,10,20
;
; Examples:
;
; srclength,*,2,5,30
;
; 1. If within last 5 minutes there are calls from any src number that has length shorter or equal to 2 charaters, then src number's score will be increased by 30
; Type: srcbldst
; Description: put a score on src if user calls to dst which has equal or higher score than defined
;
; Examples:
;
; srcbldst,*,60,2,30
;
; 1. If within last 2 minutes any src number made a call to dst which has blacklisting score 60 or higher, then src number's score will be increased by 30
; To comment out a rule, use ; character before rule
;
; Note: only one rule will be applied to the same src/dst/ip so rules should be ordered by prefix length (from longest to shortest (or *))
; Rules start here, please modify them
Add your rules at the end of blacklist.conf file.
 
Note that examples in your configuration file might be outdated, therefore use examples from this page.
 
This script can be enabled or disabled at any time. Check '''Enable Dynamic Blacklisting script''' checkbox in '''ADDONS''' -> '''Monitoring''' -> '''Dynamic Blacklisting''' -> '''Settings''':
 
[[File:Dynamic bl settings enable script.png]]
 
Note that the script does not work in real-time and blacklisted numbers are added to the Blacklisting database within a minute or two.
 
Also, only a single rule is applied to the same number at a time so order your rules by priority.
 
<br><br>
=Troubleshooting=
 
To enable verbose Dynamic Blacklisting log in /var/log/asterisk/messages, and make sure that debug messages are included in /etc/asterisk/logger.conf file, for example:
 
messages => notice, warning, error, debug, verbose
 
Most Dynamic Blacklisting log messages are [DEBUG] type messages.
 
If you are using a Dynamic Blacklisting script, make sure that the script is executed by cron. Check if /etc/cron.d/mor_blacklisting_script cron is present.
 
Log for the Dynamic Blacklisting script can be found in /var/log/mor/mor_blacklisting_script.log
 
 
 
<br><br>
 
= SIM Blocking =
In some cases, Dynamic Blacklisting functionality can be used for SIM blocking prevention. Such cases are when you know for sure that the operator is using specific calls pattern to detect not-Retail traffic and you know what that pattern is and when Blacklisting functionality supports rules for that pattern. In such cases properly configured rules (individual on each case) '''may''' help.
 
Please note that different operators are using different techniques to detect non-Retail traffic. There is no universal formula or method to prevent SIM Blocking. It is possible that the Operator simply reviews CDRs of specific SIM in order to detect not-Retail traffic. In such case, Blacklisting will not help with SIM blocking anyhow.
 
 
<br><br>


=See also=
= See also =


* [[Monitorings_Addon#Monitorings_Settings | Monitorings Settings]]
* [[Static_Blacklist_and_Whitelist_functionality#Blacklists_.2F_Whitelists|Static Blacklist/Whitelist]]
* [[User_Details#Blacklists | User Details]]
* [[Monitorings Addon]]
* [[LCR]]

Latest revision as of 06:46, 1 December 2022

Dynamic Blacklisting

NOTE: This functionality can be used with a Monitorings Addon enabled only.

Dynamic Blacklist functionality is based on a smart logic that puts a 'score' on the call by its Source Number, Destination Number, and SIP signaling IP and allows routing calls with a high score over a different route.

This functionality gives you the ability to define Blacklist LCR. MOR reroutes all the calls, that have a score more than a defined threshold, to this Blacklist LCR. Dynamic Blacklisting is useful when the system owner wants to route 'suspect' calls through a different route than 'normal' calls.

Example: calls from such countries as Nigeria, Sudan, etc. based on their IP/CallerID can be marked as 'suspects' and routed to some IVR or to the dead-end.

If you are looking for simple Blacklisting implementation, refer to Static Blacklist/Whitelist



Dynamic Blacklisting settings

Dynamic Blacklisting settings are located in ADDONS -> Monitorings -> Dynamic Blacklisting:

Dynamic bl menu.png



How does it work

When calls come to MOR, the system tries to find the score for the Source Number, Destination Number, and SIP signaling IP. These scores are summed into a single value: 

TOTAL SCORE = DST SCORE + SRC SCORE + IP SCORE

The total score is compared against the defined Blacklisting Threshold value. If the total score is equal to or higher than the Blacklisting Threshold value, the system changes LCR to the defined Backlisting LCR.

It is important to understand that Dynamic Blacklisting checks all three scores (DST, SRC, and IP) before deciding whether calls should be blacklisted (changed LCR) or not.



Threshold

Before using Dynamic Blacklisting you need to define Blacklisting Threshold values in ADDONS -> Monitoring -> Dynamic Blacklisting -> Settings:

Dynamic bl settings thresholds.png

You can use up to 3 different Threshold values but for simplicity, we will use only the first one.

The calculated Blacklisting total score will be compared to this value. If the calculated Blacklisting total score is equal to or higher than 100, the User’s current LCR will be changed to Blacklisting LCR. If the total score is lower than 100, the User’s LCR will not be changed.



Blacklisting LCR

When the calculated Blacklisting score is higher than Blacklisting Threshold, User’s LCR is changed to Blacklisting LCR.

This LCR may contain specific Providers or can be completely empty. In case of an empty LCR, the call will be hangup with the code: 

204	No suitable providers found



How score is calculated

When a call comes to MOR, the Blacklisting score is calculated by finding the score for SRC, DST, and IP in the Blacklisting database.

For example, let’s explain how the score is calculated for the Destination Number (DST). Source and IP score is calculated in the same way.

When a new number is dialed and it is not yet in the Blacklisting database, MOR tries to assign a score to the number by checking the Blacklisting prefix database, which can be defined in ADDONS -> Monitoring -> Dynamic Blacklisting -> Destinations (DST) -> Prefix scores:

Dynamic bl prefix scores.png

For example, if someone dials 93xxxxxx, MOR assigns a score of 70 to this number and puts this number along with the score into the Blacklisting database. Next time this number is dialed, MOR will know the score by looking in the Blacklisting database.

What happens when the score is not set for the prefix? For example, if someone dials 370xxxx but the Prefix scores database does not have a prefix for this number, then the default score will be used. You can set default score in ADDONS -> Monitoring -> Dynamic Blacklisting -> Settings:

Dynamic bl settings default scores.png

Note: numbers with default scores will not be saved to the Blacklisting database. The system will assume that numbers that are not present in the Blacklisting database have a default score and use that score when calculating the Blacklisting score.

The same principle is used for SRC and IP score - when call comes MOR, Dynamic Blacklisting checks if DST/SRC/IP is in Backlisting database, if not then check if prefix exists in Blacklisting prefixes database, if not then uses default Blacklisting score.

These 3 scores are summed (DST score + SRC score + IP Score) and compared against the Blacklisting Threshold value. If the total score is equal or higher, then User’s LCR will be changed to Blacklisting LCR.

If you use only DST blacklisting, you may leave Default SRC and Default IP scores 0. This way it will be easier to calculate the Blacklisting score (DST score + 0 + 0).



Blacklisting database

You can check already blacklisted numbers in ADDONS -> Monitoring -> Dynamic Blacklisting -> Destinations (DST):

Dynamic bl scores.png

On this page, you can find, add, update or delete numbers.

If you want to import numbers to the Blacklisting database, use the following format in a CSV file: 

number1;score
number2;score
number3;score



SIP signaling IP

Due to technical limitations, Dynamic Blacklisting will use SIP signaling IP which may be different from the RTP (media) of the Originator.

Dynamic Blacklisting for specific Users

Dynamic Blacklisting blacklisting can be enabled globally for all Users or for specific Users only.

If you want to enable Dynamic Blacklisting globally, go to ADDONS -> Monitoring -> Dynamic Blacklisting -> Settings and check Blacklist Feature enabled checkbox.

If you want to enable Dynamic Blacklisting for a specific User, go to the User’s edit page and change settings under Blacklisting / Whitelisting section:

Dynamic bl user settings.png



Dynamic Blacklisting script (advanced)

Dynamic Blacklisting script allows to add numbers to the Dynamic Blacklisting database based on Blacklisting rules.

Some examples of Blacklisting rules:

  • Set score 100 to DST number if there are 2 or more calls during 5 minutes to the same number
  • Set score 100 to DST number if there are 5 or more calls with a duration lower than 30 seconds to the same number
  • Set score 100 to DST number if there are 3 or more calls to the same number and the number length is lower than 6 digits

The minimal check time is 1 minute (you cannot create a rule 'set score X if there are 10 or more calls during 30 seconds). Maximum time 24 hours. The script is set to run every minute, so if the script is set to block new calls as in 1st example, the script will check if calls should be blocked every minute.


These rules are defined in: 

/usr/local/mor/blacklist.conf

The configuration file contains all rules with examples: 

; Rules have the following structure: 
;
; type,prefix,count,period,score
;
; type   - type of rule (src/dst/ip/dstsrc/dstduration/srcduration/srclength/dstlength/srcbldst)
; prefix - prefix or keyword (only for src) used to match the target (src/dst/ip)
; count  - how many TIMES this target can be dialed/make calls during specified period of time (in minutes), before this rule is applied
; period - defines the PERIOD of time (in minutes) which is used to check calls (takes all calls made within last X minutes)
; score  - score that will be ADDED to previous score of the target
;
; Note1: to match all the targets of the same rule type, use * symbol instead of prefix
; Note2: in case of dstduration and srcduration, count is time in seconds of a call
; Note3: in case of dstlength and srclength, count is the length of the number
; Note4: in case of dstsrc rule, you can you EMPTY keyword instead prefix. This allows to block dst if numbers without src are calling to this dst
; Note5: in case of srcbldst rule, count is blacklisting score of dst number
;
; Rule types explained


; Type: src
; Description: put a score on src, based on src number and number of calls FROM that src in a defined time period
;
; Examples:
;
; src,mor,1,5,10
; src,1001,1,10,20
;
; Examples explained:
;
; 1. If src 'accountant_mor_25' makes 1 or more calls during 5 minutes period, its blacklisting score will be updated by 10
; 2. If src '1001' makes 1 or more calls during 10 minutes period, its blacklisting score will be updated by 20


; Type: dst
; Description: put a score on dst, based on dst number and number of calls TO that dst in a defined time period
;
; Examples:
;
; dst,370,5,60,50
; dst,37621,5,60,30
; dst,*,10,10,10
;
; Examples explained:
;
; 1. If dst '37062255555' is dialed 5 or more times during 60 minutes period, its blacklisting score will be increased by 50
; 2. If dst '37062155555' is dialed 5 or more times during 60 minutes period, its blacklisting score will be increased by 30
; 3. If any dst is dialed 10 or more times during 10 minutes period, its blacklisting score will be increased by 10


; Type: IP
; Description: put a score on ip, based on ip address and number of calls FROM that ip address in a defined time period
;
; Examples:
;
; ip,78.35,1,15,1
;
; Examples explained:
;
; 1. If ip '78.35.45.21' makes 1 or more calls during 15 minutes period, its blacklisting score will be increased by 1


; Type: dstsrc
; Description: put a score on dst, based on src number and number of calls FROM that src in a defined time period
;
; Examples:
;
; dstsrc,anonymous,1,5,50
; dstsrc,EMPTY,1,5,50
; 
; 1. If src 'anonymous' makes 1 or more calls during 5 minutes period, then blacklisting score will be increased by 50 TO THE NUMBER USER HAS DIALED (dst number)
; 2. If call with no src makes 1 or more calls during 5 minutes period, then blacklisting score will be increased by 50 TO THE NUMBER USER HAS DIALED (dst number)


; Type: dstduration
; Description: put a score on dst, based on lowest call duration to this dst number in a defined time period
;
; Examples:
;
; dstduration,370,30,5,45
; 
; 1. If within last 5 minutes there are calls to dst number 370xxxxxx that have duration shorter than 30 seconds, then dst number's score will be increased by 45


; Type: srcduration
; Description: put a score on src, based on lowest call duration from this src number in a defined time period
;
; Examples:
;
; srcduration,*,60,1,45
; 
; 1. If within last minute there are calls from any src number that have duration shorter than 60 seconds, then src number's score will be increased by 45


; Type: dstlength
; Description: put a score on dst, based on length of dst number and number of calls to this dst in a defined time period
;
; Examples:
;
; dstlength,*,6,1,10
; 
; 1. If within last minute there are calls to any dst number that has length shorter or equal to 6 charaters, then dst number's score will be increased by 10
;
; In this case:
;
; Number 370621 will be blacklisted
; Number 3706215 will not be blacklisted


; Type: srclength
; Description: put a score on src, based on length of src number and number of calls to this dst in a defined time period
;
; Examples:
;
; srclength,*,2,5,30
; 
; 1. If within last 5 minutes there are calls from any src number that has length shorter or equal to 2 charaters, then src number's score will be increased by 30


; Type: srcbldst
; Description: put a score on src if user calls to dst which has equal or higher score than defined
;
; Examples:
;
; srcbldst,*,60,2,30
;
; 1. If within last 2 minutes any src number made a call to dst which has blacklisting score 60 or higher, then src number's score will be increased by 30 


; To comment out a rule, use ; character before rule
;
; Note: only one rule will be applied to the same src/dst/ip so rules should be ordered by prefix length (from longest to shortest (or *))

; Rules start here, please modify them

Add your rules at the end of blacklist.conf file.

Note that examples in your configuration file might be outdated, therefore use examples from this page.

This script can be enabled or disabled at any time. Check Enable Dynamic Blacklisting script checkbox in ADDONS -> Monitoring -> Dynamic Blacklisting -> Settings:

Dynamic bl settings enable script.png

Note that the script does not work in real-time and blacklisted numbers are added to the Blacklisting database within a minute or two.

Also, only a single rule is applied to the same number at a time so order your rules by priority.



Troubleshooting

To enable verbose Dynamic Blacklisting log in /var/log/asterisk/messages, and make sure that debug messages are included in /etc/asterisk/logger.conf file, for example: 

messages => notice, warning, error, debug, verbose

Most Dynamic Blacklisting log messages are [DEBUG] type messages.

If you are using a Dynamic Blacklisting script, make sure that the script is executed by cron. Check if /etc/cron.d/mor_blacklisting_script cron is present.

Log for the Dynamic Blacklisting script can be found in /var/log/mor/mor_blacklisting_script.log




SIM Blocking

In some cases, Dynamic Blacklisting functionality can be used for SIM blocking prevention. Such cases are when you know for sure that the operator is using specific calls pattern to detect not-Retail traffic and you know what that pattern is and when Blacklisting functionality supports rules for that pattern. In such cases properly configured rules (individual on each case) may help.

Please note that different operators are using different techniques to detect non-Retail traffic. There is no universal formula or method to prevent SIM Blocking. It is possible that the Operator simply reviews CDRs of specific SIM in order to detect not-Retail traffic. In such case, Blacklisting will not help with SIM blocking anyhow.




See also

Retrieved from "https://wiki.kolmisoft.com/index.php?title=Dynamic_Blacklist_Functionality&oldid=28283"