---

Manual Reference Pages  - SSHGUARD (8)

---

sshguard - monitors daemon activity

CONTENTS

Synopsis
Description
Usage
Whitelisting
Extensions
See Also

sshguard [-a abuse_tresh] [-p pardon_min_interval] [-s stale_tresh] [-w addr/host/block/file]

sshguard monitors logging activity and reacts to attacks by blocking their source addresses.

sshguard has 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.

sshguard is given log messages in its standard input. By mean of a parser, it decides whether an entry is normal activity or attack; in the latter case, it remarks the author’s address. When the number of attacks from one address exceeds a threshold, the address is blocked with the firewall.

sshguard supports the following firewalls:

netfilter/iptables
	for Linux-based operating systems
Packet Filter (PF)
	for BSD operating systems (Open, Free, Net, DragonFly -BSD)
IPFirewall (IPFW)
	for FreeBSD and Mac OS X
tcpd’s hosts_access (/etc/hosts.allow)
	portable across UNIX

sshguard is typically given log entries by syslog (or syslog-ng), or by tail.

For interfacing sshguard with syslog, a line like this must be included in syslog.conf:

# copy to sshguard entries with auth and authpriv fac., lev. >= info
auth.info;authpriv.info     |/usr/local/sbin/sshguard

For interfacing sshguard with syslog-ng, configurations like the following are needed:

# sshguard is a log destination
destination sshguardproc {
    program("/usr/local/sbin/sshguard"
        template("$DATE $FULLHOST $MESSAGE\n"));
};
# filter LOG_AUTH messages which also contain "ssh"
filter authssh { facility(auth, authpriv) and match("sshd"); };
# copy filtered logs into the sshguard process
log { source(src); filter(authssh); destination(sshguardproc); };

For making sshguard get entries directly from a log file, run this command (iff -F is not available for you, use -f that doesn’t handle file rotation):

tail -n0 -F /var/log/auth.log | /usr/local/sbin/sshguard

sshguard 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:

-a num	block an address after num attack attempts have been detected. (Default: 4)
-p secs	release a blocked address not sooner than secs seconds after being blocked. sshguard will release the address between X and 3/2 * X seconds. (Default: 7*60)
-s secs	forget about an address after secs seconds. If host A issues one attack every this many seconds, it will never be blocked. (Default: 20*60)
-w addr/host/block/file
	see the WHITELISTING section

sshguard supports address whitelisting. Whitelisted addresses are not blocked even if they appear to generate attacks. This is useful for protecting lame LAN users (or external friendly users) from being incidentally blocked.

Whitelist addresses are controlled through the -w command-line option. This option can add explicit addresses, host names and address blocks:

addresses
	specify the address directly, like:     -w 192.168.1.10 or in multiple occurrences:     -w 192.168.1.10 -w 192.168.1.11 -w 192.168.1.12
host names
	specify the host name directly, like:     -w friendhost.enterprise.com or in multiple occurrences:     -w friendhost.enterprise.com -w friend2.enterprise.com When hosts resolve to multiple addresses, all of them are whitelisted. Hosts are resolved to addresses once, when sshguard starts up.
address blocks
	specify the address block in the usual CIDR notation:     -w 192.168.0.0/24 or in multiple occurrences:     -w 192.168.0.0/24 -w 1.2.3.128/26
file	When longer lists are needed for whitelisting, they can be wrapped into a plain text file, one address/hostname/block per line, with the same syntax given above. sshguard 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 ip address 1.2.3.4 # address blocks in CIDR notation 127.0.0.0/8 10.11.128.0/17 192.168.0.0/24 # hostnames rome-fw.enterprise.com hosts.friends.com And this is how sshguard 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.

sshguard can be easily extended to support both more backends (systems blocking addresses, like firewalls) and to recognize more attack patterns.

Adding backends is extremely easy when the blocking and releasing operations can be controlled with system commands. sshguard provides a shell script for generating such extensions in few steps: sshguard_backendgen.sh.

Adding more attack patterns needs some expertise with bison, as sshguard uses a grammar-based context-free parser for powerfulness. Thus, there is one tracker for user-proposed patterns at http://sshguard.sourceforge.net/newattackpatt.php.

syslog(1), syslog.conf(5)

sshguard website at: http://sshguard.sourceforge.net/