Documentation

• Getting the Source
• Using the tool

Getting the Source

In order to check out the code for the current version of the standalone program, you will want to grab an SVN client for your system (using the command-line version in Linux/Unix/Mac OS X is good enough, while TortoiseSVN is often used by people under Windows who do not wish to utilize a command-line client). If you are using the command-line client then issue the command:

svn co https://scrub-tcpdump.svn.sourceforge.net/svnroot/scrub-tcpdump/trunk/scrubtcpdump scrub-tcpdump

This will pull the latest version of the source from the repository. Alternatively, if you are using TortoiseSVN, then you can just check out a new repository into a directory from the same URL as above.

Once the source has been pulled, you need a system with a C compiler (at the current time we only use C and not C++ to maintain compatibility with tcpdump). The system has only been tested with variants of gcc and the make system. It has been compiled on Mac OS X 10.4.10 using the native Xcode compiler and the bash prompt, and also in Linux and on Windows using the Cygwin environment. In all cases, you will need to compile and install libpcap, which is available from the tcpdump website. Build and install that first (if you prefer to use pre-built packages, use the one with the dev build from your available system) and then enter the directory to which you pulled the scrub-tcpdump source and simply issue the command 'make' there. This should produce a binary called 'scrub-tcpdump' which you can then use to anonymize packet captures in libpcap format.

Using the tool

To invoke the tool, one simply has to issue the following command:

scrub-tcpdump <input> <output> [options]
The following two options are required:

-r filename	file to be read, pcap format
-w filename	file to be output, pcap format
The following are options:
-i device	pcap-style device name from which to capture packets
-o "anonymization sting"	string of anonymization options as explained in the next paragraph
-k permutation_key	optional permutation key, only necessary if using keyed randomization
-f BPF_filter_string	filter string for libpcap

The source file needs to be a file in tcpdump/libpcap format, and in a version that is compatible with the version of libpcap against which you have built the tool. The output file will be in libpcap format, also. WARNING: The tool will silently over-write any existing file with the same name as the output file that you specify.

The anonymization options string is composed of a number of options, in any order, selected from the tables below. Its format follows the pattern of <field function> pairs, where the field is one of the designators from table 2 below and the function used to anonymize that field is from table 3 below. They must be paired as per the accepted pairings in Table 1. Errors in pairings will be accepted by the system with undefined results. An explanation of what each function means in the context of each field follows table 3. There will always be an even number of options in this string, the first indicating the field to be anonymized and the second the function to use in the anonymization process. For example, to anonymize the source IP address with black marker and all the ports with bilateral classification the anonymization options string should look like:

"srcip bm tcpsrcport bi tcpdstport bi udpsrcport bi udpdstport bi"

and so on. Each of the field designations must be taken from the left-hand column of Table 2 below. The function names must be taken from Table 3 below. It is up to the user to ensure that the combination of field and function makes sense (i.e. that you do not attempt to use bilateral classification on an IP address or prefix-preserving pseudonymization on a timestamp, etc) - pairings that the system supports (although errors will be silently accepted by the system with undefined and probably nefarious effects) are listed in Table 1.

Below you will find a table of all of the fields that scrub-tcpdump anonymizes and the methods that can be used to anonymize that field. After that will be a description of how to specify those options to the tool on the command line.

The following table lists the fields and their field designations for use in the anonymization string for use with scrubtcpdump:

The following contains the names of the anonymization methods and their specifications for the anonymization string. There is also a brief description of what that anonymization method does.