ipaudit(1)					       ipaudit(1)


NAME
       ipaudit - IP traffic summarizer


SYNOPSIS
       ipaudit -HLNcefiolmprstwx <interface>


DESCRIPTION
       ipaudit is an IP traffic monitor.  It listens to a network
       interface in promiscuous mode (or  reads	 data  previously
       dumped  to a file) and tallies the total traffic for every
       "connection".  A connection is a combination of ip address
       pairs,  protocol and for tcp/udp protocols, the ports num-
       bers.


OUTPUT
       If hosts 105.33.41.107 telnets to 211.117.5.11  this  cre-
       ates  a	single	connection.  ipaudit will tally the total
       bytes of traffic and total packet count in each	direction
       between the two hosts.

       When  ipaudit reports its findings, this telnet connection
       will be listed as

       105.033.041.107 211.117.005.011 6 1105 23 19934 2993 41 33

       The columns are (1) host 1 ip (2) host 2 ip, (3) protocol,
       (4) host 1 port,	 (5)  host  2  port,  (6)  host	 1  bytes
       received,  (7)  host  2 bytes received, (8) host 1 packets
       received, (9) host 2 packets received.

       For protocol other then tcp/udp where there are no  ports,
       the  port  numbers  are set to 0 in the output.	Note that
       the host ip octets are padded on the left with 0 to make 3
       digits.	This help make the output more readable.

       As  another  example,  if the first host now sends 10 ping
       packets to a non-existent host 105.33.41.188 then it  will
       be reported as an output line

       105.033.041.107 105.033.041.188 1 0 0 0 680 0 10

       This says that address 105.33.41.188 received 680 bytes in
       10 packets of protocol 1 - even though there  is	 no  such
       address!

       The  output  is extended using the options.  The -t option
       adds the connection starting and ending times to each out-
       put line, for example

       105.033.041.107 211.117.005.011 6 1105 23 19934 2993 41 33
       14:01:32.0495 14:04:23.9491 2 1

       The -e option adds the ethernet address for the two  hosts
       to each output line,

       105.033.041.107 211.117.005.011 6 1105 23 19934 2993 41 33
       005000c0fa45 005000d1cc21



OPTIONS
       interface
	      Network interface to read data from.


       -r <dumpfile>
	      Reads network info from <dumpfile> instead of read-
	      ing  live from network.  Such a dumpfile could have
	      been produced by the programs ipaudit , tcpdump  or
	      ethereal	(http://www.zing.org).	You can read from
	      standard input using '-' as the file name.


       -c <npacket>
	      Terminate program after reading <npacket>	 packets.


       -w <dumpfile>
	      Writes  first  nlen bytes of every packet to <dump-
	      file> (see -s option about  nlen).   Can	later  be
	      read  by	ipaudit	 ,  tcpdump or ethereal .  The -w
	      option does not affect traffic analysis -	 it  will
	      still  take  place.   By default this writes ALL of
	      the packets to the file.	 Use  the  -p  option  to
	      write  traffic  for  specific  protocols	and ports
	      only.  However the -p option does not affect normal
	      output,  all  packets  are still logged and stored.
	      Contrast this with the -f option.


       -p prot[,port..][:prot[,port..]..
	      Only  dump  packets  with	 specific  protocols  and
	      ports.   For  example,  -p1:6:17 dumps only packets
	      with protocols 1 (icmp),	6  (tcp)  and  17  (udp).
	      You can also break down udp and tcp packets by port
	      numbers - for example -p1:6,21,23	 will  only  dump
	      icmp packets, ftp packets (protocol 6, port 21) and
	      telnet packets (protocol 6, port 23).


       -s <nlen>
	      Save  no	more  than  first  <nlen>  packet  bytes.
	      Default is 96, minimum is 68.

       -i <pidfile>
	      Save  the program process id to <pidfile>.  This is
	      used to terminate program execution  when	 sampling
	      time has expired.	 Use command like

	      kill -2 `cat <pidfile>`

	      to  signal  ipaudit to stop.  Once ipaudit receives
	      this signal, it will print a list of  traffic  that
	      it has seen.


       -l <local-ip>
	      Normally,	 the two ip address within a line of out-
	      put are in sorted order.	But if you are monitoring
	      a	 link  between	two  networks, you might want the
	      addresses of one network to come first on an output
	      line.   <local-ip> is the partial ip address of the
	      network which is listed first on the line.  If nei-
	      ther  ip address belongs to the group of <local-ip>
	      then they are printed in sorted order.

	      For example,

	      ipaudit -c 10000 -l 137.11 eth0

	      will tally 10,000 packets and list the results  on-
	      screen,  placing ip addresses beginning with 137.11
	      first on each output line.  Note that ipaudit  pads
	      the  bytes  with	leading zeros, so that the output
	      will actually start like

	      137.011.nnn.nnn ...


       -m     Does not turn on promiscuous mode on interface.  By
	      default  promiscuous  mode  is  enabled.	Note that
	      interface may be in promiscuous mode for other rea-
	      sons.


       -x <program>
	      After  ipaudit ends, either from receiving a signal
	      or reaching its  packet  limit  (-c  option),  call
	      <program>.   This	 option	 is  intend  for  calling
	      reports scripts which  read  ipaudit  output  after
	      completion.   You	 can send at most one argument to
	      this program, for example

	      ipaudit -c 10000 -x 'report traffic.out'	-o  traf-
	      fic.out eth0

	      runs ipaudit for 10,000 steps, places the output in
	      the file traffic.out, and then  calls  the  program
	      'report'	with the argument 'traffic.out' - telling
	      'report' where to find its input file.

	      Note that to  send  an  argument	'traffic.out'  to
	      'report' we needed to enclose both options together
	      in a single pair of quotes.  Without the quotes  -x
	      would  think  that we were running 'report' without
	      an option (and, the  option  traffic.out	would  be
	      interpreted as the network interface - not what you
	      wanted at all).



       -o <outfile>
	      Writes traffic list to <outfile>	upon  completion.
	      By default, it writes traffic to stdout.


       -t     Adds packets connection times to each line of traf-
	      fic  output.   The   time	  are	in   the   format
	      HH:MM:SS.SSSS  where  HH, MM and SS are hours, min-
	      utes and seconds (to a precision of 1/10,000).  The
	      first  (second)  time  is the time the first (last)
	      packet in the connection	was  detected.	 This  is
	      followed	by  two	 integers  between  1 and 2.  The
	      first (second) integer is the source machine of the
	      first  packet  (second)  packet.	A 1 (2) means the
	      first (second) ip	 address  on  the  line	 was  the
	      source.


       -b     Write traffic list in binary format (experimental).


       -e     Write ethernet addresses for  each  host.	  Program
	      stops with an error if you are using a non-ethernet
	      interface.


       -f     Filter incoming packets according to filter string.
	      For example,

		 ipaudit -f "host 137.99.17.17" eth0

	      will  pass  the  string  "host 137.99.17.17" to the
	      pcap library's filter routine.  Thus  ipaudit  will
	      only  see	 packets  with 137.99.17.17 in one of the
	      two ip addresses.	 The filter commands  are  exten-
	      sive  and	 are  explained	 fully in the tcpdump man
	      page.

	      Note that the -f command is different from  the  -p
	      command.	 The  -f  command  filters packets before
	      ipaudit reads them.  Thus -f affects what is stored
	      in  the  normal output (directed by the -o command)
	      AND in the packet dump (directed	by  the	 -w  com-
	      mand).
	       The  -p command filter packets after ipaudit reads
	      them, but before it writes them to the  dump  file.
	      Thus  the	 normal	 output (-o) is not affected, but
	      the packet dump (-w) is.


       -H     Store host IPs only.  On output  the  protocol  and
	      port fields will be set to zero.


       -L hostportlimit, hostlimit
	      Normally information is stored for every connection
	      , which is a combination of host ip addresses, pro-
	      tocol  and  ports.   Sometimes  the traffic that is
	      monitored will have a large number of  connections,
	      for  example  when scans are taking place where the
	      ports  numbers  change  repeatedly.   hostportlimit
	      sets  a  limit  on the number of connections stored
	      with unique port	addresses.   Otherwise	ipaudit's
	      hash table can overflow memory.  When this limit is
	      exceeded, ipaudit will set all ports  to	zero  and
	      store only host ips and protocols.  Under some con-
	      ditions even this precaution  is	not  enough,  for
	      example when a Denial of Service attack where every
	      packet has  a  unique  forged  source  ip	 address.
	      hostlimit sets a limit on the number of unique host
	      pairs  which  are	 stored.   When	 this  limit   is
	      exceeded	then  every host ip is stored as 0.0.0.0.
	      Only the protocol number will remain unchanged.

	      By default there is no hostportlimit or  hostlimit.
	      You might want to set these limits.  If so set them
	      larger than your typical connection count.  In  our
	      case  the	 connection  count  never  exceeds 200000
	      unless  there  is	 a  DoS	  attack.    The   option
	      -L500000,100000 works for us.


       -N <n_hash_slots>
	      ipaudit  stores  connections  in a hash table.  The
	      number of slots in this table is set when the  pro-
	      gram  starts.   Each slot can hold multiple connec-
	      tions, and storage and retrieval become inefficient
	      when  there are too few slots.  You can control the
	      number of slots with this option.	 The default num-
	      ber  of slots (typically 1,000,000) is printed when
	      the -v option is given.

EXAMPLES
       ipaudit -w dump.fil -p1:2:6,21,23 eth0

	      This runs tells ipaudit to write all packet  header
	      for  icmp,  telnet, and ftp to dump.fil and to read
	      traffic from the network interface  eth0.	  ipaudit
	      will  continue  to run until it is interrupted with
	      control-C or the kill command,  at  which	 time  it
	      will list on the terminal a summary of traffic that
	      it saw.


       ipaudit -i ipaudit.pid -o traffic.out le0

	      Read traffic from interface le0 and  place  in  the
	      file  traffic.out when program completes.	 The pro-
	      cess id number is written	 to  ipaudit.pid  at  the
	      program start.  Thus you can terminate ipaudit with
	      the command kill -2 `cat ipaudit.pid`


       ipaudit -c 50000 eth0 > traffic.out

	      Read 50,000 packets  of  traffic	from  eth0,  pipe
	      default stdout output into file traffic.out.


EXAMPLE OUTPUT
       without -t option
	 192.051.201.068 192.051.201.076 6 2076 139  0 58 0 1
	 192.051.201.001 224.000.000.009 17 520 520  0 1092 0 2
	 192.051.091.021 192.051.091.127 17 138 138  0 243 0 1
	 192.051.221.242 192.051.221.255 17 138 138  0 248 0 1
	 192.051.201.021 192.051.201.070 17 123 123  180 180 2 2

       Columns	are ip address for first (second) machine, proto-
       col number (1 is icmp, 6 is tcp, 17 is udp), udp/tcp ports
       on  first  (second)  machine  (set  to  0  if protocol not
       udp/tcp), bytes received by first (second) machine, number
       of packets recevied by first (second) machine.


       with -t option
	 192.051.201.068  192.051.201.076  6  2076  139	 0 58 0 1
       13:38:59.8229 13:38:59.8229 1 1
	 192.051.201.001 224.000.000.009 17 520 520 0  1092  0	2
       13:38:59.1435 13:38:59.9248 1 1
	 192.051.091.021  192.051.091.127  17  138  138 0 243 0 1
       13:38:56.5373 13:38:56.5373 1 1
	 192.051.221.242 192.051.221.255 17 138 138  0	248  0	1
       13:38:54.7191 13:38:54.7191 1 1
	 192.051.201.021  192.051.201.070  17 123 123 180 180 2 2
       13:38:54.6649 13:38:57.5350 2 1


       As above but with the addition of time  the  first  (last)
       packet  was detected, and the machine which sent the first
       (last) packet.



BUGS
       Hash table size is fixed at run-time.  Would  be	 nice  to
       have dynamically adjusted hash table size.

       Report any bugs to jon.rifkin@uconn.edu.	 If possible, run
       with -d option and email output.	 Thanks.


AUTHOR
       j rifkin <jon.rifkin@uconn.edu>
       http://www.sp.uconn.edu/~jrifkin


VERSION
       0.92 June 20, 2000


SEE ALSO
       ipstrings(1) total(1) tcpdump(1) pcap(3)
































ipaudit 0.92		    2 May 2000				7


