Difference between revisions of "Dynamic Blacklist Functionality"

From Kolmisoft Wiki
Jump to navigationJump to search
Line 13: Line 13:
[[File:Dynamic bl menu.png]]
[[File:Dynamic bl menu.png]]


=How does it work=
==How does it work==


When calls comes to MOR, system tries to find score for Source Number, Destination Number and SIP signaling IP. These scores are summed into single value:
When calls comes to MOR, system tries to find score for Source Number, Destination Number and SIP signaling IP. These scores are summed into single value:
Line 23: Line 23:
It is important to understand that Dynamic Blacklisting checks all three scores (DST, SRC and IP) before deciding whether call should be blacklisted (changed LCR) or not.
It is important to understand that Dynamic Blacklisting checks all three scores (DST, SRC and IP) before deciding whether call should be blacklisted (changed LCR) or not.


=Threshold=
==Threshold==


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

Revision as of 14:15, 23 November 2016

Dynamic Blacklisting

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

This functionality gives you 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 system owner wants to route 'suspect' calls through 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.

Dynamic Blacklisting settings

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

Dynamic bl menu.png

How does it work

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

TOTAL SCORE = DST SCORE + SRC SCORE + IP SCORE

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

It is important to understand that Dynamic Blacklisting checks all three scores (DST, SRC and IP) before deciding whether call 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 first one.

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

Blacklisting LCR

When 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 empty LCR, call will be hangup with code:

204	No suitable providers found

How score is calculated

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

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

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

Dynamic bl prefix scores.png

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

What happens when score is not set for prefix? For example, if someone dials 370xxxx but Prefix scores database does not have prefix for this number, then 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 score will not be saved to Blacklisting database. System will assume that numbers that are not present in Blacklisting database have default score and use that score when calculating Blacklisting score.

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 checks 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 Blacklisting Threshold value. If 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 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

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

If you want to import numbers to Blacklisting database, use following format in 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 RTP (media) of Originator.

Dynamic Blacklisting for specific Users

Dynamic Blacklisting blacklisting can be enabled globally to 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 specific User, go to 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 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 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 number length is lower than 6 digits

These rules are defined in:

/usr/local/mor/blacklist.conf

Configuration file contains all rules with examples:

; ABOUT THIS FILE
;
; This configuration file describes blacklisting rules


; Rule types explained below


; 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,370123456,1,5,10
; src,*,5,60,100
;
; Examples explained:
;
; 1. If src '370123456' makes 1 or more calls during 5 minutes period, its blacklisting score will be set to 10
; 2. If any src makes 5 or more calls during 1 hour period, its blacklisting score will be set to 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 set to 50
; 2. If dst '37062155555' is dialed 5 or more times during 60 minutes period, its blacklisting score will be set to 30
; 3. If any dst is dialed 10 or more times during 10 minutes period, its blacklisting score will be set to 10


; Type: dstduration
; Description: put a score on dst, based on call duration to this dst number in a defined time period
;
; Examples:
;
; dstduration,370,30,5,3,45
;
; 1. If within last 5 minutes there are at least 3 calls to dst number 370xxxxxx that have duration shorter than 30 seconds, then dst number's score will be set to 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,2,45
;
; 1. If within last minute there are at least 2 calls calls from any src number that have duration shorter than 60 seconds, then src number's score will be set to 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,5,10
;
; 1. If within last minute there are at least 5 calls to any dst number that has length shorter or equal to 6 charaters, then dst number's score will be set to 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,3,30
;
; 1. If within last 5 minutes there are at least 3 calls from any src number that has length shorter or equal to 2 charaters, then src number's score will be set to 30


; To comment out a rule, use ; character before rule


; Rules start here

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

Note that examples in your configuration file might be outdated, thefore 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 script does not work in realtime and blacklisted number are added to Blacklisting database within a minute or two.

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

Troubleshooting

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

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

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

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

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