was born for protecting SSH servers from the today's widespread brute force attacks, and evolved to an extensible log supervisor for blocking attacks to applications in real-time.
can monitor a number of log sources proactively, or receive log messages in its standard input. By means of a parser, it decides whether an entry is normal activity or attack; in the latter case, it remarks the attacker's address. When determines that an attacker committed enough danger to the system to discern an abuse it blocks the attacker's address with the firewall. The attacker becomes offender, and is released after an adequate period of time.
supports the following firewalls:
Some terms in this manual have a special meaning in the context. refers to them consistently throughout documentation, source code, and log messages. See http://www.sshguard.net/docs/terminology/ to get acquainted with them.
can interface with the following blocking systems to block attackers:
Depending on the way chosen for giving logs to sshguard, and depending on the chosen blocking system, some setup may be needed. Instructions are documented at http://www.sshguard.net/docs/setup/
does not make use of any configuration file. Instead, a combination of optional arguments can be passed to its process on the command line, for modifying its default behaviour:
When is signalled with SIGTSTP, it suspends activity. When is signalled with SIGCONT, it resumes monitoring. During suspension, log entries are discarded without being analyzed.
When senses the SSHGUARD_DEBUG environment variable, it enables debugging mode: logging is directed to standard error instead of syslog, and includes comprehensive details of the activity and parsing process. Debugging mode can help investigating attack signatures: once enabled, a log message can be directly pasted into the tool from the console, and the behavior is immediately and minutely shown beneath.
Whitelist addresses are controlled through the -w command-line option. This option can add explicit addresses, host names and address blocks:
-w 192.168.1.10or in multiple occurrences:
-w 192.168.1.10 -w 2001:0db8:85a3:0000:0000:8a2e:0370:7334
-w friendhost.enterprise.comor in multiple occurrences:
-w friendhost.enterprise.com -w friend2.enterprise.comAll IPv4 and IPv6 addresses that the host resolves to are whitelisted. Hosts are resolved to addresses once, when sshguard starts up.
-w 2002:836b:4179::836b:0000/126or in multiple occurrences:
-w 192.168.0.0/24 -w 18.104.22.168/26
can take whitelists from files when the -w option argument begins with a `.' (dot) or `/' (slash).
This is a sample whitelist file (say /etc/friends):
# comment line (a '#' as very first character) # a single IPv4 and IPv6 address 22.214.171.124 2001:0db8:85a3:08d3:1319:8a2e:0370:7344 # address blocks in CIDR notation 127.0.0.0/8 10.11.128.0/17 192.168.0.0/24 2002:836b:4179::836b:0000/126 # hostnames rome-fw.enterprise.com hosts.friends.com
And this is how is told to make a whitelist up from the /etc/friends file:
sshguard -w /etc/friends
The -w option can be used only once for files. For addresses, host names and address blocks it can be used with any multiplicity, even with mixes of them.
Log validation is only needed when is fed log messages from syslog or from syslog-ng. When a process logs directly to a raw file and sshguard is configured for polling logs directly from it, you only need to adjust the log file permissions so that only root can write on it.
For enabling log validation on a given service the -f option is used as follows:
-f 100:/var/run/sshd.pidwhich associates the given pidfile to the ssh service (code 100). A list of well-known service codes is available at http://www.sshguard.net/docs/reference/service-codes/
The -f option can be used multiple times for associating different services with their pidfile:
sshguard -f 100:/var/run/sshd.pid -f 123:/var/run/mydaemon.pid
Services that are not configured for log validation follow a default-allow policy (all of their log messages are accepted by default).
PIDs are checked with the following policy:
Low I/O load is committed to the operating system because of an internal caching mechanism. Changes in the pidfile value are handled transparently.
To counteract these cases, by default behaves with touchiness Besides observing abuses from the log activity, it also monitors the overall behavior of attackers. The decision on when and how to block is thus made respective to the entire history of the offender as well. For example, if address A attacks repeatedly and the base blocking time is 420 seconds, A will be blocked for 420 seconds (7 mins) at the first abuse, 2*420 (14 mins) the second, 2*2*420 (28 mins) the third ... and 2^(n-1)*420 the n-th time.
Touchiness has two major benefits: to legitimate users, it grants forgiving blockings on failed logins; to real attackers, it effectively renders large scale attacks infeasible, because the time to perform one explodes with the number of attempts.
Touchiness can be augmented with blacklisting (-b). With this option, after a certain total danger committed, the address is added to a list of offenders to be blocked permanently. The list is intended to be loaded at each startup, and maintained/extended with new entries during operation. inserts a new address after it exceeded a threshold of danger committed over recorded history. This threshold is configurable within the -b option argument. Blacklisted addresses are never scheduled for releasing.
The -b command line option enables blacklisting and requires the filename to use for permanent storage of the blacklist. Optionally, a custom blacklist threshold can be prefixed to this path, separated by ':'. For example,
-b 50:/var/db/sshguard/blacklist.dbrequires to blacklist addresses after having committed attacks for danger 50 (default per-attack danger is 10), and store the blacklist in file /var/db/sshguard/blacklist.db. Although the blacklist file is not meant to be in human-readable format, the strings(1) command can be used to peek in it for listing the blacklisted addresses.
Extending attack signatures needs some expertise with context-free parsers; users are welcome to submit samples of the desired log messages to http://www.sshguard.net/support/attacks/submit/
website at: http://www.sshguard.net/