pyruse/doc/logandban.md

9.2 KiB

Log entries creation, and ban of IP addresses

Log entries

The main purpose of creating new log entries, is to detect recidives in bad behaviour: after an IP address misbehaves, it gets banned, and we generate a log line for that; such log lines get counted, and eventually trigger a harsher, recidive, ban of the same IP address. Several levels of bans can thus be stacked, up to an unlimited ban, if such is wanted.

Action action_log takes a mandatory message argument, which is a template for the message to be sent. Optionally, the log level can be changed from the default (which is “INFO”) by setting the level parameter; valid values are “EMERG”, “ALERT”, “CRIT”, “ERR”, “WARNING”, “NOTICE”, “INFO”, and “DEBUG” (see Syslog severity levels for the definitions).

The message parameter is a Python string format. This means that any key in the current entry may be referrenced by its name between curly braces. This also means that literal curly braces must be doubled, lest they are read as the start of a template placeholder.

Here are some examples:

{
  "action": "action_log", "args": { "message": "Ban from SSH for {thatIP}." }
}

{
  "action": "action_log",
  "args": {
    "level": "NOTICE",
    "message": "Recidive ban from SSH for {thatIP}."
  }
}

Ban IP addresses after they misbehaved

Linux provides a number of firewall solutions: iptables, its successor nftables, and many iptables frontends like Shorewall or RedHat’s firewalld.

For Pyruse, nftables was initially chosen, because it is modern and light-weight, and provides interesting features. Besides, only nftables is actually tested in real use.
Now, an ipset-based alternative is also available.

nftables

Action action_nftBan requires that nftables is installed. In addition, the binary to run (and parameters if needed) should be set in the configuration file; here is the default value:

"nftBan": {
  "nft": [ "/usr/bin/nft" ]
}

This action takes three mandatory arguments:

  • nftSetIPv4 and nftSetIPv6 are the nftables sets where IP addresses will be added. The IP address is considered to be IPv6 if it contains at least one colon (:) character, else it is supposed to be IPv4.
  • IP gives the name of the entry field to read, in order to get the IP address.

Note that nftables sets are kind-of paths. For example, if your nftables ruleset is such:

table ip Inet4 {
  set mail_ban {
    type ipv4_addr
    flags timeout
  }

  chain FilterIn {
    type filter hook input priority 0
    policy drop
    ip saddr @mail_ban drop
    …
  }
}
table ip6 Inet6 {
  set mail_ban {
    type ipv6_addr
    flags timeout
  }

  chain FilterIn {
    type filter hook input priority 0
    policy drop
    ip6 saddr @mail_ban drop
    …
  }
}

Then the values for nftSetIPv4 and nftSetIPv6 will be respectively “ip Inet4 mail_ban” and “ip6 Inet6 mail_ban”.

Optionally, a number may be specified with banSeconds to limit the time this ban will last. The nice thing with nftables, is that it handles the timeouts itself: no need to keep track of the active bans and remove them using a Python program; the only reason why bans are recorded in a file, is to be able to restore them on reboot.

Here are examples:

{
  "action": "action_nftBan",
  "args": { "IP": "thatIP", "banSeconds": 86400, "nftSetIPv4": "ip Inet4 mail_ban", "nftSetIPv6": "ip6 Inet6 mail_ban" }
}

{
  "action": "action_nftBan",
  "args": { "IP": "thatIP", "nftSetIPv4": "ip Inet4 sshd_ban", "nftSetIPv6": "ip6 Inet6 sshd_ban" }
}

List the currently banned addresses

To see what IP addresses are currently banned, here is the nft command:

$ sudo nft 'list set ip Inet4 mail_ban'
table ip Inet4 {
        set mail_ban {
                type ipv4_addr
                flags timeout
                elements = { 37.49.226.159 timeout 5d expires 3d11h11m58s,
                             71.6.167.142 timeout 2d20h23m57s expires 6h12m49s,
                             91.200.12.96 timeout 4d18h22m29s expires 2d4h11m24s,
                             91.200.12.156 timeout 4d22h59m19s expires 2d8h48m15s,
                             91.200.12.203 timeout 4d22h53m38s expires 2d8h42m33s,
                             91.200.12.213 timeout 4d22h54m25s expires 2d8h43m21s,
                             91.200.12.217 timeout 4d18h1m14s expires 2d3h50m9s,
                             91.200.12.230 timeout 4d22h54m27s expires 2d8h43m23s,
                             139.201.42.59 timeout 5d expires 3d17h29m51s,
                             183.129.89.243 timeout 5d expires 4d9h4m37s }
        }
}

Note: The un-rounded timeouts are post-reboot restored bans.

Un-ban an IP address

It is bound to happen some day: you will want to un-ban a banned IP address.

Since action_nftBan does not keep the current bans in memory, it is enough to remove the ban using the nft command:

$ sudo nft 'delete element ip Inet4 mail_ban {10.0.0.10}'

However, the ban may be restored when restarting Pyruse. To avoid that, also delete the corresponding record from the action_nftBan.py.json file in Pyruse’s storage directory.

To go further, you could tweak your configuration, so that your trusted IP addresses never reach action_nftBan.

Manual ban of an IP address

To add a ban yourself, run a command like this:

$ sudo nft 'add element ip Inet4 ssh_ban {192.168.1.1 timeout 5d}

The timeout … part can be omitted to add a permanent ban. The timeout can be any combination of days (d), hours (h), minutes (m), and seconds (s), eg. “3d31m16s”.

In order to make the ban persistent across reboots, a corresponding record should also be appended to the action_nftBan.py.json file in Pyruse’s storage directory (the IP address, Nftables Set, days, hours, minutes, seconds, and actual path to the file should be adapted to your needs):

  • either a time-limited ban:
$ sudo sed -i "\$s/.\$/$(date +', {"IP": "192.168.1.1", "nfSet": "ip Inet4 ssh_ban", "timestamp": %s.000000}' -d 'now +3day +31minute +16second')]/" /var/lib/pyruse/action_nftBan.py.json
  • or an unlimited ban:
$ sudo sed -i '$s/.$/, {"IP": "192.168.1.1", "nfSet": "ip Inet4 ssh_ban", "timestamp": 0}]/' /var/lib/pyruse/action_nftBan.py.json

iptables with ipset

Action action_ipsetBan requires that ipset and iptables are installed. In addition, the ipset binary to run (and parameters if needed) should be set in the configuration file; here is the default value:

	"ipsetBan": {
		"ipset": [ "/usr/bin/ipset", "-exist", "-quiet" ]
	}

This action works exactly like action_nftBan, except parameters nftSetIPv4 and nftSetIPv6 are named ipSetIPv4 and ipSetIPv6 instead.

The name of the set in the ipSetIPv4 parameter must have been created before running Pyruse, with:

$ sudo ipset create SET_NAME hash:ip family inet hashsize 1024 maxelem 65535

Likewise, the set given by ipSetIPv6 must have been created before running Pyruse, with:

$ sudo ipset create SET_NAME hash:ip family inet6 hashsize 1024 maxelem 65535

Here are examples of usage for this action:

{
  "action": "action_ipsetBan",
  "args": { "IP": "thatIP", "banSeconds": 86400, "ipSetIPv4": "mail_ban4", "ipSetIPv6": "mail_ban6" }
}

{
  "action": "action_ipsetBan",
  "args": { "IP": "thatIP", "ipSetIPv4": "sshd_ban4", "ipSetIPv6": "sshd_ban6" }
}

List the currently banned addresses

To see what IP addresses are currently banned, here is the ipset command:

$ sudo ipset list mail_ban4'

Un-ban an IP address

To remove an IP address from a set, here is the ipset command:

$ sudo ipset del mail_ban4 10.0.0.10'

To make the change persistent across reboots, also delete the corresponding record from the action_ipsetBan.py.json file in Pyruse’s storage directory.

To go further, you could tweak your configuration, so that your trusted IP addresses never reach action_ipsetBan.

Manual ban of an IP address

To add a ban yourself, run a command like this:

$ sudo ipset add ssh_ban4 192.168.1.1 timeout 261076

The timeout … part can be omitted to add a permanent ban; otherwise it is a number of seconds.

In order to make the ban persistent across reboots, a corresponding record should also be appended to the action_ipsetBan.py.json file in Pyruse’s storage directory (the IP address, Nftables Set, days, hours, minutes, seconds, and actual path to the file should be adapted to your needs):

  • either a time-limited ban:
$ sudo sed -i "\$s/.\$/$(date +', {"IP": "192.168.1.1", "nfSet": "ssh_ban4", "timestamp": %s.000000}' -d 'now +3day +31minute +16second')]/" /var/lib/pyruse/action_ipsetBan.py.json
  • or an unlimited ban:
$ sudo sed -i '$s/.$/, {"IP": "192.168.1.1", "nfSet": "ssh_ban4", "timestamp": 0}]/' /var/lib/pyruse/action_ipsetBan.py.json