TRACEANON(1)

NAME
traceanon - anonymise ip addresses and other sensitive information in traces

SYNOPSIS
traceanon [ -C configfile | --config=configfile ] sourceuri desturi

DESCRIPTION
traceanon anonymises a trace by replacing IP addresses found in the IP header, and any embedded packets inside an ICMP packet. It also replaces the checksums inside TCP, UDP and ICMPv6 headers with zeroes. Two anonymisation schemes are supported. The first replaces a prefix with another prefix. This can be used to replace a /16 with an equivalent prefix from RFC1918, for instance. The other scheme is cryptopan which is a prefix preserving encryption scheme based on AES (traceanon must be built with libcrypto support to be able to use the cryptopan scheme). traceanon can also anonymise sensitive fields within RADIUS packets, such as usernames, password hashes and IP addresses.

CONFIGURATION
As of libtrace 4.0.8, traceanon can (and should) now be configured using a YAML-formatted file instead of via a series of command-line arguments. Use the -C command line switch to tell traceanon the location of your configuration file. Configuration options in YAML can be expressed at one of three levels: the top level (i.e. no indentation), ipanon (i.e. within an 'ipanon' map) or radius (i.e. within a 'radius' map). See EXAMPLES below for an example configuration file with entries at each level. Options supported by traceanon are:

compress_level (top-level)
    sets the compression level for the anonymised output trace file.
compress_type (top-level)
    sets the compression method for the anonymised output trace file (gzip, bzip2, etc.).
threads (top-level)
    sets the number of processing threads used to read from the input source.
filterstring (top-level)
    ignores all packets that do NOT match the given BPF filter.
encode_addresses (ipanon)
    specifies which addresses should be anonymised within the IP header -- can be one of 'both', 'none', 'source' or 'dest'.
prefix_replace (ipanon)
    specifies the high bits of each anonymised IP address with the given IPv4 prefix. Can only be applied to IPv4 addresses and is mutually exclusive with the 'cryptopan_key' option.
cryptopan_key (ipanon)
    encrypt the IP addresses using the prefix-preserving cryptopan method using the given key. The key can be up to 32 bytes long, and will be padded with NULL characters.
encode_radius (radius)
    if set to yes, will attempt to encrypt any RADIUS traffic that is found within the input trace.
ignore_safe_avps (radius)
    if set to yes, certain RADIUS AVPs that we have deemed to not be sensitive will NOT have their values encrypted. This includes AVPs containing packet and byte counters, service types and framed protocols.
salt (radius)
    sets a salt for the RADIUS encryption process. Salts longer than 32 bytes are truncated to 32 bytes.
server (radius)
    tells traceanon the IP address and port numbers being used by the RADIUS server whose traffic is to be anonymised. The expected format for this option is 'IPaddress,accessport,accountingport'.

OPTIONS
Remember that all options other than -C are now officially deprecated.
-C
--config
    specifies the location of the YAML configuration file.
-s
--encrypt-source
    encrypt only source ip addresses.

-d
--encrypt-dest
    encrypt only destination ip addresses.

-p
--prefix=prefix
    substitute the high bits of the IP addresses with the provided IPv4 prefix. This method will only anonymise IPv4 addresses; IPv6 packets will be untouched.

-c
--cryptopan=key
    encrypt the IP addresses using the prefix-preserving cryptopan method using the key "key". The key can be up to 32 bytes long, and will be padded with NULL characters.

-F
--keyfile=file
    encrypt the IP addresses using the prefix-preserving cryptopan method using the key specified in the file "file". The key must be 32 bytes long. A suitable method of generating a key is by using the command dd to read from /dev/urandom.

-f
--filter=expr
    Discard all packets that do not match the BPF expression specified in 'expr'. Filtering is applied *before* any anonymisation occurs, so IP address filters will attempt to match against the original unencrypted addresses.

-z
--compress-level=level
    compress the output trace using a compression level of "level". Compression level can range from 0 (no compression) through to 9. Higher compression levels require more CPU to compress data. Defaults to no compression.

-Z
--compress-type=method
    compress the output trace using the compression algorithm "method". Possible algorithms are "gz", "bz", "lzo", "xz" and "no". Default is "no".

-t
--threads=threadcount
    use the specified number of threads to anonymise packets. The default number of threads is 4.

EXAMPLES
Given a configuration file that looks like this:
    #------
      ipanon:
        encode_addresses: both
        cryptopan_key: thisisaverysecurekeyforanonpurposes
      radius:
        encode_radius: yes
        ignore_safe_avps: yes
        salt: thisisarandomlygeneratedsalt
        server: 192.168.200.1,1645,1646
      compress_level: 1
      compress_type: gzip
      threads: 1
    #------
We can run traceanon using that configuration as below:
traceanon --config=/path/to/config/file
	erf:/traces/unenc.gz \
	erf:/traces/enc.gz \

BUGS
This software should support encrypting based on the direction/interface flag. IP addresses inside ARP's are not encrypted.

LINKS
More details about traceanon (and libtrace) can be found at https://github.com/LibtraceTeam/libtrace/wiki

SEE ALSO
libtrace(3), tracemerge(1), tracefilter(1), traceconvert(1), tracestats(1), tracesummary(1), tracertstats(1), tracesplit(1), tracesplit_dir(1), tracereport(1), tracepktdump(1), tracediff(1), tracereplay(1), traceends(1), tracetopends(1)

AUTHORS
Perry Lorier <perry@cs.waikato.ac.nz> Shane Alcock <salcock@waikato.ac.nz> Richard Sanger <rjs51@students.waikato.ac.nz>