#!/usr/bin/perl -w
use strict;

## Scott Wiersdorf
## Created: Tue Jan  3 09:25:34 MST 2006
## $Id: rascals,v 1.12 2007/01/02 17:28:48 scott Exp $

## rascals - tarpit via hosts.allow for dictionary attacks

## usage: rascals [selection options] [action options] log

our $VERSION = '1.10';

use Time::Local qw(timelocal);
use Getopt::Long;
my %opt = ( report => '', 
	    exclude => [],
	    service => 'sshd',
	    period  => '5m',
	    limit   => 5,
	    pattern => '^Failed password for (?:root|(?:[Ii]nvalid|[Ii]llegal) user \S+) from (\S+)',

	    expire  => '2h',
	    rascals => '/var/log/rascals',
	  );

unless( GetOptions( \%opt,
		    'help|h',
		    'report=s',
		    'version',

		    'exclude:s',
		    \@{$opt{exclude}},
		    'service|s=s',
		    'period|p=s',
		    'limit|l=i',
		    'pattern=s',

		    'expire|e=s',
		    'rascals|r=s', ) ) {
    usage();
}

usage() if $opt{help};
die "This is rascals version $VERSION\n" if $opt{version};

$opt{pattern} = qr($opt{pattern})io;

my %Moy  = ( Jan => 0, Feb => 1, Mar => 2, Apr => 3, May => 4, Jun => 5,
	     Jul => 6, Aug => 7, Sep => 8, Oct => 9, Nov => 10, Dec => 11 );
my $time      = time;
my ($c_month, $c_year) = (localtime($time))[4,5];
my $threshold = $time - to_seconds($opt{period});
my $expires   = $time + to_seconds($opt{expire});
my %exclude_hosts = ();
@exclude_hosts{@{$opt{exclude}}} = (1) x @{$opt{exclude}};
my %hosts     = ();
my $line      = 0;
my $last_month = 0;

while( <> ) {
    chomp;

    ## look for lines like this:
    ## Jan  2 23:32:33 deep2 sshd[5482]: Invalid user staff from 210.240.17.26

    ## this is fast
    my($mon,$day,$hr,$min,$sec,$srv,$msg) 
      = $_ =~ /^(\w+)\s+               ## month
                (\d+)\s+               ## day
                (\d+):(\d+):(\d+)\s+   ## hh:mm:ss
	         \S+\s+                ## skip hostname
	        ([\w\.-]+)\[\d+\]:\s+  ## service (skip [pid]:)
	        (.+)/x                 ## message
		  or next;

  SPAN_YEAR_CHECK: {
	## first line: look at the month
	if ( $line++ == 0 ) {
	    if( $Moy{$mon} > $c_month ) {  ## a log that spans last year
		$c_year -= 1;              ## decrement the year
	    }
	}

	## subsequent lines: look for the new year
	else {
	    if( $Moy{$mon} < $last_month ) {
		$c_year += 1;
	    }
	}

	$last_month = $Moy{$mon};
    }

    ## look for this service
    next unless $srv eq $opt{service};

    ## look for message pattern
    next unless my($host) = $msg =~ $opt{pattern};
    next if $exclude_hosts{$host};

    ## do time conversion
    my $line_t = timelocal($sec,$min,$hr,$day,$Moy{$mon},$c_year);

    ## reject lines too old
    next if $line_t < $threshold;

    ## count hosts
    $hosts{$host}++;
}

## write out to the expiration log
my $tmp_rascals = $opt{rascals} . ".$$.tmp." . int(rand(999999));
die "$tmp_rascals exists! Exiting\n" if -e $tmp_rascals;
open TMP, ">", $tmp_rascals
  or die "Could not write to temp file: $!\n";

## preen hosts under the limit
my @hosts = ();
for my $host ( keys %hosts ) {
    next if $hosts{$host} < $opt{limit};
    push @hosts, $host;
}

## add these hosts to the new rascals file
if( scalar @hosts ) {
    print TMP "## expires: $expires (" . scalar localtime($expires) . ")\n";
    print TMP $_ . "\n" for @hosts;
    print TMP "\n";

    if( $opt{report} =~ /^(?:new|all)/i ) {
	print STDERR "New rascals (expire " . scalar localtime($expires) . ")\n";
	print STDERR $_ . "\n" for @hosts;
	print STDERR "\n";
    }
}

## remove expired rascals
if( open LOG, "<", $opt{rascals} ) {
    my $skip = 0;

    while( <LOG> ) {
	if( my ($expire) = $_ =~ /^\#\# expires: (\d+)/ ) {
	    $skip = $time > $expire;
	    if( $skip ) {
		if( $opt{report} =~ /^(?:old|all)/i ) {
		    print STDERR "Expired rascals (" . scalar localtime($expire) . "):\n";
		    next;
		}
	    }
	}

	## normal line
	if( $skip ) {
	    if( $opt{report} =~ /^(?:old|all)/i ) {
		print STDERR;
	    }
	    next;
	}

	print TMP;
    }
    close LOG;
}

close TMP;

rename $tmp_rascals, $opt{rascals};

exit;

sub to_seconds {
    my $ts = shift;
    my ($tm,$unit) = $ts =~ /^(\d+)([dhms]?)/;
    $unit ||= 'm';

    if( $unit eq 'd' ) {
	$tm *= ( 60 * 60 * 24 );
    }
    elsif( $unit eq 'h' ) {
	$tm *= ( 60 * 60 );
    }
    elsif( $unit eq 'm' ) {
	$tm *= 60;
    }

    return $tm;
}

sub usage {
    die <<'_USAGE_';
rascals [selection options] [action options] auth.log

'rascals' scans recent lines in auth.log for lines matching:

  (date) (hostname) (service)[pid]: Invalid user (user) from (remote host)

and adds 'remote host' to /var/log/rascals for denial from
/etc/hosts.allow. You'll need to add this one line to the top of your
/etc/hosts.allow file:

  sshd : /var/log/rascals : deny

selection options:
  --log=logfile          which logfile to look for rascals
  --exclude=host         exclude this host when looking for rascals. May be
                         specified multiple times
  --service=srv          service as found in auth.log (default = sshd)
  --period=time          length of time to query log in minutes (default = 5m)
  --limit=num            maximum allowed 'invalid user' errors per host (default = 5)
  --pattern=message      experts only: specify a different log message pattern

action options:
  --expire=time          remove entries older than 'time' (default = 2h)
  --rascals=filename     write to this file (default = /var/log/rascals)

See 'perldoc rascals' for complete documentation.

_USAGE_
}

=head1 NAME

rascals - find and blacklist rascally twerps

=head1 SYNOPSIS

  rascals --exclude=231.58.192.122 --period=1h --limit=30 --expire=1d auth.log

=head1 DESCRIPTION

B<rascals> reads F<auth.log> looking for ssh dictionary attackers
("rascals") and adds the offending host to a blacklist. This list may
be used by the "tcp wrappers" subsystem (via F</etc/hosts.allow>) to
block or tarpit attacking hosts.

B<rascals> automatically removes older entries in the F<rascals>
blacklist each time it runs, based on the expiration date when the
entries were added.

B<rascals> is designed to run with no maintenance: install and forget.

B<rascals> may be run from the command-line as root, or from a root
crontab (see L<INSTALLATION> and L<EXAMPLES>, especially the
B<Author's usage> below).

Nearly all of the default behavior of B<rascals> can be changed (see
L<OPTIONS> below).

To make use of the F<rascals> blacklist using tcp wrappers, add the
following line to the top of your F</etc/hosts.allow> file:

  sshd : /var/log/rascals : deny

See L<EXAMPLES> below for some other interesting F</etc/hosts.allow>
options.

=head1 INSTALLATION

For the impatient, here is the checklist of things that must be done
for B<rascals> to maintain its blacklist automatically:

=over 4

=item * install B<rascals>

Use the installer provided, or just copy B<rascals> to your favorite
system executable directory (e.g., F</usr/local/sbin>). Make sure
B<rascals> is executable:

  chmod 0755 /usr/local/sbin/rascals

=item * add F</etc/hosts.allow> entry

Something like this in F</etc/hosts.allow>:

  sshd : /var/log/rascals : deny

=item * add F</etc/crontab> entry

Here's a sample crontab entry to run B<rascals> every half-hour (make
sure the path to F<rascals> matches your installation):

  */30 * * * *  root  /usr/local/sbin/rascals /var/log/auth.log

The author runs B<rascals> every 2 minutes, with a period of 2m so no
evil-doers miss an opportunity to be trounced:

  */2 * * * *  root  /usr/local/sbin/rascals --period=2m /var/log/auth.log

=back

That's it--no fuss, no muss.

=head1 OPTIONS

In a nutshell, B<rascals> works like this:

Rascals goes through the last 5 minutes ("period") of the given log
looking for 5 entries ("limit") matching sshd ("service") requests for
"Illegal user" ("pattern") and adds the offending IP to the rascals
log ("rascals") for a period of 2 hours ("expire").

All options are configurable: you can change the period (how much of
the log to examine), the limit (how many times an offense must occur
before they're blacklisted), the service (defaults to sshd, but could
be any service, such as 'sm-mta' or 'ipop3d'), the pattern (what an
offense looks like in the log), and the expiration (how long the
offending IP will be on the blacklist).

This section describes in some detail your options.

=head2 General Options

=over 4

=item B<help>

Shows a brief help message and exits.

=item B<report=[new|old|all]>

Writes a brief report to STDERR when done. This options is useful if
you want to get a little reporting from cron or just want to see what
happened.

If 'new' is specified, new rascals added to the blacklist will be
returned (if no output appears, no new entries were added to the
blacklist at this time).

If 'old' is specified, expiring rascals will be listed (if no output
appears, no expiring rascals were removed from the blacklist at this
time).

'all' prints both new additions and expirations.

If no report type is specified, B<rascals> runs silently.

=item B<version>

Shows the current version of B<rascals> and exits.

=back

=head2 Selection Options

These options determine how B<rascals> finds hosts that are attacking
your server.

Please be aware that B<rascals> only understands log files in standard
I<syslog> format:

  Jan 10 12:02:38 myhostname someservice[8888]: message from someservice

This includes auth.log, maillog, messages, and other common logs
written to by B<syslog>.

=over 4

=item B<exclude>

Which hosts to exclude when looking for rascals. This option may be
specified multiple times for each host to exclude. E.g.,:

  rascals --exclude=123.45.67.89 --exclude=132.41.33.12

The B<exclude> option is a safety valve: put your own IP address here,
as well as any addresses from valid clients who might regularly
mistype their own password.

Default: (empty)

=item B<service>

Which service to look for in the specified log file when looking for
rascals. Examples of 'services' include sshd, sendmail, proftpd,
telnet, ipop3d, popper, sm-mta, etc. B<rascals> can find attacks from
any type of service (as long as it can be found in a log file), but
tcp wrappers does not wrap all services. Check your host configuration
to determine which services can be protected by tcp wrappers.

Only exact string matches will work here. To match multiple services
you'll need to run B<rascals> multiple times. This may change in a
future release.

Default: sshd

=item B<period>

How far back in F<auth.log> to look for rascals (i.e., entries older
than this will be skipped). See L<Time Specifications> below for valid
time specifications.

Default: 5m

=item B<limit>

How many log entries matching B<pattern> (see next item) necessary
before we decide that this host is a rascal.

Default: 5

=item B<pattern>

The message to look for in F<auth.log>. Changing this should only be
done if you know what you're doing. See L<CAVEATS> for more information.

Default: '^(?:Failed password for root|(?:Invalid|Illegal) user \S+) from (\S+)'

A pattern that might work for some ipop3d dictionary attacks:

  'Login failed .*\[(\S+)\]$'

See also <Log Message Patterns> in the L<CAVEATS> section below for
more pattern help.

=back

=head2 Action Options

These options determine how B<rascals> behaves once it has found
rascally hosts.

=over 4

=item B<expire>

How long the rascals we find during this run should remain on the
blacklist. See L<Time Specifications> below for valid time
specifications. See also L<Expiration Time> in the L<CAVEATS> section
below for help on setting this to increase expiration precision.

Default: 2h

=item B<rascals>

The location of the F<rascals> blacklist. (Also determines the name of
the temporary file used when creating a new F<rascals> blacklist.)

Default: F</var/log/rascals>

=back

=head2 Time Specifications

Times specified in the B<period> and B<expire> options follow this format:

  (integer)(unit)

'integer' may be any positive whole number (e.g., 1, 2, 3, 4, etc.).

'unit' may be one of the following:

=over 4

=item B<d>

days

=item B<h>

hours

=item B<m>

minutes

=item B<s>

seconds

=back

For example, to specify an expiration of 2 weeks:

  --expire=14d

To specify an expiration of 8 minutes:

  --expire=8m

To find entries in the past 12 hours:

  --period=12h

=head1 EXAMPLES

Here are some examples of how to run B<rascals>. Further below are
examples on how to configure F</etc/hosts.allow>, and a sample F<crontab>
entry.

=head2 rascals Examples

Basic usage:

  rascals /var/log/auth.log

This will scan F</var/log/auth.log> for failed sshd attempts. When it
find 5 entries in the last 5 minutes, it will add the attacking host
to F</var/log/rascals> for 2 hours (these are all defaults).

Author's usage:

Here is how your author uses B<rascals> on one of his servers:

    */5 * * * *   root   rascals --exclude=12.34.56.78 --report=all /var/log/auth.log

with the following entry in F</etc/hosts.allow>:

  ALL : /var/log/rascals : spawn /bin/sleep 60
  ALL : ALL : allow

We scan every 5 minutes for attackers. Some attacks can do several
login attempts per second, but for this server 5 minutes is often
enough. I add my own IP address via the B<--exclude> option to make
sure I don't lock myself out of the server.

On another server, the author runs B<rascals> every two minutes, and
sets the B<--period> to '2m' also so there are no gaps in the log
processing (no chance for an attacker to guess the scanning pattern
and bypass detection).

The B<--report> option will cause B<rascals> to write output, which in
turn causes B<cron> to send an email, effectively notifying the system
administrator that this server is under attack.

Processing compressed logs:

If your F<auth.log> rotates frequently, you can use B<zcat> and a pipe
to B<rascals>:

    zcat -f /var/log/auth.log.[012].gz /var/log/auth.log | rascals

which will process these logs:

    /var/log/auth.log
    /var/log/auth.log.0.gz
    /var/log/auth.log.1.gz
    /var/log/auth.log.2.gz

=head2 F</etc/hosts.allow> examples

You might want to try some of these interesting options in your
F</etc/hosts.allow> file. Here's how to just block sshd attacks using
B<rascals>:

  sshd : /var/log/rascals : deny

Here's one way to make a tarpit that allows a login attempt but only
after waiting 30 seconds:

  sshd : /var/log/rascals : spawn /bin/sleep 30

Here's another tarpit, but which closes the connection after the
tarpit:

  sshd : /var/log/rascals : spawn /bin/sleep 30 : deny

You can replace 'sshd' with any service to block that service, or try
'ALL' to disallow any connection attempts to any service that tcp
wrappers protects.

=head2 Crontab examples

You can easily automate the maintenance of B<rascals>' log file using
cron. An entry like this in your F</etc/crontab> file will check for
attacks every half-hour:

  */30 * * * * root /usr/local/sbin/rascals /var/log/auth.log --report=all

=head1 FAQ

Q. The attacks keep coming! What can I do?

A. You probably need a stronger disincentive. Try:

    sshd : /var/log/rascals : spawn /bin/sleep 600

  The trade-off here is that I'm assuming you have plenty of sockets
  to handle the incoming connection attempts. You may find that an
  attack with many simultaneous connections from the attacking IP can
  quickly overwhelm you. If that's the case, just start closing them
  down immediately:

    sshd : /var/log/rascals : deny

  Yes, you'll still get connection attempts, but this will shut them
  down fast enough that the following will likely occur:

    1) you'll have enough sockets for legitimate connections

    2) the attacker will probably give up after a while anyway--you
       have no control over the attackers response.

Q. I watch my logs and notice that an attack will go on for several
   minutes before B<rascals> detects it and shuts it down. How can I
   make B<rascals> scan more frequently?

A. Change the cron entry to scan more frequently. B<rascals> is light
   enough to run every minute, even on very large logs:

     * * * * * root /usr/local/sbin/rascals /var/log/auth.log

  (Note that this is BSD-Vixie /etc/crontab syntax, with a username
  specified in the 6th field.)

=head1 CAVEATS

B<rascals> will likely do what you want without any command-line
options set or changes. However, due to the myriad configurations and
services running on various flavors of Unix out there, these defaults
may not all work for you.

For example, your B<sshd> agent may register itself with syslog as
'sshd2' or some other such name, in which case you'll need to specify
the B<service> option to override the default. Luckily, B<rascals> is
highly configurable.

Below are some of the things you'll want to consider if you need to
set any command-line options for one reason or another.

=head2 Temporary Files

B<rascals> creates a temporary file to which the new rascals are
written and the old rascals are appended. This temporary file is based
on the B<--rascals> option (default: F</var/log/rascals>).

This file should be written to a safe location (i.e., a location where
normal users do not have write privileges) as should all log files.

This temporary file is renamed when it is complete, and overwrites the
old F<rascals> file. A race condition exists when multiple instances
of B<rascals> are running, so try not to do that.

=head2 Log Rotation

If your F<auth.log> is rotated between B<rascals> runs, you won't see
those last entries in the rotated log, unless you figure out some way
to include those compressed logs. You might try this:

  zcat -f /var/log/auth.log.0.gz /var/log/auth.log | rascals

which will make sure you always have the last F<auth.log> rotation
period being processed.

=head2 Expiration Time

The expiration time (set via B<--expire>) will only be precise when it
is a multiple of the frequency of how often you run B<rascals>.

That is, if you run B<rascals> every hour, and your expiration is set
to 90 minutes, the expired rascals will be removed on the next
B<rascals> run I<after> the 90 minutes has gone by, which could add
half an hour to the actual expiration time.

It's best to make the expire time a multiple of the run frequency
(e.g., if B<rascals> runs every half hour, set the expire time to a
multiple of a half hour: 30m, 60m, 90m, 120m, etc.) if you want to
make sure that the blacklist expires precisely (more or less) when you
intend it to.

Most people run B<rascals> at a very short frequency (e.g., 2-5
minutes) in which case the worst expiration lag would be 2-5 minutes,
which probably isn't very important anyway.

=head2 Blacklist Size

The author is not aware of a size limit on the blacklist, but assumes
that tcp wrapper performace would begin to degrade after a few hundred
hosts. Setting a reasonable expiration time will ensure that your
blacklist doesn't become too large for too long.

=head2 Blacklist Not Working

If the F</etc/hosts.allow> doesn't seem to be blocking, you might want
to make sure it's actually installed (beyond the scope of this
document). Try adding yourself to it:

  ALL : my.hostname.tld : deny

Always keep a shell open so you can remove this entry!

Always keep a shell open so you can remove this entry!

Always keep a shell open so you can remove this entry!

(What I tell you three times is true).

If this works, make sure that your B<rascals> entry is above the first
'ALL : ALL : allow' line in F</etc/hosts.allow>. Remember: tcp
wrappers uses a simple 'first-match' algorithm to decide whether to
allow or deny a host.

=head2 Log Message Patterns

If you specify a pattern, it must have at least one "capture", and the
first capture must capture the hostname or IP address of the
rascal. For example, to look for dictionary attacks via ftp, you might
do something like this:

  rascal --service=proftpd --pattern='USER \S+: no such user found from (\S+)'

=head2 Scanning Frequency

If your scanning frequency is more often than the B<period>
specification you have set, you will possibly get duplicate entries
from one scan to the next. To illustrate:

  +------ start of auth.log
  |1
  |2
  |3  <--- scanning starts here, based on 'period' setting
  |4
  |5
  |6
  |7
  |8
  |9
  +------  end of log

If we scan again before 'period' time has elapsed, this will occur:

  +------ start of auth.log
  |1
  |2
  |3
  |4
  |5
  |6  <--- scanning starts here, based on 'period' setting
  |7  * duplicated
  |8  * duplicated
  |9  * duplicated
  |10
  |11
  |12
  |13
  |14
  +------  end of log

This isn't necessarily bad, but is something to be aware of.

=head2 Lockout

You can lock yourself out of your server! Don't do this. And don't
call me if you do--I can't help you. Messing with F</etc/hosts.allow>
can be tricky business if you don't know what you're doing (so read
the manpages listed below and experiement, but always leave a shell
open to your server).

The following brief list are good practices for newbies (and everyone
else):

=over 4

=item * Keep a shell open to the server when experimenting

... and don't close it until you're sure you can login again from that
host.

=item * Keep a backup of F</etc/hosts.allow>

=item * Be conservative

You probably don't have to run B<rascals> every minute of every
day. You're likely reading this because your server has already
handled months of attacks and you're just fed up with disconcerting
log entries, not a DOS attack.

You can run B<rascals> every minute of every day if you are under
serious attack every minute of every day or just can't stomach the
thought of someone knocking on your door all of the time. B<rascals>
runs very fast (just over a second to process an 18M logfile on my
Powerbook, about 2 seconds for a 20M logfile on a dual proc Pentium
4).

=back

=head1 TODO

=over 4

=item *

Make B<rascals> be able to run inline with /etc/hosts.allow to scan
with each connection attempt. Efficiently.

=item *

Allow the B<service> option to be a regular expression and match
multiple services.

=back

=head1 AUTHOR

Scott Wiersdorf, E<lt>scott@perlcode.orgE<gt>

=head1 COPYRIGHT

Copyright (c) 2005 Scott Wiersdorf. All rights reserved.

=head1 LICENSE

B<rascals> is released under the the same terms as Perl itself.

=head1 SEE ALSO

L<hosts_options(5)>, L<hosts_access(5)>, F</etc/hosts.allow>

=cut