ipaudit(1)

NAME
ipaudit - IP traffic summarizer

SYNOPSIS
ipaudit -CHLNcefgiolmprstwx INTERFACE[: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 numbers.

OUTPUT
If hosts 105.33.41.107 telnets to 211.117.5.11 this creates 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 output 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

COMMAND LINE OPTIONS

Causes
    ipaudit to ignore configuration file. See section on CONFIGURATION FILE below.

Read configuration info from alternate configuration file.

interface
    Network interface to read data from. If reading multiple interfaces run them together with only a colon : (no spaces) in between, like
       ipaudit eth0:eth1:eth3

-G  Ignore config file. See CONFIGURATION FILE section below.

-g config_file
    Reads configuration from config_file. See CONFIGURATION FILE section below.

-r dumpfile
    Reads network info from dumpfile instead of reading live from network. Such a dumpfile could have been produced by the programs ipaudit , tcpdump or ethereal (http://www.zing.org) among others. 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 dumpfile (see -s option about nlen). Can later be read by ipaudit , tcpdump , ethereal , etc. 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. The option -w- will write packets to standard output where they can then be piped to another program which reads pcap packets. See EXAMPLES section below for an example of sending output from ipaudit to tcpdump and also a second instance of ipaudit.

-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 ip-range[:ip-range[:ip-range[..]]]
    Normally, the two ip address within a line of output are printed in ip sorted order. But if you are monitoring a link between two networks, you might want the addresses of one (local) network to come first on an output line. ip-range is list of ip ranges that defines the local network. Any ip address in this range is considered local and is printed first on the output line. If neither or both ip address belongs to the group of ip-range then they are printed in the default sorted order. There can be many ip-ranges separate by colons. No spaces may appear in the argument. Each ip-range can be either a single ip address such as 127.0.0.23 which indicates a range of one, a partial ip address such as 127.0.5 which indicates a range from 127.0.5.0 to 127.0.5.255, a low and high ip address separate by a hypen (-), and a single ip address, a slash (/) and an integer between 0 and 32 (a "net address") which indicates a network. If you run ipaudit with the debug option (-d) the program will print the entire list of ip ranges, so you can check their values. Here is a list of arguments to -l along with the corresponding range.
       COMMAND: ipaudit -l 137.99.11
       RANGE: 137.99.11.0-137.99.11.255
       COMMAND: ipaudit -l 137.99.11:127.0.5/23
       RANGE: 137.99.11.0-137.99.11.255,127.0.4.0-127.0.5.255
       COMMAND: ipaudit -l 127.1.5.17-127.1.7.131
       RANGE: 127.1.5.17-127.1.7.131 The following 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 ... You can turn off this padding with the -S option.

-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 reasons.

-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 traffic.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 traffic output. The time are in the format HH:MM:SS.SSSS where HH, MM and SS are hours, minutes 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 extensive 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 command).
     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.

-C  Print ICMP type and code information in port field of the sending IP address. By default the port fields are set to zero for all ICMP (and all non-TCP and non-UDP traffic). Note that ICMP type/code data is not like TCP/UDP port data, because each IP address in an IP connection has its own port address. In the ICMP case, the type/code info applies to the entire 'connection', not to just the sender or receiver. However, in ipaudit output the type/code information is placed in the port field of the packet sender when the -C option is used. The type/code fields are each a byte, the port value is assigned is the corresponding two byte value. The following table shows the standard values (taken from TCP/IP Illustrated Vol 1, W.R. Stevens)
        0 Echo reply
      768 Network unreachable
      769 Host unreachable
      770 Protocol unreachable
      771 Port unreachable
      772 Fragmentation needed but don't-fragment bit set
      773 Source route failed
      774 Destination network Unknown
      775 Destination host Unknown
      776 Source host isolated (obsolete)
      777 Destination network administratively prohibited
      777 Destination host administratively prohibited
      778 Network Unreachable for TOS
      779 Communication administratively prohited by filtering
      780 Host precedence Violation
      781 Precedence cutoff in effect
     1024 Source quench
     1280 Redirect for network
     1281 Redirect for host
     1282 Redirect for type-of-service and network
     1283 Redirect for type-of-service and host
     2048 Echo request
     2304 Router advertisement
     2560 Router solicitation
     2816 Time-to-live equals 0 during transit
     2817 Time-to-live equals 0 during reassembly
     3072 IP header bad
     3073 Required option missing
     3328 Time stamp request
     3584 Time stamp reply
     3840 Information request (obsolete)
     4096 Information reply (obsolete)
     4352 Address mask request
     4608 Address mask reply

-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, protocol 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 conditions 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 program starts. Each slot can hold multiple connections, and storage and retrieval become inefficient when there are too few slots. You can control the number of slots with this option. The default number of slots (typically 1,000,000) is printed when the -v option is given.

-M  See discussion below READING MULTIPLE NETWORK INTERFACES. The -M option turns off ipaudit removal of duplicate packets.

-S  By default ipaudit pads the ip addresses with leading zeroes, for example
       128.010.223.005 This option tells ipaudit to print ip addresses without leading zeroes,
       128.10.223.5

CONFIGURATION FILE
In addition to command line options you can use a configuration file. When IPAUDIT starts it first looks for a file named "ipaudit.conf" in the current directory, then in the home directory. You can also give the '-g' (see COMMAND LINE OPTIONS above) to specify a configuration file. The configuration can contain comments beginning with #. The options in the config file are specified by keyword/value pairs. For example, to configure ipaudit to write the time information for each connection the option is
   writetime on In keyword is 'writetime' and the option is 'on'. Many options are either ON/OFF. The words TRUE, YES and OK are synonymous with ON. Any other word means OFF. Other options require one or more values, for example
   interface eth0 eth1 tells ipaudit to read interfaces eth0 and eth1. Below is a list of config file options:

interface i1 [i2] [i3]
    List interface(s) to read packets from.

ethernet {on/off}
    Like -e option, prints ethernet addresses on each connection written. Default is off.

writetime {on/off}
    Like -t option, writes times with connection data.

promisc {on/off}
    Like -m option, puts interface(s) in promiscuous mode if on. Default is on.

icmptype {on/off}
    Like -C option, writes ICMP type and code information in port field of the sending IP address.

hostonly {on/off}
    Like -H option, Save and write information only for host pairs, not for "connections", host pairs, protocols and ports.

hostip ip
    Like -I option, tells ipaudit to write *all* packets (the first length bytes as set by -s or packetlen options) for the host ip, regardless of the setting for -p or saveport options.

hostportlimit hostportlimit hostlimit
    Like -L option, sets limit for number of unique host-pair/protocol/port connections, and a separate limit for the number of unique host-pair connections.

hashslots nslots
    Like the -N option, sets the number of slots in the hash table used by ipaudit.

filter bpf_filter
    Like -f option, specifies bpf filter.

progfile program_name
    Like -x option, gives program name to run after ipaudit completes.

pidfile file_name
    Like -i option, write out file with process id.

readfile file_name
    Like -r option, gives name of pcap packet capture file to be read.

writefile file_name
    Like -w option, gives name of pcap packet capture file to write.

savefile file_name
    Like -w option, synonymous with the writefile config file option above.

outfile file_name
    Like -o option, name of output file for ipaudit output

count packet_limit
    Like -c option, maximum number of packets to read.

saveport protocol>[,port[,port]..][:<protocol[,port[,port]..]]..
    Like -p option, limits which protocols/ports packets must have to be saved with writefile(savefile) option.

packetlen length
    Like -s option, maximum number of bytes saved for each packet.

localrange ip_range
    Like -l option, determines which range(s) of ip addresses are considered local when writing ipaudit output.

shortip
    Like -S option, prints ip addresses without leading 0s.

allowduplicate
    Like -M option, turns off duplicate packet detection used when reading multiple interfaces.

READING MULTIPLE NETWORK INTERFACES
ipaudit has the ability to read network data from more than one i network interface at a time. You can specify multiple interfaces on the command line such as
   ipaudit -t eth0:eth1 with the interface names separated by colons (:). Also, in the config file you use the interface option such as
   interface eth0 eth1 There are some details to consider when monitoring multiple interfaces. In particular there is the issue of double counting packets that travel between interfaces. Consider the following example. Suppose you have a router with four interfaces A, B, C and D. Interface A connects to the Internet. Interfaces B, C and D connect to three separate internal networks called Net-B, Net-C and Net-D. If Net-B sends a packet to Net-C it will be seen twice. Once as it travels into the router through interface B, and a second time when it travels out of the router through interface C. If ipaudit simply recorded every packet on every interface, it would have two copies of every packet that travels between B and C. Similarly they would also be two copies of every packet sent between B and D and between C and D. This is a problem which ipaudit attempts to solve. The solution is to record the interface for the first packet of each connection. Then, subsequent packets for this connection are recorded only if they are read from the same interface. In this way duplicate packets are ignored. This technique should work fine under normal circumstances, but it fails when the hostportlimit is reached (see discussion about the -L option). When the hostportlimit is reached ipaudit stops recording ip addresses. In order to save memory it sets all ip address to 0.0.0.0. The correct ip address is needed to successfully remove duplicate packet information. When this information is lost many different connections are stored together, making it impossible to remove duplicate packets by noting which interface they were read from. If you wish, you can run ipaudit without removing duplicate packets with the -M option.

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 process 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.

ipaudit -w- -oipaudit.out eth0:eth1 | tcpdump -r- -wtest.cap port 23 or port 111 or net 10.1.4
    Reads data from interfaces eth0 and eth0 while writing output to ipaudit.out. In addition raw packets are sent to standard out (-w- option) and are piped to tcpdump. The trick here is that tcpdump is used to write raw packets instead of ipaudit. The advantage is that tcpdump offers finer control than ipaudit's -p option over what packets are written to the capture file. In this example it is necessary to write the ipaudit output directly to file instead of to standard out (the default) so as not to interfere with the packets written to standard out. You could also use the BPF filters called by ipaudit to accomplish the same thing, ipaudit -w- -oipaudit.out eth0:eth1 | ipaudit -r- -wtest.cap -f 'port 23 or port 111 or net 10.1.4'

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, protocol 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 received 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
Sometimes under Linux when reading lo and eth0 interfaces simultaneously packets on the lo interface are dropped. If a non-existant interface is specified then ipaudit refuses to read *any* interface and gives no error message. 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.95 Jan 19, 2001

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