Ubuntu Manpage: sshguard - block brute-force attacks by aggregating system logs

NAME

       sshguard - block brute-force attacks by aggregating system logs

SYNOPSIS

       sshguard  [-v]  [-a  thresh] [-b thresh:file] [-f service:pidfile] [-i pidfile] [-l source] [-p interval]
       [-s interval] [-w address | file]

DESCRIPTION

       sshguard protects hosts from brute-force attacks against SSH and other  services.  It  aggregates  system
       logs  and  blocks  repeat offenders using one of several firewall backends, including iptables, ipfw, and
       pf.

       sshguard can read log messages from standard input (suitable for piping from syslog) or  monitor  one  or
       more  log  files.  Log  messages are parsed, line-by-line, for recognized patterns. If an attack, such as
       several login failures within a few seconds, is detected, the offending IP  is  blocked.   Offenders  are
       unblocked after a set interval, but can be semi-permanently banned using the blacklist option.

       See http://www.sshguard.net/docs/setup/ for setup instructions.

       Other features, attack signatures, and additional documentation can be found at http://www.sshguard.net/.

OPTIONS

-a thresh (default 30)
Block an attacker when its dangerousness exceeds thresh. Each attack pattern that is matched
contributes a fixed dangerousness of 10.

-b thresh:file
Blacklist an attacker when its dangerousness exceeds thresh. Blacklisted addresses are added to
file so they can be read at the next startup. Blacklisted addresses are never automatically
unblocked, but it is good practice to periodically clean out stale blacklist entries.

-f service:pidfile
Deprecated. See LOG VALIDATION below.

-i pidfile
Write the PID of sshguard to pidfile.

-l source
Monitor source for log messages. By default, sshguard reads log messages from standard input. Give
this option once for every source to monitor instead. sshguard transparently handles log
rotations. When using this option, standard input is ignored, but can be re-added by giving '-l
-'.

-p interval (default 120 secs, or 2 minutes)
Wait at least interval seconds before releasing a blocked address. Repeat attackers are blocked
for 1.5 times longer after each attack. Because sshguard unblocks attackers only at infrequent
intervals, this parameter is inexact (actual blocks will be longer).

-s interval (default 1800 secs, or 30 minutes)
Forget about an attacker interval seconds after its last attempt. Its dangerousness will be reset
to zero.

-w address | file
Whitelist the given address, hostname, or address block. Alternatively, read whitelist entires
from file. This option can be given multiple times. See WHITELISTING below for details.

-v Print version information and exit.

ENVIRONMENT

       SSHGUARD_DEBUG
              Enable additional debugging information.

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  and  IPv6  addresses  that  the host resolves to are whitelisted. Hosts are resolved to
              addresses once, when sshguard starts up.

       address blocks
              specify the IPv4 or IPv6 address block in the usual CIDR notation:

                 -w 2002:836b:4179::836b:0000/126

              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
                 2002:836b:4179::836b:0000/126
                 #   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 VALIDATION

Syslog and syslog-ng typically insert a PID of the generating process in every log message. 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 messages. This way sshguard can be safely used even on hosts
where this assumption does not hold.

Log validation 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 validation 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/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:

1. the logging service is searched in the list of services configured for validation. 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.

AUTHORS

       Michele Mazzucchi <mij@bitchx.it>, Kevin Zheng <kevinz5000@gmail.com>

1.7.1                                           October 11, 2016                                     SSHGUARD(8)