NAME
sshguard - monitors daemon activity
SYNOPSIS
sshguard [-b thr:filename] [-a abuse_tresh] [-p pardon_min_interval]
[-s stale_tresh] [-w addr/host/block/file] [-f srv:pidfile]
DESCRIPTION
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 means of a
parser, it decides whether an entry is normal activity or attack; in the
latter case, it remarks the author’s address. After a number of attacks,
the address is distinguished as an abuser, and blocked with the firewall.
sshguard supports the following firewalls:
AIX native firewall
for IBM AIX operating systems
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
IP Filter (IPFILTER)
for FreeBSD, NetBSD and Solaris
tcpd’s hosts_access (/etc/hosts.allow)
portable across UNIX
null
portable do-nothing backend for applying detection but not prevention
USAGE
sshguard is given log entries to scan in its standard input. It can
interpret logs with the following formats:
· syslog
· syslog-ng
· metalog
· multilog
· raw messages
sshguard can interface with the following blocking systems to block
attackers:
· IBM AIX firewall
· PF
· netfilter/iptables
· IPFW
· IP Filter
· /etc/hosts.allow
· null firewall
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/doc/setup/setup.html .
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:
-b [num:]filename
enable blacklisting: blacklist after num (or 3) blocked abuses,
and hold the permanent blacklist in filename. See TOUCHINESS &
BLACKLISTING below.
-v print summary information on sshguard and exit.
-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.
-f servicecode:pidfile
see the LOG MESSAGE AUTHENTICATION section.
When sshguard is signalled with SIGTSTP, it suspends activity. When
sshguard is signalled with SIGCONT, it resumes monitoring. During
suspension, log entries are discarded without being analyzed.
When sshguard 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 patterns: once enabled, a pattern
can be directly pasted into the tool from the console, and the behavior
is immediately and minutely shown beneath.
WHITELISTING
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 numeric IPv4 or IPv6 address directly, like:
-w 192.168.1.10
or in multiple occurrences:
-w 192.168.1.10 -w 2001:0db8:85a3:0000:0000:8a2e:0370:7334
host names
specify the host name directly, like:
-w friendhost.enterprise.com
or in multiple occurrences:
-w friendhost.enterprise.com -w friend2.enterprise.com
All IPv4 addresses that the host resolves to 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 IPv4 and IPv6 address
1.2.3.4
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
# 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.
LOG MESSAGE AUTHENTICATION
Syslog and syslog-ng typically insert a PID of the generating process in
every log line. This can be checked for authenticating the source of the
message and avoid false attacks to be detected because malicious local
users inject crafted log lines. This way sshguard can be safely used even
on hosts where this assumption does not hold.
Log message authentication is only needed when sshguard 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 message authentication on a given service the -f option
is used as follows:
-f 100:/var/run/sshd.pid
which associates the given pidfile to the ssh service (code 100). A list
of well-known service codes is available at
http://www.sshguard.net/doc/servicecodes.html.
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 message authentication follow a
default-allow policy (all of their log messages are accepted by default).
PIDs are checked with the following policy:
1. the logging service is searched in the list of services configured
for authentication. If not found, the entry is accepted.
2. the logged PID is compared with the pidfile. If it matches, the entry
is accepted
3. the PID is checked for being a direct child of the authoritative
process. If it is, the entry is accepted.
4. the entry is ignored.
Low I/O load is committed to the operating system because of an internal
caching mechanism. Changes in the pidfile value are handled
transparently.
TOUCHINESS & BLACKLISTING
In many cases, attacks against services are performed in bulk in an
automated form. For example, the attacker goes trough a dictionary of 150
username/password pairs and sequentially tries to violate the SSH service
with any of them, continuing blindly while blocked, and re-appearing once
the block expires.
To counteract these cases, sshguard by default behaves with touchiness.
Besides observing abuses from the log activity, it monitors also the
overall behavior of attackers. The decision on when and how to block is
thus made respective to the entire history of the attacker 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 it
explodes with the number of attempts.
Touchiness can be augmented with blacklisting (-b). With this option,
after a number of abuses, the address is added to a list of attackers to
be blocked permanently. The list is intended to be loaded at each
startup, and maintained/extended with new entries during operation.
sshguard inserts a new address after it exceeded a threshold of abuses.
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 5:/var/db/sshguard/blacklist.db
requires to blacklist addresses after the 5th abuse, 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.
EXTENSIONS
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://www.sshguard.net/newattackpatt.php.
SEE ALSO
syslog(1), syslog.conf(5)
sshguard website at: http://www.sshguard.net/