
Description

Hostpairs is a Perl script for gathering and aggregating certain types of 
IP information from a ra data stream, and printing this data out is an 
easily human-readable format. The goal is to provide a flexible mechanism 
to easily make a variety of common queries on Argus data without the need
to write a custom script each time. While it provides some of the same 
functionality as ramon and other standard Argus clients, it also provides 
some additional query and output capabilities.

Hostpairs makes no direct use of Argus flow information. Instead, one
specifies 0-2 (optional) sets of hosts and associated ports (using the
-h1/-p1 and -h2/-p2 options), and these sets are matched against the src/dst
and dst/src hosts/ports in ra output regardless of order.  If a given
host/port set is not specified, any host/port will match. 

A filter to pass on to ra can be specified in order to further narrow down
which data is selected for processing.  It is a good idea to specify a filter
of some sort just to limit the amount of data that hostpairs has to process,
since it can take a loooong time to process a large number of Argus records.

The basic usage: Pick values for h1/p1 and h2/p2.  Choose a mode.
Choose output fields, sort fields, and a format for the output for that 
mode (portpair mode uses both hospair and portpair output/sort/formats).
Let 'er rip.

Additional information about options and usage can be found in
the embedded POD documentation and by invoking hostpairs with the -help
option.

Also included with this distribution is 'trace', which is a very simple
program that uses the Net::Argus::HostPairs.pm module and prints out a 
sorted (by time) list of all the hostpair/portpair information for a given
host.  

Installation

The following modules are required:
    -- Net::Argus::Hostpairs  
        Should be included with the hostpairs program
    -- Net::Patricia
        Patricia trie module available from www.cpan.org
    -- Socket, Text::Wrap, Getopt::Long, POSIX
        These should all be part of the standard Perl distribution, and are
        also available from cpan.
        
You may need to change where hostpairs and trace expect the perl5 binary
to be located.

An rarc file with specific options is required.  One that works is
included as "rarc.hostpairs".  Hostpairs also needs to be able to find
the ra binary. See the instructions at the beginning of the hostpairs 
script for details.  The trace program needs similar modifications to
work.

Examples

(Most command-line options can be abbreviated (eg -s_o for -summary_output). 
 Also, see  "hostpairs -help forms" for shortcuts in specifying command-line 
 args)
 
Simplest invocation, using default values for output, sorting and format:

 hostpairs -h -h1 myhost.mydom.com -f 'host myhost.mydom.com' [files]

would produce output like this (where 123.45.67.89 is myhost.mydom.com, and
XXX, etc are IP addresses of hosts that talked to myhost), along with header
information explaining the fields (in this case pkt and byte counts, along
with the number of matching argus records):

123.45.67.89   XXX.XXX.XXX.XXX       11429     7673     686105     698276   35
123.45.67.89   YYY.YYY.YYY.YYY          27        0       2085          0   10

One can also do a more complicated inquiries, and print out additional
types of information:

Who is trying to talk to myhost.mydom.com and on what ports:

 hostpairs -h -h1 myhost.mydom.com -h_output h2_ip,h2_name,h1_pc,h1_portlist \
   -h_sortby h2_pc -h_format '%-15.15s %-20.20s %5.5s\n  Ports: %s\n'       \
   -filter 'host myhost.mydom.com' [files]
 
Top talkers on subnet 123.45.67.0/24 by number of hosts talked to:

 hostpairs -s -h1 123.45.67.0/24 -h_o h1_ip,h1_name,num_peers -h_s num_peers \
    -h_f '15.15s 30.30s 12.12s\n' -filter 'net 123.45.67' [files]

How much data have each of my web servers served:

 hostpairs -s -h1 www1.mydom.com,www2.mydom.com -p1 80,https -s_output \
     h1_name,h1_pkts,h1_bytes -s_sortby h1_name,h1_bytes                     \
     -filter 'tcp and (host www1.mydom.com or host www2.mydom.com)' [files]
     
The host unpatched.victim.com just got broken into.  Who has it been talking
to, in detail:

 trace -h unpatched.victim.com


Bugs

No attempt is made to do anything special with fragments.
While the hostpairs program attempts to do a bit of sanity checking before
passing things on to the module, it won't catch things like format strings
with too few items, etc.

Please send bug reports to cbs@cs.cmu.edu.

