[Users] NEW FEATURE: IP blacklists - sr-users

30 Jan 2007

Hi everybody,

OpenSER 1.2.0 has new feature - IP Blacklist support. This is a low 
level filtering engine for the outgoing requests; low level, because the 
filtering is done based on IP, protocol, port, etc.
Its primary purposes will be to prevent sending requests to critical IPs 
(like GWs) due DNS or to avoid sending to destinations that are known to 
be unavailable (temporary or permanent).

Because of flexibility concerns, the filtering rules can be groups 
inside multiple lists.

A rule:
  - matches based on IP/mask, proto, port and text pattern criteria
  - can be reversed applied

A list:
  - can be read-only - it does not change during execution
  - have timeout per elements - elements expires after a configured timeout.

How to use:
===========

currently there are 2 ways of using the blacklists:

1) statically defining list in the configuration file and selecting 
which ones should be used for each request.

You can define blacklists as follow:
    # filter out requests going to ips of my gws
    dst_blacklist = gw:{( tcp , 192.168.2.100 , 5060 , "" ),( any , 
192.168.2.101 , 0 , "" )}
    # block requests going to "evil" networks
    dst_blacklist = net_filter:{ ( any , 192.168.1.100/255.255.255.0 , 0 
, "" )}
    # block message requests with nasty words
    dst_blacklist = msg_filter:{ ( any , 192.168.20.0/255.255.255.0 , 0 
, "MESSAGE*ugly_word" )}  
    # block requests not going to a specific subnet
    dst_blacklist = net_filter2:{ !( any , 192.168.30.0/255.255.255.0 , 
0 , "" )}  

a rule is defined by:
    protocol : TCP, UDP, TLS or "any" for anything
    port : number or 0 for any
    ip/mask
    test patter - is a filename like matching (see  "man 3 fnmatch") 
applied on the outgoing request buffer (first_line+hdrs+body)

 From routing script, you can use the use_blacklist("name") function to 
select what blacklist to be applied for the current request. More than 
one list can be selected.

If the destination address matches on of the selected rules, the send 
will fail.

2) via DNS

The DNS resolver, when configured with failover, can automatically store 
in a temporary blacklist the failed destinations. This will prevent (for 
a limited period of time) openser to send requests to destination known 
as failed.
So, the blacklist can be used as a memory for the DNS resolver.

To use it, you have to enabled it - the rest is done automatically.
    disable_dns_blacklist = no

By default is enabled. The temporary blacklist created by DNS resolver 
is named "dns" and it is by default selected for usage (no need use the 
use_blacklist() function. The rules from this list have a life time of 4 
minutes - you can change it at compile time, from blacklists.h .

To give you an internal snapshot, a new MI function - "list_blacklists" 
- was added to print all existent blacklists and their rules.

Any suggestions/reports are welcome!

regards,
bogdan