This repository contains the C++ tools for emulating the real-time DDoS attack detection mechanism proposed within the paper "Offloading Real-time DDoS Attack Detection to Programmable Data Planes" (IM 2019). The P4 description is available at ddosd-p4. These tools serve to enable thorough functional evaluation of the detection mechanism since production performance has not been a design goal of our P4 target. The functional equivalence of both implementation may be verified by comparing the values assumed by the mechanism variables during runtime.

The purpose of each tool is the following:

• ee: emulating the Entropy Estimation unit;
• ercnv: converting a pcap file containing packets with the ddosd_t header (see ddosd-p4) to an execution report text file with the same format as the tcad output;
• lpm: generating the LPM lookup table entries supporting in-network entropy estimation;
• psamp: calculating the entropy of source and destination IP addresses from packet samples;
• tcad: emulating the Traffic Characterization and the Anomaly Detection units;
• trafg: generating workload from legitimate and malicious packet traces.

These instructions will guide you to build and run these tools. We consider an environment running Ubuntu 16.04 LTS.

• git
• CMake 3.12 or higher (see https://launchpad.net/~janisozaur/+archive/ubuntu/cmake-update)
• GNU Make
• A C++11 compiler
• libpcap
• Boost.Algorithm
• Boost.Optional
• Boost.Program_options

For installing all dependencies, run:

sudo apt install git cmake make g++ libpcap-dev libboost-dev libboost-program-options-dev

Use the following commands to build all tools:

git clone https://github.com/aclapolli/ddosd-cpp.git
cd ddosd-cpp
mkdir build
cd build
cmake ..
make

This process creates the binaries within ../bin.

usage: ee [-h] -c <config_filename> <pcap_filename>
general options:
  -h [ --help ]         show this help message and exit
  -c [ --config ] arg   configuration filename

The ee tool reads a JSON configuration file specified with the -coption (check example/ee.json). The following parameters are supported:

• window_size (number): the number of packets in each observation window;
• baseline (boolean): specifies whether to perform an exact calculation of entropy for evaluating the estimation error;
• estimators (object): optional parameter specifying the estimators configuration;
  • repetitions (number): the number of experiment repetitions for each count sketch width and depth levels combination (useful when using random hash coefficients);
  • width_levels (array of numbers): list of count sketch widtdh levels;
  • depth_levels (array of numbers): list of count sketch depth levels;
  • coefficients (array of objects): optional parameter for defining hash coefficients for each depth level (useful when verifying the functional equivalence of the P4 program); if not present, these coefficients are autogenerated randomly;
    • h (object): coefficients for the hash functions h = (a*x + b) mod p;
      • a (array of numbers): list of values for coefficient a;
      • b (array of numbers): list of values for coefficient b;
    • g (object): coefficients for the hash functions g = 2*(((a*x + b) mod p) mod 1) - 1;
      • a (array of numbers): list of values for coefficient a;
      • b (array of numbers): list of values for coefficient b.

This tool emulates several instances of the Entropy Estimation unit processing the packets within the given pcap file. It writes to the standard output stream: the packet timestamp (in milliseconds) of the last packet of each observation window, and the entropy estimates of the source and destination IP addresses.

usage: ercnv [-h] <pcap_filename>
general options:
  -h [ --help ]         show this help message and exit

The er tool takes a pcap file as parameter which must only contain packets having the ddosd_t header. It extracts the values of the mechanism variables as reported by ddosd-p4 and writes them to the standard output stream along with the packets timestamp (in milliseconds).

usage: lpm [-h] -b <bit_precision> -m <max_x> -e <max_error>
general options:
  -h [ --help ]              show this help message and exit
  -b [ --bit-precision ] arg fixed-point representation bit precision
  -m [ --max-x ] arg         LPM lookup table maximum domain value
  -e [ --max-error ] arg     LPM lookup table maximum approximation error 2^max_error

The lpm tool takes three parameters:

• bit_precision (integer): the number of fractional bits for the fixed-point representation of the function image;
• max_x (integer): the upper limit for the function domain (must be at least the number of packets within an observation window);
• max_error (integer): the maximum approximation error when aggregating function domain values (the maximum error is given by 2^max_error).

This tool writes to standard output stream the LPM entries which populate the mechanism lookup table used for entropy estimation.

usage: psamp [-h] -w <window_size> -s <sampling_prob> <pcap_filename>
general options:
  -h [ --help ]              show this help message and exit
  -w [ --window-size ] arg   observation window size
  -s [ --sampling-prob ] arg sampling probability

The psamp tool takes three parameters:

• window_size (integer): the number of packets in each observation window;
• sampling_prob (float): the packet sampling probability;
• pcap_filename (string): a pcap file with the workload packet traces.

This tool writes to standard output stream: the timestamp (in milliseconds) of the last packet of each observation window, and the entropies of the source and destination IP addresses calculated over the packet samples.

usage: tcad [-h] -t <training_length> -s <smoothing_coefficient> -k <sensitivity_coefficient>
general options:
  -h [ --help ]                        show this help message and exit
  -t [ --training-length ] arg         training length (number of windows)
  -s [ --smoothing-coefficient ] arg   smoothing coefficient
  -k [ --sensitivity-coefficient ] arg sensitivity coefficient

The tcad tool takes three parameters:

• training_length (integer): the number of observation windows composing the training phase;
• smoothing_coefficient (double): the smoothing coefficient of the Traffic Characterization units;
• sensitivity_coefficient (double): the sensitivity coefficient of the Anomaly Detection unit.

It reads the entropy estimates as formatted by the ee tool from standard input stream. Therefore, to emulate the whole DDoS attack detection mechanism, one may execute:

ee -c <config_filename> <pcap_filename> | tcad -t <training_length> -s <smoothing_coefficient> -k <sensitivity_coefficient>

The command above writes to the standard output stream:

• The timestamp (in milliseconds) of the last packet of each observation window;
• The entropy estimates of the source and destination IP addresses, their EWMA, and their EWMMD;
• The detection alarm status.

usage: trafg [-h] -n <packet_count> -a <attack_proportion> <legitimate_pcap_filename> <malicious_pcap_filename <output_pcap_filename>
general options:
  -h [ --help ]                  show this help message and exit
  -n [ --packet-count ] arg      packet count
  -a [ --attack-proportion ] arg attack proportion

The trafg tool takes five parameters:

• packet_count: the number of packets composing the detection phase;
• attack_proportion: the proportion of malicious packets within the overall traffic during the attack;
• legitimate_pcap_filename: a pcap file containing packet traces of legitimate traffic;
• malicious_pcap_filename: a pcap file containing packet traces of a DDoS attack;
• output_pcap_filename: the output filename for the workload pcap.

This repository is licensed under the GNU General Public License v3.0 (check LICENSE for details).