File Coverage

blib/lib/LaBrea/Tarpit.pm

Criterion	Covered	Total	%
statement	235	260	90.3
branch	113	138	81.8
condition	45	63	71.4
subroutine	15	18	83.3
pod	9	9	100.0
total	417	488	85.4

#!/usr/bin/perl
package LaBrea::Tarpit;
#
# 2-5-05, [e-mail]
#
BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN }}
$__PACKAGE__::DOWARN = 1;
use strict;
#use diagnostics;
use vars qw($VERSION @ISA @EXPORT_OK);

$VERSION = do { my @r = (q$Revision: 1.36 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };

use Fcntl qw(:DEFAULT :flock);
use AutoLoader 'AUTOLOAD';
require Exporter;
@ISA = qw(Exporter);
@EXPORT_OK = qw(
	recurse_hash2txt
	daemon
	bandwidth
	midnight
	timezone
	tz2_sec
	their_date
	restore_tarpit
	log2_mem
	process_log
	cull_threads
	write_cache_file
	prep_report
	find_old_threads
	array2_tarpit
);

use constant defaults => {	# seconds
	'cull'		=> 600, # drop threads older than this
	'min_age'	=> 15,	# don't cull for at least
	'auto_cull'	=> 900,	# cull at least every
	's_timeout'	=> 0.1,	# select timeout
	'sock_timeout'	=> 180,	# give up on socket response
};
use constant mon => {
	qw(jan 0 feb 1 mar 2 apr 3 may 4 jun 5 jul 6 aug 7 sep 8 oct 9 nov 10 dec 11)
};

=head1 NAME

  LaBrea::Tarpit - Utilities and web displays for
  Tom Liston's LaBrea scanner/worm disruptor

  See: http://sourceforge.net/projects/labrea/

=head1 SYNOPSIS

  use LaBrea::Tarpit qw( [exportable functions] );
  or
  require LaBrea::Tarpit;

  daemon(%hash or \%hash);

  $bandwidth = bandwidth(\%tarpit);

  $midnight = midnight($epoch_time,$tz);

  $timezone = timezone($now);

  $sec = $tz2_sec($tz);

  $time_string = their_date($gmtime,$tz);

  $rv = restore_tarpit(\%tarpit,path2cache_file);

  $rv = log2_mem(\%tarpit,log_line,is_daemon,port_intvls,DShield);

  $rv = process_log(\%tarpit,path2log_file,is_daemon,port_intvls);

  $rv = cull_threads(\%tarpit,timeout,scanners,port_intvls,DShield);

  $rv = write_cache_file(\%tarpit,path2cache_file,umask,flag);

        prep_report(\%tarpit,\%hash);

  $rv = find_old_threads(\%tarpit,\%report,$age);

=head1 INSTALL

=over 4

=item * Package

	Untar the package

	perl Makefile.PL
	make
	make test
	make install

	To use examples/daemon.pl, configure
	the array at the beginning of the script
	and set the locations for the cache files.
	...typically /var/tmp/labrea.cache
	and /var/tmp/DShield.cache

=item * Report/examples/html_report.plx

=item * Report/examples/paged_report.plx

B and B will run as a cgi scripts
by simply renaming them B. It is highly recommend that
you  enable the file caching to minimize load on your system.

Read the comments in the file itself for configuration.
The defaults should work fine, but you must create the
temporary directory used for file caching AND it must
be writable by the web server.

B and B are configured to provide B
reporting. You must set up the cron job maintain the
B file for reporting. B below:

=item * Get/examples/web_scan.pl

Run B from a cron job hourly or daily to
update the statistics from all know sites running
LaBrea::Tarpit. A report can then be generated showing
the activity worldwide.

  # MIN HOUR DAY MONTH DAYOFWEEK   COMMAND
  30 * * * * ./web_scan.pl ./other_sites.txt ./tmp/site_stats

  Also see: LaBrea::Tarpit::Report::other_sites

=item * examples/tell_me.pl AGE

Run B from a cron job daily to send yourself
an email detailing teergrubed hosts that have been
held longer than B days. You might actually want
to tell the bad guys that they have a rogue machine.

  # MIN HOUR DAY MONTH DAYOFWEEK   COMMAND
  30 * * * * ./tell_me.pl 60  # default

=item * DShield/examples/mail_dshield.pm

Configure with your DShield UserID, email address, mail agent and
the location of the daemon - DShield cache file, then run periodically from
cron to send reports to DShield.

=back

=head1 DESCRIPTION - LaBrea::Tarpit

A comprehensive Hack Attack reporting module when used in conjunction with
Tom Liston's LaBrea scanner/worm disruptor. When configured with reporting
and stat collection it provides a detailed HTML page containing:

=over 4

=item * Bandwidth consumed by attack/disruption daemon

=item * Summary of previous 5 days of attack/disruption

=item * All IP addresses currently attacking

=item * IP address, port attacked/held, attack start time

=item * As above, but history of terminated attacks

=item * By day detail graphs on port attack intensity

=item * Active summary of known LaBrea::Tarpit sites

=back

For more information on B see: L
or contact the author of LaBrea, Tom Liston L.

The parsed output of either syslog data or STDOUT from LaBrea using -o or -O
options is readily turned into text reports or an html output page.

Basically there are two methods of operation. You can use the B mode
to create an almost realtime cache that may be parsed using the report
routines, or you can use the update and report routines to parse the syslog
files on an as needed basis. If you plan to create web page reports, the
daemon model will use less system resources in the long run and avoids
running syslog with the high volume output of LaBrea.

Improvements VERSION 1.00

As of version 1.00, B uses network sockets to provide data for
the report modules. This means that the daemon can run on a remote machine
and the report scripts and web server can be somewhere else.

For those of you upgrading from older versions, you B upgrade all of
your report scripts as well. Older versions use a pipe or FIFO and this is
no longer supported as there were problems maintaining separate sessions.

=cut

# memory records are kept in the form:
#
# %tarpit			# time is kept in seconds since epoch
#	{bw}	-> bandwidth	# bytes per second
#
#	{tz}	-> timezone	# i.e. text string = -800
#
#	{now"	-> epoch time	# only used when writing cache,
#				# not current otherwise
#   active threads
#	{at}	-> {srcIP_1}	-> {sp1} -> {dip} -> destination IP
#		     .	      (src_port1)   {dp}  -> destination port
#		     .	      .		    {pst} -> protocol type (0,6=tcp)
#						for tcp = persistent [true/false]
#		     .	      .		    {ct}  -> capture time
#		     .	      .		    {lc}  -> last contact time
#		     .        .
#		     .		-> {sp2} -> {dip} -> destination IP
#		     .	      (src_port2)   {dp}  -> destination port
#		     .			    {pst} -> protocol type (0,6=tcp)
#						for tcp =  persistent [true/false]
#		     .			    {ct}  -> capture time
#		     .			    {lc}  -> last contact time
#		     .
#		   {srcIP_2}	-> etc...
#   dead threads
#	{dt}	-> {srcIP}	-> {dp}  -> last destination port
#				   {lc}  -> last contact time
#		     .
#   port stats
#	{ph}	-> {timea}	-> {port num.x}	  -> count
#		     .		-> {port num.y}   -> count
#		     .		-> {port num.z}   -> count
#		   (timeb}	-> etc...
#
#	{pt}	-> collection_interval

=over 2

=item * recurse_hash2txt(\$txt_buffer,\%hash,$keys_so_far,flag)

 Appends to txt_buffer.

 Generates a text tree of a hash.
 %hash{lvl1}->{lvl2}->{lvl3} = 5;	this real hash
 flag = 0, ksf = ''			with this input
 lvl1:lvl2:lvl3:5		produces this text
 flag = 1, ksf = ptr			this input
 ptr->{lvl1}->{lvl2}->{lvl3} = 5;	this txt

=cut

# input:	txt out pointer, pointer to hash, keys so far, dump | debug
# 		if the dod flag is 0, this is normal dump mode
#		else it's the fancy debug mode
sub recurse_hash2txt {
  my ($txp, $p, $ksf,$dod) = @_;
  foreach my $key (sort keys %{$p}) {
    my $keysnow = $ksf;
    $keysnow .= ($dod) ? qq|->{$key}|
	: ($ksf)
		? ':'. $key
		: $key;
    if (ref $p->{$key}) {
      &recurse_hash2txt($txp,$p->{$key},$keysnow,$dod);
    } else {
      $keysnow .= ($dod) ? ' = ' : ':';
      $keysnow .= ($p->{$key} || 0) . "\n";
      $$txp .= $keysnow;
    }
  }
}

=item * ($LBfh,$version,$kid) = lbd_open($LaBrea,$DEBUG);

Core daemon start routine. Not exported, but can
be replaced externally with:

  *LaBrea::Tarpit::lbd_open = sub { stuff };

Returns the pid of the underlying process (if any) and the version number of
that process. It also sets the command line shown by 'ps' like this:

  $0 = 'stuff';

  input:	path to daemon,
		STDERR switch
  returns:	LaBrea file handle,
		version,
		pid of kid

=cut

sub lbd_open {
  my($LaBrea,$DEBUG) = @_;
  local *LABREA;
  $LaBrea =~ /^([^\s]+)/;		# bare path to LaBrea
  qx/$1 -V 2>&1/ =~ /(\d+\.[^\s]+)/;	# get version
  my $version = $1;			# save version
# open LaBrea daemon
  my $kid = open(LABREA,$LaBrea .' |');
  die "Can't open $LaBrea: $!" unless $kid;
  unless ($DEBUG) {
    open STDERR, '>&STDOUT'		or die "Can't dup stdout: $!";
  }
  $0 = __PACKAGE__.' '.$0;		# set ps(1) name to package name
  return(*LABREA,$version,$kid);
}

=item * lbd_close($LBfh,$kid);

Core daemon close routine, not exported but can be
replaced externally with:

  *LaBrea::Tarpit::lbd_close = sub { sutff };

Close the daemon and kill off $kid with sig 15

  input:	filehandle,
		pid of kid
  returns:	nothing

=cut

sub lbd_close {
  my($LBfh,$kid) = @_;
  kill 15, $kid;				# kill LaBrea
  close $LBfh;
}

# autoload everything to keep daemon small
sub daemon;
sub bandwidth;
sub midnight;
sub timezone;
sub restore_tarpit;
sub log2_mem;
sub process_log;
sub cull_threads;
sub write_cache_file;
sub prep_report;
sub find_old_threads;
sub array2_tarpit;

# helper subroutines
#sub _cullnsquish;
sub _check4cull;
sub _init_pt;
sub _add_array;
sub _cache2txt;
sub _ex_append;
sub _get_config;
sub DESTROY {};

1;
__END__