IP Blacklist

Contents

IP Blacklist

Synopsis

This feature provides the functionality of dynamic IP blacklist. This feature can be used with other security modules to block an IP address for a while if the IP address performs specified-times attacks.
This feature is availiable since version 1.5.5.
Until version 1.8.1 IP blacklist supports blocking IP addresses on the base of illegal activity in 1 second time frame. Version 1.8.2 introduces new directive ip_blacklist_ttl for flexible blocking policy.

Directives

ip_blacklist

Syntax ip_blacklist on | off;
Default off
Context http

Enable or disable IP blacklist.

Example: 

ip_blacklist on;


ip_blacklist_size

Syntax ip_blacklist_size size;
Default 1024
Context http

Specify IP blacklist size, size is how many IP addresses could be stored in the blacklist.

Example: 

ip_blacklist_size 10240;


ip_blacklist_timeout

Syntax ip_blacklist_timeout timeout;
Default 60
Context http

Specify IP blacklist entries timeout (ban time) in seconds.

Example: 

ip_blacklist_timeout 120;


ip_blacklist_log

Syntax ip_blacklist_log on | off;
Default off
Context http/server/location

Enable error log or not.

Example: 

ip_blacklist_log on;


ip_blacklist_show

Syntax ip_blacklist_show;
Default
Context location

Show IP blacklist items.
Since version 1.8.3 the parameter "debug" is supported.
Example: 

location /show_blacklist {
       ip_blacklist_show;
}

Use a browser or http client, such as wget, curl, etc., open /show_blacklist to view the blacklist.

curl http://1.1.1.1/show_blacklist
curl http://1.1.1.1/show_blacklist?debug=1


ip_blacklist_flush

Syntax ip_blacklist_flush;
Default
Context location

Flush all IP blacklist items.
Since version 1.8.3 the parameter "ip" is used to remove only one IP address from the blacklist.
Example: 

location /flush_blacklist {
    ip_blacklist_flush;
}


Use a browser or http client, such as wget, curl, etc., open /flush_blacklist to clear the blacklist or remove one IP address from the blacklist.

curl http://1.1.1.1/flush_blacklist
curl http://1.1.1.1/flush_blacklist?ip=8.8.8.8


ip_blacklist_mode

Syntax ip_blacklist_mode sys | local;
Default local
Context http

Specify blacklist's mode, which can be two types:

  • System command mode (sys): The IP addresses are added kept outside of SEnginx, for example, if you use iptables, the requests will be blocked at the kernel level.
  • Local mode (local): The IP addresses which are blacklisted are kept in SEnginx, subsequent requests will be blocked at the SEnginx.

Example:

System command mode (sys):
ip_blacklist_mode sys;
Local mode (local):
ip_blacklist_mode local;


ip_blacklist_syscmd

Syntax ip_blacklist_syscmd [system command];
Default
Context http

Specify what external system command will be called when SEnginx wants to blacklist an IP address. IP address in the command is given by %V.

Example: 

Specify a script to handle the IP addresses which is added to the blacklist:
ip_blacklist_syscmd "sudo /path/to/a/scritp %V";

Use iptables to add an IP address and block:
ip_blacklist_syscmd "sudo /sbin/iptables -A INPUT -s %V -j DROP";



ip_blacklist_ttl

Syntax ip_blacklist_ttl ttl;
Default 1
Context http
Version Since 1.8.2

IP blacklist consists of the nodes. Each blacklist node contains an IP address and counter (actually node has a different counter per each module calling blacklist module). The IP address is blocked when the counter over maximum value defined at the calling module. If the counter does not over maximum value the blacklist node is deleted in TTL seconds after last calling blacklist module for that IP.
This directive appeared in SEnginx 1.8.2.

For example, if maximum counter value is 3, the IP address should be blocked on 4 call of the blacklist module.
If TTL is 5 seconds, the IP will be blocked at 10:56:08 on 4 call of the blacklist module:
10:56:01
10:56:02
10:56:04
10:56:08
If TTL is 3 seconds, the IP will not be blocked because the node is deleted at 10:56:07 (3 secods after 10:56:04) and created anew at 10:56:08.

Prior to version 1.8.2, the unblocked ip blacklist nodes are deleted after 1 second since first calling blacklist module for that IP.



ip_blacklist_use_remote_addr (Pro)

Syntax ip_blacklist_use_remote_addr on | off;
Default off
Context http
Version Since SEnginx Pro 1.10.0

Setting "on" force ip_blacklist to ignore IP-address received from the calling module (such as Robot Mitigation or Naxsi) and always use only client IP address (remote_addr). This option also prevents using address from the "x-forwarder-for" header which may be faked by atackers.
Note: load balancers and legal proxies set "x-forwarder-for" header with client real IP-address. Use nginx module ngx_http_realip_module to write real client address to the remote_addr variable.
This directive appeared in SEnginx Pro 1.10.0.

Example: 

ip_blacklist_use_remote_addr on;


ip_blacklist_timeout (Pro)

Syntax ip_blacklist_timeout timeout;
Default 60
Context http, server, location
Version Since SEnginx Pro 1.10.0

The same as ip_blacklist_timeout but could be set also at server and location config.

Example: 

location = /a {
        robot_mitigation on;
        ip_blacklist_timeout 60;
}


ip_blacklist_ttl (Pro)

Syntax ip_blacklist_ttl ttl;
Default 1
Context http, server, location
Version Since SEnginx Pro 1.10.0

The same as ip_blacklist_ttl but could be set also at server and location config.

Example: 

location = /a {
        robot_mitigation on;
        ip_blacklist_ttl 60;
}


ip_blacklist_syscmd (Pro)

Syntax ip_blacklist_syscmd [system command];
Default
Context http
Version Since SEnginx Pro 1.10.0

The same as ip_blacklist_syscmd but also supports timeout parameter as second argument. Timeout in the command is given by %d

Example:

Examples used with robot mitigation module


http {
    ... ...
    ip_blacklist on;
    ip_blacklist_size 10240;
    ip_blacklist_timeout 60;
    ip_blacklist_log on;
    server {
        listen       80;
        server_name  localhost;       
        location /blacklist_flush {
            ip_blacklist_flush;
        }
        location /blacklist_show {
            ip_blacklist_show;
        }       
        location / {
            ... ...
            robot_mitigation on;
            robot_mitigation_mode js;
            robot_mitigation_blacklist 10;
            ... ...
        }
　　}
}