This module has been designed to offer an additional layer of security over our communications. To achieve this, the following features are available:

- Blacklist to block user agents, IP addresses, countries, domains and users.

- Whitelist to allow user agents, IP addresses, countries, domains and users.

- Blacklist of destinations where the called number is not allowed.

- SQL injection attacks prevention.

When a function is called, it will be searched in the whitelist. If the value is not found, then the blacklist will be searched.

All data will be loaded into memory when the module is started. There is an RPC reload command to update all the data from database. It is also possible to add new data to the blacklist or whitelist using other RPC commands.

2. Dependencies

2.1. Kamailio Modules

The following modules must be loaded before this module:

database -- Any db_* database module

2.2. External Libraries or Applications

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

none

3. Parameters

3.1. `db_url` (string)

Database URL.

Default value is ""

Example 1.1. Set db_url parameter

		...
		modparam("secfilter", "db_url", "mysql://user:pass@localhost/kamailio")
		...

3.2. `table_name` (string)

Name of the table used to store the blacklisted and whitelisted values.

Default value is secfilter

Example 1.2. Set table_name parameter

		...
		modparam("secfilter", "table_name", "secfilter")
		...

3.3. `action_col` (string)

Name of database column containing the type of list. The possible values are:

0 = blacklisted data
1 = whitelisted data
2 = blacklisted destination number

Default value is action

Example 1.3. Set action_col parameter

		...
		modparam("secfilter", "action_col", "action")
		...

3.4. `type_col` (string)

Name of database column containing the type of values. The possible values are:

0 = user-agent (if action=0 or action=1)
0 = destination number (if action=2)
1 = country
2 = domain
3 = IP address
4 = user

Default value is type

Example 1.4. Set type_col parameter

		...
		modparam("secfilter", "type_col", "type")
		...

3.5. `data_col` (string)

Name of database column containing blacklisted and whitelisted values.

Default value is data

Example 1.5. Set data_col parameter

		...
		modparam("secfilter", "data_col", "data")
		...

3.6. `dst_exact_match` (integer)

This value is used in the destinations blacklist and corresponds to the numbers that we want to prevent calling. If the value is 1, the call will appear as blacklisted if the destination is exactly the same. If the value is 0, every destination whose number begins with a number appearing on the destination blacklist will be rejected.

Default value is 1

Example 1.6. Set dst_exact_match parameter

		...
		modparam("secfilter", "dst_exact_match", 1)
		...

4. Functions

4.1. `secf_check_ip ()`

It checks if the source IP address is blacklisted. The search is aproximate and data stored in the database will be compared as a prefix. For example, if we have blacklisted IP address 192.168.1. all messages from IPs like 192.168.1.% will be rejected.

Return values are:

2 = the value is whitelisted
1 = the value is not found
-2 = the value is blacklisted

Example 1.7. secf_check_ip usage

		...
        secf_check_ip();
        if ($? == -2) {
                xlog("L_ALERT", "$rm from $si blocked because IP address is blacklisted");
                exit;
        }
		...

4.2. `secf_check_ua ()`

It checks if the user-agent is blacklisted. The search is approximate and the comparison will be made using the values of the database as a prefix. If we add to the user-agent blacklist the word sipcli, every message whose user-agent is named, for example, sipcli/1.6 or sipcli/1.8 will be blocked. It is very useful to block different versions of the same program.

Return values are:

2 = the value is whitelisted
1 = the value is not found
-1 = error
-2 = the value is blacklisted

Example 1.8. secf_check_ua usage

		...
        secf_check_ua();
        if ($? == -2) {
                xlog("L_ALERT", "$rm from $si blocked because UserAgent '$ua' is blacklisted");
                exit;
        }
		...

4.3. `secf_check_country (string)`

Similar to secf_check_ua. It checks if the country (IP address) is blacklisted. Geoip module must be loaded to get the country code.

Return values are:

2 = the value is whitelisted
1 = the value is not found
-1 = error
-2 = the value is blacklisted

Example 1.9. secf_check_country usage

		...
        if (geoip2_match("$si", "src")) {
                secf_check_country($gip2(src=>cc));
                if ($avp(secfilter) == -2) {
                        xlog("L_ALERT", "$rm from $si blocked because Country '$gip2(src=>cc)' is blacklisted");
                        exit;
                }
        }
		...

4.4. `secf_check_from_hdr ()`

It checks if any value of from header is blacklisted. It checks if from name or from user are in the users blacklist or whitelist. It also checks if the from domain is in the domains blacklist or whitelist. The blacklisted value will be used as a prefix and if we block, for example, the user sipvicious, all users whose name starts with this word will be considered as blacklisted.

Return values are:

4 = from name is whitelisted
3 = from domain is whitelisted
2 = from user is whitelisted
1 = from header not found
-1 = error
-2 = from user is blacklisted
-3 = from domain is blacklisted
-4 = from name is blacklisted

Example 1.10. secf_check_from_hdr usage

		...
        secf_check_from_hdr();
        switch ($?) {
                case -2:
                        xlog("L_ALERT", "$rm to $si blocked because From user '$fU' is blacklisted");
                        exit;
                case -3:
                        xlog("L_ALERT", "$rm to $si blocked because From domain '$fd' is blacklisted");
                        exit;
                case -4:
                        xlog("L_ALERT", "$rm to $si blocked because From name '$fn' is blacklisted");
                        exit;
        };
		...

4.5. `secf_check_to_hdr ()`

Do the same as secf_check_from_hdr function but with the to header.

Return values are:

4 = to name is whitelisted
3 = to domain is whitelisted
2 = to user is whitelisted
1 = to header not found
-1 = error
-2 = to user is blacklisted
-3 = to domain is blacklisted
-4 = to name is blacklisted

Example 1.11. secf_check_to_hdr usage

		...
        secf_check_to_hdr();
        switch ($?) {
                case -2:
                        xlog("L_ALERT", "$rm to $si blocked because To user '$tU' is blacklisted");
                        exit;
                case -3:
                        xlog("L_ALERT", "$rm to $si blocked because To domain '$td' is blacklisted");
                        exit;
                case -4:
                        xlog("L_ALERT", "$rm to $si blocked because To name '$tn' is blacklisted");
                        exit;
        };
		...

4.6. `secf_check_contact_hdr ()`

Do the same as secf_check_from_hdr function but with the contact header.

Return values are:

3 = contact domain is whitelisted
2 = contact user is whitelisted
1 = contact header not found
-1 = error
-2 = contact user is blacklisted
-3 = contact domain is blacklisted

Example 1.12. secf_check_contact_hdr usage

		...
        secf_check_contact_hdr();
        switch ($?) {
                case -2:
                        xlog("L_ALERT", "$rm to $si blocked because Contact user '$ct' is blacklisted");
                        exit;
                case -3:
                        xlog("L_ALERT", "$rm to $si blocked because Contact domain '$ct' is blacklisted");
                        exit;
        };
		...

4.7. `secf_check_dst (string)`

It checks if the destination number is blacklisted. It must be user for INVITE messages. If the value of dst_exact_match is 1, the call will appear as blacklisted if the destination is exactly the same. If the value is 0, every destination whose number begins with a number appearing on the destination blacklist will be rejected.

Return values are:

2 (if the value is whitelisted)
1 (if the value not found)
-2 (if the value is blacklisted)

Example 1.13. secf_check_dst usage

		...
		if (is_method("INVITE")) {
			secf_check_dst($rU);
			if ($? == -2) {
				xlog("L_ALERT", "$rm from $si blocked because destination $rU is blacklisted");
				send_reply("403", "Forbidden");
				exit;
			}
		}
		...

4.8. `secf_check_sqli_hdr (string)`

Search for illegal characters in the given value.

Example 1.14. secf_check_sqli_hdr usage

		...
        secf_check_sqli_hdr($ua);
        if ($? == -1) {
                xlog("L_ALERT", "$rm from $si blocked because possible SQLi found in the user-agent header ($ua)");
                exit;
        }

		...

4.9. `secf_check_sqli_all ()`

Search for illegal characters in several headers (user-agent, from, to and contact). If illegal characters are found the message will be dropped.

Example 1.15. secf_check_sqli_all usage

		...
		secf_check_sqli_all();
		...

5. RPC commands

5.1. `secfilter.reload`

Reload all blacklisted and whitelisted values from database.

Example 1.16. secfilter.reload usage

		...
		kamcmd secfilter.reload
		...

5.2. `secfilter.print`

Print blacklisted and whitelisted values. Without parameters it will print all values. If you enter a type it will print this type values only.

Possible values are:

(none) (show all data)
ua (show blacklisted and whitelisted user-agents)
country (show blacklisted and whitelisted countries)
domain (show blacklisted and whitelisted domains)
user (show blacklisted and whitelisted users)
ip (show blacklisted and whitelisted IP addresses)
dst (show blacklisted destinations)

Example 1.17. secfilter.print usage

		...
		kamcmd secfilter.print
		kamcmd secfilter.print ua
		kamcmd secfilter.print country
		kamcmd secfilter.print dst
		...

5.3. `secfilter.stats`

Print statistics of blocked and allowed messages.

Example 1.18. secfilter.stats usage

		...
		kamcmd secfilter.stats
		...

5.4. `secfilter.stats_reset`

Reset all statistics.

Example 1.19. secfilter.stats_reset usage

		...
		kamcmd secfilter.stats_reset
		...

5.5. `secfilter.add_dst`

Insert values into destination blacklist. These values will be checked with the function secf_check_dst to verify if the destination number can be called.

Parameters:

number (number to add to the destination blacklist)

Example 1.20. secfilter.add_dst usage

		...
		kamcmd secfilter.add_dst 555123123
		...

5.6. `secfilter.add_bl`

Insert values into blacklist.

Parameters:

type (must be: ua, country, domain, user or ip)
value (value to add to the blacklist)

Example 1.21. secfilter.add_bl usage

		...
		kamcmd secfilter.add_bl ua friendly-scanner
		kamcmd secfilter.add_bl user sipvicious
		...

5.7. `secfilter.add_wl`

Insert values into whitelist.

Parameters:

type (must be: ua, country, domain, user or ip)
value (value to add to the whitelist)

Example 1.22. secfilter.add_wl usage

		...
		kamcmd secfilter.add_wl country es
		kamcmd secfilter.add_wl user trusted_user
		...

6. Installation

6.1. Database setup

Before running Kamailio with the secfilter module, it is necessary to setup the database table where the module will read the blacklist data from. In order to do that, if the table was not created by the installation script or you choose to install everything by yourself you can use the secfilter-create.sql SQL script in the database directories in the kamailio/scripts folder as a template. Database and table name can be set with module parameters so they can be changed, but the name of the columns must match the ones in the SQL script. You can also find the complete database documentation on the project webpage, https://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.

Example 1.23. Example database content - secfilter table

		...
		+----+-----------+-----------+------------------+
		| id | action    | type      | data             |
		+----+-----------+-----------+------------------+
		|  1 | 0         | 2         | 1.1.1.1          |
		|  2 | 0         | 0         | friendly-scanner |
		|  3 | 0         | 0         | pplsip           |
		|  4 | 0         | 0         | sipcli           |
		|  5 | 0         | 4         | sipvicious       |
		|  6 | 0         | 1         | ps               |
		|  7 | 0         | 3         | 5.56.57.58       |
		|  8 | 1         | 0         | asterisk pbx     |
		|  9 | 1         | 2         | sip.mydomain.com |
		| 10 | 2         | 0         | 555123123        |
		| 11 | 2         | 0         | 555998776        |
		+----+-----------+-----------+------------------+
		...

Action values are:

0 (blacklist)
1 (whitelist)
2 (destination)

Type values are:

0 (user-agent)
1 (country)
2 (domain)
3 (IP address)
4 (user)

7. Some examples

7.1. Print data

Example 1.24. kamcmd secfilter.print ua

		...
User-agent
==========
[+] Blacklisted
    -----------
    0001 -> friendly-scanner
    0002 -> pplsip
    0003 -> sipcli
    0004 -> sundayddr
    0005 -> iWar
    0006 -> sipsak
    0007 -> VaxSIPUserAgent
    0008 -> SimpleSIP
    0009 -> SIP Call
    0010 -> Ozeki
    0011 -> VoIPSec
    0012 -> SIPScan
    0013 -> Conaito
    0014 -> UsaAirport
    0015 -> PortSIP VoIP SDK
    0016 -> zxcvfdf11
    0017 -> fdgddfg546df4g8d5f

[+] Whitelisted
    -----------
    0001 -> my custom ua
		...

7.2. Statistics

Example 1.25. kamcmd secfilter.stats

		...
Blocked messages (blacklist)
============================
[+] By user-agent    : 1256
[+] By country       : 45
[+] By from domain   : 0
[+] By to domain     : 0
[+] By contact domain: 1
[+] By IP address    : 2552
[+] By from name     : 0
[+] By to name       : 0
[+] By contact name  : 0
[+] By from user     : 316
[+] By to user       : 134
[+] By contact user  : 0

Allowed messages (whitelist)
============================
[+] By user-agent    : 0
[+] By country       : 478
[+] By from domain   : 0
[+] By to domain     : 0
[+] By contact domain: 0
[+] By IP address    : 0
[+] By from name     : 0
[+] By to name       : 0
[+] By contact name  : 0
[+] By from user     : 0
[+] By to user       : 0
[+] By contact user  : 0

Other blocked messages
======================
[+] Destinations   : 0
[+] SQL injection  : 213
		...

Secfilter Module

Jose Luis Verdeguer

Chapter 1. Admin Guide

1. Overview

2. Dependencies

2.1. Kamailio Modules

2.2. External Libraries or Applications

3. Parameters

3.1. db_url (string)

3.2. table_name (string)

3.3. action_col (string)

3.4. type_col (string)

3.5. data_col (string)

3.6. dst_exact_match (integer)

4. Functions

4.1. secf_check_ip ()

4.2. secf_check_ua ()

4.3. secf_check_country (string)

4.4. secf_check_from_hdr ()

4.5. secf_check_to_hdr ()

4.6. secf_check_contact_hdr ()

4.7. secf_check_dst (string)

4.8. secf_check_sqli_hdr (string)

4.9. secf_check_sqli_all ()

5. RPC commands

5.1. secfilter.reload

5.2. secfilter.print

5.3. secfilter.stats

5.4. secfilter.stats_reset

5.5. secfilter.add_dst

5.6. secfilter.add_bl

5.7. secfilter.add_wl

6. Installation

6.1. Database setup

7. Some examples

7.1. Print data

7.2. Statistics

3.1. `db_url` (string)

3.2. `table_name` (string)

3.3. `action_col` (string)

3.4. `type_col` (string)

3.5. `data_col` (string)

3.6. `dst_exact_match` (integer)

4.1. `secf_check_ip ()`

4.2. `secf_check_ua ()`

4.3. `secf_check_country (string)`

4.4. `secf_check_from_hdr ()`

4.5. `secf_check_to_hdr ()`

4.6. `secf_check_contact_hdr ()`

4.7. `secf_check_dst (string)`

4.8. `secf_check_sqli_hdr (string)`

4.9. `secf_check_sqli_all ()`

5.1. `secfilter.reload`

5.2. `secfilter.print`

5.3. `secfilter.stats`

5.4. `secfilter.stats_reset`

5.5. `secfilter.add_dst`

5.6. `secfilter.add_bl`

5.7. `secfilter.add_wl`