LaBrea::Tarpit::Report - tarpit log analysis and report

  use LaBrea::Tarpit::Report qw( ... );

  generate($input,\%look_n_feel,\%output);
  gen_short($input,\%output);
  syslog2_cache($input,\%config);
  guests(\%report,\%look_n_feel,\%output);
  guests_by_IP(\%report,\%look_n_feel,\%output);
  capture_summary(\%report,\%look_n_feel,\%output);
  got_away(\%report,\%look_n_feel,\%output);
  my_IPs(\%report,\%look_n_feel,\%output);
  get_config(\%hash,\%look_n_feel);
  get_versions($report,\%look_n_feel,\%output,$dname);
  port_stats(\%report,\%look_n_feel,\%output);
  short_report(\$report,\%out);
  $html=make_buttons(\%look_n_feel,$url,$active,\@buttons,$xtra);
  $html=make_port_graph($port,\%look_n_feel,$max,\@counts);
  $html=make_image_cache($pre,@images);
  $html=make_jsPOP_win($name,$width,$height);

utility subroutines (not exported)

  $hex = age2hex($age,$scale_factor);
  $td_string=txt2td(\%config_hash,string);
  $time_string=time2local($epoch_time,$tz);
  $port_text=get_portname($port,\%trojan_list)
  $port_text=Getservbyport($port,$proto);
  $image_html=element($ht,$w,$alt,$img);
  $color=pcolor($number);
  @scaled_array=scale_array($sf,@array);
  $max=max(@array);
  $scriptname=scriptname();

This modules provides a simple interface to the data generated by the LaBrea::Tarpit reporting module. It is intended as an example of how to interface to LaBrea::Tarpit and was patched together hastily. When used with html_report.plx or paged_report.plx found in the examples directory, it will produce an html pages showing all the capabilities of LaBrea and the LaBrea::Tarpit module.

You should write your own version of

sub generate using it as a guide and the individual report generation subroutines described below. sub generate is an example routine that encompasses all the reports created by this module.

* generate($input,\%look_n_feel,\%output)

  Returns false on success, error message $@ on failure.
  Likely cause of failure is dameon not running
  when attempting to open a connection to the daemon

  input		= '/path/to/cache_file' 
		      or
		  hash->{d_host}	[optional]
		  hash->{d_port}	[optional]
		  hash->{d_timeout}	[optional]

  %look_n_feel	(	# defaults shown
    'face'	=> 'VERDANA,ARIAL,HELVETICA,SANS-SERIF',
    'color'	=> '#ffffcc',
    'bakgnd'	=> '#000000',
  # below are all for port_intervals
    'images'	=> 'path/to/images/',	# REQUIRED
    'height'	=> 72,			# default
    'width'	=> 7,			# default
    'legend'	=> 'text for graph',	# optional
    'threshold'	=> 2,	# ignore below this count
    'trojans'	=> \%trojans,		# optional
  	#	 where %trojans is of the form
	#	( # info not in /etc/services
	#	# port		text
	#	  555	=> 'phAse zero',
	#	  1243	=> 'Sub-7',
	#	# etc....
	#	);
  # SEE: examples/localTrojans.pl
  # required html cache control
    'html_cache_file' => './tmp/html_report.cache',# optional
    'html_expire'     => '5',         # cache expiration, secs

  # optional other_sites stats cache location
    'other_sites'     => './tmp/site_stats',
  # optional whois action name
    'whois'           => 'whois',	(as in whois.cgi)
  );

Output hash, fills the values with html text if the key->value pair exists, otherwise it's skipped.

  %output	(	# hash of the form:
    'guests'		=> undef,
    'guests_by_IP'	=> undef,
    'capture_summary'	=> 5,	# days to show
    'got_away'		=> undef,
    'my_IPs',		=> undef,
    'date'		=> (is always inserted)
    'port_intervals'	=> 30,  num intervals to show
    'versions'		=> header || 'undef',
    'other_sites'	=> undef,
  );

  where the above hash will be filled with text
  for the keys that you provide. Text generated
  is of the form:

* gen_short(($input,\%output);

sub gen_short takes similar arguments as generate, however the %output array may be (usually is) empty. It will insert the minimum information required in %output prior to a call to short_report.

Returns false on success, error message $@ on failure. Likely cause of failure is dameon not running when attempting to open the daemon fifo.

It produces the same results as:

  prep_report(\%tarpit,\%out);
  return $@;

for an empty %out starting hash

* syslog2_cache($input,\%config);

  Returns true, false on failure. Likely cause of 
  failure is a missing input log file or missing
  or not writeable cache file.

  $input	path/to/log_file
  %config	same as Tarpit::daemon(\%hash)
		except that 'LaBrea' and 'pid'
		'pipe' are not required.

  The cache file (if present) will be read
  prior to adding the information from the log file
  and will be created if not present at the end of
  the log analysis. The cache file can then be used
  by the generate routine (above) to create a report.

  This is a demonstration routine. All of this can be
  accomplished in one fell swoop using LaBrea::Tarpit
  subroutine calls. Your are encouraged to write your
  own versions of "generate" and "syslog2_cache"

* guests(\%report,\%look_n_feel,\%output);

  	    html table

	4 lines of explanation
		-
		-
		-
  IP:Port->destPort | Held Since | IP:Port->destPort | Held Since

  fills:        %output{guests} with html table
  returns:      true on success

* guests_by_IP(\%report,\%look_n_feel,\%output);

  	     html table

	2 lines of explanation
		-
  IP addr | # Threads | IP addr | # Threads | IP addr | # Threads |

  fills:        %output{guests_by_IP} with html table
  returns       true on success

* capture_summary(\%report,\%look_n_feel,\%output);

  	html table

	bandwidth
	today
	yesterday
	  -
	prior days

  fills:        %output{capture_summary} with html table
  returns:      true on success

* got_away(\%report,\%look_n_feel,\%output);

  	    html table

	3 lines of explanation
		-
		-
  IP -> destPort | Last Scan | IP -> destPort | Last Scan

  fills:        %output{got_away} with html table
  returns:      undef or html text

* my_IPs(\%report,\%look_n_feel,\%output);

  input: \%report,	pointer to report
	 \%look_n_feel,	pointer to look and feel	
	 \%output,	pointer to output

  	    html table

	5 lines of explanation
		-
		-
		-
		-
      IP  |  IP  |  IP  |  IP  | IP

  fills:        %output{my_IPs} with html table
  returns:      true on success

* $html=get_versions($report,\%look_n_feel,\%output,$dname);

  Return html table of versions numbers, no border

       $header
  $dname	nn.nn
  Tarpit	nn.nn
  Report	nn.nn
  Util		nn.nn

  $dname defaults to 'LaBrea' if false
  fills:        %output{versions} with html table
  returns:	true on success

* other_sites(undef,\%look_n_feel,\%output);

Generate a synopsis report of activity at all sites using LaBrea::Tarpit that issue a short_report. Report is a 6 column html table with a marker comment at the beginning of the form:

 <table ....>
 <!-- INSERT MARKER -->
 -----------------------------------------------------
 | hyper-linked  nmbr  nmbr  current   last  LaBrea  |
 |     URL     threads IP's bandwidth update version |
 -----------------------------------------------------
 | www.foo.com   323   106     118    string  string |
 -----------------------------------------------------
 |    etc....                                        |
 -----------------------------------------------------

  input:	first parameter is "don't care"
		to maintain compatibility with other
		reports of the form:
		\%report,\%look_n_feel,\%output

  fills:        %output{other_sites} with html table
  returns:      true on success

* $html=make_image_cache($pre,@images);

Generate javascript code to cache a list of images

  input: path to images,
	 list of images in addition to standard

  returns:	html for javascript
	   i.e.
  <script language=javascript1.1>
  var images=new Array(n);
  for(var i = 0; i < n; n++) {
    image[i] = new Image();
  }
  image[0] = "pre/image0";
    .
    .
  </script>

* $html=make_jsPOP_win($name,$width,$height);

This function makes the javascript code to generate a pop-up window. The function name created is 'popwin', the name and size are arguments to the function call.

  input:	window name,
		width [optional - 500 def]
		height [optional - 400 def]
  returns:	html text

The javascript function returns 'false'.

* port_stats(\%report,\%look_n_feel,\%output);

  generate html port statistics tables sorted by decending
  port activity then ascending port numbers of the form:

           (see &make_port_graph for details)

  #######################################################
  #			     				#
  #   #####################  	#####################   #
  #   #    description    #  	#      example      #	#
  #   #####################  	#####################   #
  #			     				#
  #   #####################  	#####################   #
  #   #      graph1       #  	#       graph2      #	#
  #   #####################  	#####################   #
  #			     				#
  #   #####################  	#####################   #
  #   #      graph3       #  	#       etc...      #	#
  #   #####################  	#####################   #
  #			     				#
  #######################################################

* short_report(\$report,\%out);

Generate summary text of the form:

  LaBrea=2.4b3
  Tarpit=0.18
  Report=0.14
  Util=0.02
  now=1018832056  *note:
  tz=-0700    
  threads=462 
  total_IPs=243 
  bw=230  

First call sub prep_report with %out, %out may be empty.

always returns true

Note: now is time since epoch at the site. To properly represent it at the origin site do:

  LaBrea::Tarpit::Util::their_date($now,$tz);

* $html=make_port_graph($port,\%look_n_feel,$max,\@counts);

Return html table graph of @counts values scaled, colored per look_n_feel for port

used internally by port_stats to create individual port graphs.

  Example 30 day shown:

  port 31337
  BackOrifice
  1	  max probes 138		30
  --------------------------------
	*	*
	*  *	*
  *	*  *	*	*  *	*
  ** *	** ***	*   *	*  * * **
  ************* ** **  *** *** ***
  ************* ****** ******* ***	
  --------------------------------

* $html=make_buttons(\%look_n_feel,$url,$active,\@buttons,$xtra);

  Return the html text for a button bar

  input:	\%look and feel
		url (if @buttons url !~ m|/|)
		active button value (not text)
		\@button array
		xtra,
		  true = width of bar
		  false = horizontal and
		    $active = anchor tag

  returns:	html for button bar

  @buttons is a list of the form = (
	# text	      command
        'BUTT1' => 'command1',
        'BUTT2' => 'command2',
	''	=> '',
	'BUTT3'	=> 'http://somewhere.com',

  # buttons may include other text to include in the
  # <a   .... > tag separated by spaces

	'BUTT4'	=> 'command onClick="somefunction();"',

  #which will result in an atag containing the onClick function

  );
	If the button text is false,
	a spacer is inserted in the button bar

  NOTE:		class NU must be defined
  example:
		<style>
		A.NU {
		  color: red;
		  background: transparent;
		  font-family: "Helvetica";
		  font-weight: bold;
		  text-decoration: none;
		}
		</style>

* $rv = get_config(\%hash,\%look_n_feel) {

Retrieves and stores the config information about the remote daemon process. The resulting config file is used by my_IPs.

  input:	$hash->{d_host}	[optional]
		$hash->{d_port}	[optional]
			default is localhost:8686
		$hash->{d_timeout} default 180
		$look_n_feel->{html_cache_file}
  returns:	false on success
		else error message
		html_cache_file updated

  Note:		silently skips if %hash is
		configured for file service

* $hex=age2hex($age,$scale_factor);

html utility

  Convert an age in seconds to a hex number
  represented in ascii, range 00 -> FF
  i.e.
  with a scale factor of one,
	0	-> FF
	255	-> 00

  The default scale factor, if omitted, is 3

* $td_string=txt2td(\%config_hash,string);

html utility

  Convert a string into a formated table
  entry of the form:

    <td align=xx bgcolor=yy>
    <font face=aa size=nn color=RGB>
     string
    </font></td>

  input:	\%hash, text
	where %hash = (
		'face'	=> font face,
		'size'	=> font size,
		'f_clr'	=> font color,
		'td_clr'=> table background color,
		'align'	=> alignment statement,
	);
	missing items are not inserted into the table

  returns:	<td options>txt</td>

* $time_string=time2local($epoch_time,$tz);

html utility

  Convert seconds since the epoch to the form:

  13:27:56 (-0800) 11-29-01

  $tz =	time zone or blank if missing.

* $port_text=get_portname($port,\%trojan_list)

html utility

  Looks up a port number first in %trojan_list
  if present, then /etc/services (tcp then udp)

  %trojans = (		# optional
	port number => text description
	);

  returns:	description

* $port_text=Getservbyport($port,$proto);

html utility

replacement for getservbyport which is broken for use in mod_perl 1.26 but works OK for plain cgi

* $image_html=element($ht,$w,$alt,$img);

html utility

  create html image text of the form

 <img src=$img height=$ht width=$w hspace=1 alt="$alt">

* $color=pcolor($number);

html utility

  return color text based on input number

  0	-> <10		blu
  10	-> <100		ltb
  100	-> <1000	grn
  1000	-> <10000	org
  10000	-> <100000	red
  >= 100000		mag

* @scaled_array=scale_array($sf,@array);

html utility

  scale an array of values with SF
  smallest non-zero value is 1

  returns:	@scaled_array

* $max=max(@array);

html utility

  return the maximum numeric value from 
  an array but not less than 1

* $scriptname = scriptname();

html utility

Returns the scriptname of the caller from ENV{SCRIPT_NAME}

	capture_summary
	generate
	gen_short
	get_config
	get_versions
	got_away
	guests
	guests_by_IP
	make_buttons
	make_image_cache
	make_port_graph
	make_jsPOP_win
	my_IPs
	other_sites
	port_stats
	short_report
	syslog2_cache
	time2local
	valid_request

Copyright 2002 - 2008, Michael Robinton & BizSystems This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Michael Robinton, michael@bizsystems.com

perl(1), LaBrea::Tarpit(3), LaBrea::Codes(3), LaBrea::Tarpit::Get(3), LaBrea::Tarpit::Util(3), LaBrea::Tarpit::DShield(3)