Read Me

The Advanced Network Traffic Analysis Research and Exploration Suite (ANTARES)
is a toolkit for defining and computing flow attributes.  Flow attributes are
values computed from network traffic, and can be used to distinguish between
network flows created by different applications even without examining the
payload of the traffic.

Flow attributes are useful for distinguishing between different uses of the
network, even without using the packet payload, which would be useful in the
fields of network security and administration, among others.  The goal is to be
able to identify, in general, what activity is generating a given flow; for
example, distinguishing traffic generated by a spyware agent sending keylogger
data to its controller over HTTP from that generated by legitimate web surfing,
or distinguishing different classes of traffic for quality-of-service and
congestion control in a network.

The focus of ANTARES is on facilitating the definition of these attributes, so
it provides several powerful mechanisms for this.  Attributes can be defined in
terms of other attributes; e.g. the proportion of small packets in a given
network flow can be defined as the ratio of two counts: the number of packets
meeting a 'small packet' filter over the total number of packets in the flow.
These two counts, and the proportion of small packets itself, could all be used
in definitions of more complex attributes.  It provides several basic classes
for these attributes, and supports the addition of arbitrarily complex custom
attribute classes.

Although other tools exist for analyzing network traffic, such as Wireshark,
Netdude, and NETMATE, few of them support non-payload based attributes to the
extent that ANTARES does, and ANTARES is the only one that allows such
attributes to be defined in terms of each other.  This ability makes it
straightforward and fast for a researcher to define new flow attributes for
experimentation.


INSTALLATION
------------

First unpack the ANTARES toolkit, and set the environment variable ANTARES_HOME
to the root directory of the toolkit:
	tar xvfz ANTARES_xxxxxxxxx.tar.gz
	cd ./antares
	export ANTARES_HOME=`pwd`

ANTARES depends on a few additional libraries.  We explain here how to create
the environment that ANTARES expects.

libpcap with seek patch:
  Evan Hughes has written a patch for libpcap that allows a program to seek
randomly within a pcap file; this functionality is required by the configuration
of the libqcap library used by ANTARES.  The patch is available as
patches/patch_pcap_seek.diff in the ANTARES distribution.  To produce the
required library, follow this procedure:

- Obtain libpcap (preferably the 2005.11.21 snapshot, available at
  http://www.tcpdump.org/weekly/libpcap-2005.11.21.tar.gz), and extract it (for
  our example, we will extract it in $ANTARES_HOME/ so that is creates the
  directory $ANTARES_HOME/libpcap-2005.11.21)
- cd into the top directory of the libpcap distribution (e.g.
  $ANTARES_HOME/libpcap-2005.11.21)
- patch the libpcap distribution:  
  	patch -p1 < $ANTARES_HOME/patches/patch_pcap_seek.diff
- configure the libpcap distribution to install into a subdirectory of the
  ANTARES directory, and with the SEEK modification enabled:
	CFLAGS=-D__PCAP_SEEK_MOD ./configure --prefix=$ANTARES_HOME/libpcap/
- build and install libpcap:
 	make && make install
- if you installed the patched libpcap somewhere other than
  "$ANTARES_HOME/libpcap", create a symbolic link to the installed path from
  there - i.e. such that $ANTARES_HOME/libpcap/include/pcap.h points to the
  pcap.h in the include directory of the patched distribution.  As a test:
	grep pcap_ftell $ANTARES_HOME/libpcap/include/pcap.h
  should return a function declaration.


libqcap:
  ANTARES uses a library named libqcap to do much of the initial packet
processing; that must be built and installed before ANTARES.

- Obtain libqcap (via Subversion from http://qcap.sourceforge.net/, instructions
  from http://sourceforge.net/svn/?group_id=149547), e.g. to $ANTARES_HOME/qcap
  	svn co https://qcap.svn.sourceforge.net/svnroot/qcap qcap
- cd into the top directory, e.g. $ANTARES_HOME/qcap
- patch it to use the modified pcap library:
	patch -p1 < $ANTARES_HOME/patches/patch_qcap.diff
- cd into src/libqcap and build it:
	make
- if you installed qcap somewhere other than $ANTARES_HOME/qcap, create a
  symbolic link from that path to the qcap installation directory.  As a test:
	grep ANTARES_HOME $ANTARES_HOME/qcap/src/libqcap/Makefile
  should return three lines - two CFLAGS variables and an SLIBS variable being
  set.


Once those are taken care of, you can build the ANTARES libraries
	cd $ANTARES_HOME/src
	make

Examples of uses of the library can be found in $ANTARES_HOME/src/testing; note
that at any given time, some of the files in that directory may not compile.