Address 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.

Address whitelisting is only supported by sshguard branch 1.x. As of now, whitelisting is restricted to IPv4 addresses.

Whitelisting addresses

These are some examples for whitelisting plain (IPv4) addresses:

    # specify one address straight:
    -w 192.168.1.10
    # specify several addresses:
    -w 192.168.1.10 -w 192.168.1.23 -w 12.13.14.15

Whitelisting host names

These are some examples for whitelisting hostnames:

    # specify one host name straight:
    -w friendhost.enterprise.com
    # specify several different host names:
    -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.

Whitelisting address blocks

Sets of IP addresses can be given in CIDR notation: network-address/mask. These are some examples for whitelisting in this form:

    # whitelist addresses from 192.168.0.1 to 192.168.0.255
    -w 192.168.0.0/24
    # whitelist addresses 192.168.0.1-255 PLUS 1.2.3.128 to 1.2.3.191
    -w 192.168.0.0/24 -w 1.2.3.128/26

Whitelisting from files

In this form, the source of addresses information is not the command line options but a text file. This is useful when longer or more complex sets of addresses need to be whitelisted.

This is how such file appears:

    # 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

Summing up, the format is the following:

line-based, one address set per line
lines beginning with '#' (sharp) are ignored
each address set can be expressed with the same format used for the command line argument: single address, host name or CIDR

Sshguard is told to whitelist address sets in file X with the following command line argument:

    -w /full/path/to/X

It is distinguished from address, CIDRs and hostnames because the argument starts with a '/' (slash). Relative paths beginning with '.' (dot) are also supported.

Structured whitelisting

Finally, whitelisting can be composed by many of the proposed forms mixed together. This is an example:

    # whitelist addresses in file /etc/friends + LAN + host mktn.enterprise.com
    sshguard -w /etc/friends -w 192.168.1.0/24 -w mktn.enterprise.com