Content-type: text/html Manpage of ipaudit

ipaudit

Section: User Commands (1)
Updated: 2 May 2000
Index Return to Main Contents

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

OPTIONS

interface

Network interface to read data from.

-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). 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 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 output 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 neither 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 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.

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

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.

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

This document was created by man2html, using the manual pages.
Time: 16:14:28 GMT, June 20, 2000