Extending blocking backends

Sshguard uses blocking backends for blocking addresses recognized as attackers.

They are called backends because they are decoupled by the sshguard application through an API. Sshguard cares about detecting attackers, deciding whether and when to block them, defining what services they have violated, and finally if and when to release them. Blocking backends are then inquired for actually blocking and releasing those addresses.

Blocking backends are defined in the src/fwalls directory of the sshguard package.

Every blocking backend must provide these services:

block an address
release an address
release all blocked addresses (flush)

It is often the case that a blocking backend can provide all of its services through system commands. The implementation of this kind of backends can be generated automatically by the sshguard_backendgen.sh script, which is provided in the sshguard source package. The script is self-documented: run and read.

In the rest of the cases, the backend needs to be coded with respect to the sshguard blocking backend API.

Blocking backend API

The services of blocking backends are presented to the main application with the following functions (respectively), prototyped in sshguard_fw.h:

int fw_block(char *addr, int addrkind, int service)
int fw_release(char *addr, int addrkind, int service)
int fw_flush(void)

In these functions, this is the meaning of parameters:

parameter	format	meaning
addr	string, in address presentation format (e.g. "192.168.1.230")	the address to operate. This reference cannot be written to and cannot be stored for future use.
addrkind	integer, internal code (see `sshguard_addresskind.h`)	kind of address passed, like IPv4 or IPv6
service	integer, internal code (see `sshguard_services.h`)	kind of service being violated, like SSH, SMTP etc

Furthermore, two more functions are provided for backends that need stuff to be done before working and undone before exiting; they are called by the main application when starting up and when shutting down, indeed. These are prototyped like this:

int fw_init()
int fw_fin()

All these functions return an integer code determining their operating status. The possible codes are listed in sshguard_fw.h and they are:

symbol	meaning
FWALL_OK	operation correctly accomplished
FWALL_ERR	error during operation. Operation not accomplished.
FWALL_UNSUPP	operation not supported. Operation not accomplished.

The backend can provide more information about errors or its working status by means of the sshguard_log() function, that is provided in sshguard_log.h. This function's interface is analogous to the syslog() function (see syslog(3)). Sshguard cares where and how to dispatch these messages. This is a sample snippet for using this logging interface:

    ...
    #include "../sshguard_log.h"
    ...
    sshguard_log(LOG_INFO, "backend_name: could not open file %s: %s", filename, error);
    ...