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

SYNOPSIS
      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();

DESCRIPTION - LaBrea::Tarpit::Report
    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}

EXPORT_OK
            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
    Copyright 2002, 2003, 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.

AUTHOR
    Michael Robinton, michael@bizsystems.com

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

