Skip to content

traceanon

Jump to bottom
Shane Alcock edited this page Jul 1, 2019 · 5 revisions

traceanon is a libtrace tool that anonymises the IP addresses found in the IP and ICMP headers of packets within a trace. It will also updates the checksums of packets inside the TCP and UDP headers.

traceanon can also anonymise sensitive fields withing RADIUS packets, such as usernames, password hashes and IP addresses.

Usage

    traceanon
            [ -C file | --config file ]
            [ -s | --encrypt-source ]
            [ -d | --encrypt-dest ]
            [ -p prefix | --prefix=prefix ]
            [ -c key | --cryptopan=key ]
            [ -Z method | --compress-type=method ]
            [ -z level | --compress-level=level ]
            [ -t threadcount | --threads=threadcount ]
            sourceuri desturi

Options

-C, --config Read configuration from the provided YAML file.

-s, --encrypt-source deprecated Encrypt source IP addresses.

-d, --encrypt-dest deprecated Encrypt destination IP addresses.

-p, --prefix deprecated Substitute the high bits of the IP addresses with the provided prefix.

-c, --cryptopan deprecated Anonymise IPs using the cryptopan method using the provided key.

-z, --compress-level deprecated Compress the output trace using the given compression level. Compression level can range from 0 (no compression) through to 9. Higher compression levels require more CPU to compress data. Default is no compression.

-Z, --compress-type deprecated Compress the output trace using the given compression algorithm. Options are "gzip", "bzip2", "lzo", "xz" or "none". Default is "none".

-t, --threads deprecated Use threadcount processing threads. Defaults to 4 processing threads. Bear in mind that setting this number too high will decrease performance if there is not enough work to keep all the threads occupied.

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). An example configuration file is given below:

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

The configuration options supported by traceanon are described below...

  • compress_level (top-level)

    sets the compression level for the anonymised output trace file

  • compress_type (top-level)

    sets the compression method used to write the anonymised output trace file (e.g. gzip, bzip2, etc.)

  • threads (top-level)

    set the number of processing threads that are used to read from the input source

  • filterstring (top-level)

    ignore 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', traceanon 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'.

Applications

Anonymising traces using cryptopan (old-style arguments):

    traceanon -Z gzip -z 1 -sd -c "I like bears" erf:unanonymised.erf.gz erf:anonymised.erf.gz

Anonymising traces using prefix substitution (old-style arguments):

    traceanon -Z gzip -z 1 -sd -p 192.168.0.0/16 erf:unanonymised.erf.gz erf:anonymised.erf.gz

Anonymising traces using a config file:

    traceanon -C myconfig.yaml erf:unanonymised.erf.gz pcapfile:anonymised.pcap.gz

Details

Prefix substitution

Prefix substitution is the simpler of the two anonymisation schemes. It works by replacing the prefix of the IP addresses in the trace with the prefix provided on the command line. Obviously, this can result in multiple different IP addresses in the original trace becoming the same IP address in the anonymised trace. As a result, prefix substitution is only useful in certain circumstances and using cryptopan encryption is recommended for regular anonymisation.

Cryptopan encryption

Cryptopan is a prefix preserving encryption scheme based on AES. Under cryptopan, every IP address will map to a unique new IP address and IP addresses within the same subnet will share the same encrypted prefix. Generally, cryptopan is the anonymisation scheme that should be used with traceanon. Cryptopan encryption requires an encryption key that may be up to 32 bytes long and will be padded with NULLs. The same encryption key will produce the same mappings of real IPs to encrypted IPs.

RADIUS encryption

RADIUS encryption is intended to take real-world RADIUS traffic, which often contains private or sensitive information both about network users and the network operational structure, and anonymise it into a trace file that could be safely used in contexts outside of the organisation that runs the network that it came from. An example use case might be testing a RADIUS analysis/parsing program.

To ensure that the anonymised trace is still useful in as many contexts as possible, our encryption method does the following:

  • 'textual' fields (e.g. usernames) are anonymised such that the resulting fields only contain characters from the range [a-zA-Z0-9].
  • 'numeric' fields (e.g. counters) are anonymised such that the resulting fields only contain digits (i.e. they can still be interpreted as numbers.
  • by default, fields that we believe to be usually non-sensitive, such as byte usage counters, the service type, the framed protocol, etc., are NOT modified by traceanon. This can be overridden by setting the ignore_safe_avps config option to 'no'. Specifically the AVP types that are not encrypted by default are 6, 7, 40, 41, 42, 43, 46, 47, 48, 55, and 61.

Notes

  • The output trace format does not have to match the input formats, e.g.

     traceanon pcapfile:unanonymised.pcap.gz erf:anon.erf.gz

    will work. This property holds true for all libtrace applications, although format header information can be lost converting from one format to another, e.g. pcap headers have no space to store the ERF rxerror variable.

  • IP addresses within ARP packets are currently not anonymised - this may be added in a future version of libtrace.

  • Currently, we do not support anonymising IP addresses based on packet direction - this may be added in a future version of libtrace.

Clone this wiki locally