SSHBlack Variable Customization

Several variables are available for tuning the script. Default values are already entered in the script and will run fine for most applications right out of the box. These variables are detailed below.

$DAEMONIZE will allow the script to run in the background (via fork) and will essentially create a daemon out of the script. If this is set to '1' it will place the executing script in the background. If set to '0' it will run from the command prompt and log all output to the terminal (useful for debugging, not much else).

$LOG is the log file to monitor, commonly set to '/var/log/secure' but might be '/var/log/messages' or '/var/log/syslog' and should include a complete path.

$OUTPUTLOG is the log file for output from the sshblack script. It will log everything from STDOUT and STDERR. You can certainly send this to /dev/null if you don't want to see this output. Default is '/var/log/sshblacklisting'.

$CACHE is the file used to store the working database of IP addresses. This includes both addresses that are already blacklisted and those that are "addresses of interest" that have done something suspicious but have not yet crossed the threshold to be blacklisted. The database is composed of one line per address, three comma-separated elements per line. The form is:

   ip_address,epoch_time,attack_count

  IP address is the dotted notation for the "attacking" host. The time is epoch time (seconds since Jan 01, 1970). The attack count is an integer representing of the number of distinct attack patterns seen from the respective host since it was first "observed".

$LOCALNET is a whitelist of hosts and/or networks. This is recorded in REGEX notation and can include any hosts and networks that should NOT be blacklisted, regardless of activity. A good tutorial on REGEX should be consulted for help on this if needed. There is also a little tutorial on the sshblack homepage.

$ADDRULE is the command line option used to ADD things to the blacklist. You can use route commands, iptables commands, ipchains commands.... Whatever command you use, the sshblack script will execute this command when it is triggered. Some example commands are on the sshblack homepage. The only special thing you need to do is substitute the literal character string 'ipaddress' in the location where you would normally put the actual IP address. The script will search for this string and replace it with the attacker's address as needed.

$DELRULE is the command line option used to DELETE things from the blacklist. You can use route commands, iptables commands, ipchains commands.... Whatever command you use, the sshblack script will execute this command when it removes addresses from the blacklist. Some example commands are on the sshblack homepage. The only special thing you need to do is substitute the literal character string 'ipaddress' in the location where you would normally put the actual IP address. The script will search for this string and replace it with the attacker's address as needed.

$REASONS is the exact, case sensitive REGEX of items that should be considered "attacks". For most modern versions of sshd, the common setting of '(Failed password|Failed none)' works well. It is usually best to NOT use both 'Failed password' and 'Illegal user' as some ssh daemons record both of those for a single failure and it could produce duplicate counts.

$AGEOUT is a timing variable expressed IN SECONDS. This is the amount of time before a suspect IP is removed from the database unless it is already blacklisted. That is, if an attacker has not reached $MAXHITS (see below) attacks by the time $AGEOUT has expired, he will be removed from the database and NOT be blacklisted. Commonly set to 600 seconds (10 minutes).

$RELEASEDAYS is a timing variable expressed IN DAYS. This is the amount of time before a blacklisted host is removed from the blacklist. Commonly set to 3 but can be anything deemed reasonable.

$CHECK is a timing variable expressed IN SECONDS. This is an internal timer used as an interval for parsing the database. Every $CHECK seconds, the script will open the database, see a) if anyone who is already blacklisted should be released from the blacklist, b) if any suspicious IPs should be dropped from the database because they have reached $AGEOUT seconds and are not currently blacklisted. Commonly set to 300 seconds (5 minutes) and should not be set too low (not less than 60 seconds) or too high (not more than 3600 seconds).

$MAXHITS is the number of "attacks" allowed before the IP will be blacklisted. This is commonly set to 4 or 5. This should not be set extremely low so as to allow for legitimate users to mistype their password. It should also not be set extremely high (e.g. 100) as it would reduce the effectiveness of the script. Any legitimate user is going to be well below three or four attempts and any trojan/hacker is going to be above five or six attempts so it is best to keep it in this range.

$DOSBAIL is a denial-of-service counter. If the script detects that more than $DOSBAIL IPs are listed in the database, it will hibernate for one day and do nothing. This is done in an attempt to keep an attacker from spoofing source addresses and loading up the iptables chain with an enormous number of addresses (if this is even possible). It is assumed an administrator would notice the huge number of attack attempts and do something to obviate the problem. This is commonly set to 200 but can be adjusted to whatever the administrator feels is reasonable. Obviously setting the number too low could cause premature hibernation.

$CHATTY determines the amount of logging output produced. 0 and 1 are the only options. A setting of 0 will produce limited output. A message will be produced when the script starts and each time a host is blacklisted or released. A setting of 1 will produce more output in the form of notices each time a host trips a single $REASON even if it hasn't reached $MAXHITS to be blacklisted yet. It defaults to 1 which is usually acceptable for most applications and makes testing a bit easier.

$EMAILME is used to decide if the script will E-mail the administrator when certain events occur. 0 and 1 are the only options. A setting of 1 will cause E-mails to be generated only when an address is added to or released from the blacklist.

$NOTIFY is the E-mail address of the administrator monitoring sshblack activity. The can be left as 'root' or it can be set to any local user such as 'webmaster' or it can be set to a valid SMTP address such as 'bubba@example.com'. Obviously E-mail is sent to this address only if $EMAILME is enabled.

Maintaining things with cron

Some have suggested that sshblack should fully maintain the iptables configuration it works with, including saving, checking and restoring chains and rules. I have chosen not to do this for several reasons which are beyond the scope of this section. However, here are some pointers that allow you do do these kind of operations yourself.

Actually, starting sshblack after a reboot can be as simple as placing the full path and file name in your /etc/rc.d/rc.local file (or whatever directory/file your OS uses for custom start-up scripts). This will start sshblack very quickly after your machine boots.

Saving the iptables configuration can be important because if the custom chain sshblack uses is not restored after a reboot, obviously sshblack won't be able to add/delete rules for a non-existent chain. If your machine supports it, saving and restoring iptables configs can be done easily using iptables-save and iptables-restore.

Execution of the iptables-save command can be done in the root crontab or it can be placed in the /etc/cron.daily directory. You can of course do this save every hour if you like by placing the shell file in the /etc/cron.hourly directory. Here is an example of an iptables-save script:

#!/bin/sh # Save iptables configuration to /etc/sysconfig/iptables.1 /sbin/iptables-save -c > /etc/sysconfig/iptables.1

If you'd like to use crontab to do this same thing you can execute the following command:

[root@stinky root]# crontab -e

You will then see your crontab configuration (likely opened in vi). Simply place the following command into your crontab file and save it:

mailto = "root" 25 * * * * /sbin/iptables-save -c > /etc/sysconfig/iptables.1

Now, how do we pull this information back into iptables in the event of a reboot? Simple, just go back to your /etc/rc.d/rc.local and add in the iptables-restore command [Be sure to place this line BEFORE the line that starts sshblack in your rc.local file]. This will pull that saved information back in to iptables.

/sbin/iptables-restore -c < /etc/sysconfig/iptables.1

Note that iptables-restore will not only restore the rules that sshblack has added, it will restore any custom chains also.