Sign inSign up

nladc/dissector

By nladc

•Updated about 1 year ago

DDoS Dissector of the DDoS Clearing House - generates DDoS fingerprints from traffic captures

Image
0

2.0K

nladc/dissector repository overview

       

⁠View on github⁠


Python GitHub Issues Contributions welcome License Last commit

⁠DDoS Dissector

The Dissector summarizes DDoS attack traffic from stored traffic captures (pcap/flows). The resulting summary is in the form of a DDoS Fingerprint; a JSON file in which the attack's characteristics are described.

⁠How to use the Dissector

⁠Option 1: in Docker

You can run DDoS Dissector in a docker container. This way, you do not have to install dependencies yourself and can start analyzing traffic captures right away. The only requirement is to have Docker⁠ installed and running.

  1. Pull the docker image from docker hub⁠: docker pull ddosclearinghouse/dissector
  2. Run dissector in a docker container: 
    docker run -i --network="host" --env UID=$(id -u) --env GID=$(id -g) \
--mount type=bind,source=/abs-path/to/config.ini,target=/etc/config.ini \
-v /abs-path/to/data:/data \
nladc/dissector -f /data/capture_file [options]
    Note: We bind-mount the config file⁠ with DDoS-DB and MISP tokens to /etc/config.ini, and create a volume mount for the location of capture files. We use the local network to also allow connections to a locally running instance of DDoS-DB or MISP. Fingerprints are saved in your-data-volume/fingerprints

⁠Option 2: Installed locally

  1. Install the dependencies to read PCAPs (either pcap-converter or tshark+tcpdump) and Flows (nfdump):

  2. Clone the Dissector repository

    git clone https://github.com/ddos-clearing-house/ddos_dissector;
cd ddos_dissector;

  3. [Advised] create a python virtual environment or conda environment for the dissector and install the python requirements:

    Venv:

    python -m venv ./python-venv
source python-venv/bin/activate
pip install -r requirements.txt

    Conda⁠:

    conda create -n dissector python=3.10
conda activate dissector
pip install -r requirements.txt

  4. Get a traffic capture file to be analized (PCAP files should have the .pcap extension, Flows should have the .nfdump extension)

  5. Run the dissector:

    python src/main.py -f data/attack_traffic.nfdump --summary

⁠Options

    ____  _                     __            
   / __ \(_)____________  _____/ /_____  _____
  / / / / / ___/ ___/ _ \/ ___/ __/ __ \/ ___/
 / /_/ / (__  |__  )  __/ /__/ /_/ /_/ / /    
/_____/_/____/____/\___/\___/\__/\____/_/     

usage: main.py [-h] -f FILES [FILES ...] [--summary] [--output OUTPUT] [--config CONFIG] [--nprocesses N] [--target TARGET] [--ddosdb]
               [--misp] [--graph] [--noverify] [--show-target] [--tshark] [--debug]

options:
  -h, --help            show this help message and exit
  -f FILES [FILES ...], --file FILES [FILES ...]
                        Path to Flow / PCAP file(s)
  --summary             Optional: print fingerprint without source addresses
  --output OUTPUT       Path to directory in which to save the fingerprint (default: ./fingerprints)
  --config CONFIG       Path to DDoS-DB and/or MISP config file (default: /etc/config.ini)
  --nprocesses N        Number of processes used to read and process PCAPs (default: number of CPU cores (#))
  --target TARGET       Optional: Specify target IP address of this attack (subnet currently unsupported)
  --ddosdb              Optional: Directly upload fingerprint to DDoS-DB
  --misp                Optional: Directly upload fingerprint to MISP
  --graph               Optional: Create graphs of the attack, stored alongside the fingerprint
  --noverify            Optional: Do not verify TLS certificates (accept self-signed certificates)
  --show-target         Optional: Do NOT anonymize the target IP address/network in the fingerprint
  --tshark              Optional: Force use of tshark/tcpdump over pcap-converter, even if it is present
  --debug               Optional: Show debug messages

Example: python src/main.py -f /data/part1.nfdump /data/part2.nfdump --summary --config ./localhost.ini --ddosdb --noverify

⁠DDoS Fingerprint format

⁠Click here⁠

⁠Example Fingerprints

Note: numbers and addresses are fabricated but are inspired by real fingerprints.

(Click to expand) Fingerprint from FLOW data: Multivector attack with LDAP amplification and TCP SYN flood 
{
"attack_vectors": [
  {
    "service": "HTTPS",
    "protocol": "TCP",
    "source_port": 443,
    "fraction_of_attack": 0.21,
    "destination_ports": {
      "443": 1.0
    },
    "tcp_flags": {
      "......S.": 0.704,
      "others": 0.296
    },
    "nr_flows": 7946,
    "nr_packets": 39900000,
    "nr_megabytes": 34530,
    "time_start": "2022-01-30 12:49:09",
    "duration_seconds": 103,
    "source_ips": [
      "75.34.122.98",
      "80.83.200.214",
      "109.2.17.144",
      "22.56.34.108",
      "98.180.25.16",
      ...
    ]
  },
  {
    "service": "LDAP",
    "protocol": "UDP",
    "source_port": 389,
    "fraction_of_attack": 0.79,
    "destination_ports": {
      "8623": 0.837,
      "36844": 0.163
    },
    "tcp_flags": null,
    "nr_flows": 38775,
    "nr_packets": 31365000,
    "nr_megabytes": 101758,
    "time_start": "2022-01-30 12:49:01",
    "duration_seconds": 154,
    "source_ips": [
      "75.34.122.98",
      "80.83.200.214",
      "109.2.17.144",
      "22.56.34.108",
      "98.180.25.16",
      ...
    ]
  }
],
"target": "Anonymous",
"tags": [
  "Amplification attack",
  "Multi-vector attack",
  "TCP",
  "TCP flag attack",
  "UDP"
],
"key": "601fd86e43c004281210cb02d7f6d821",
"time_start": "2022-01-30 12:49:01",
"time_end": "2022-01-30 12:51:35",
"duration_seconds": 154,
"total_flows": 46721,
"total_megabytes": 102897,
"total_packets": 189744000,
"total_ips": 4397,
"avg_bps": 5193740008,
"avg_pps": 960028,
"avg_Bpp": 497
}
(Click to expand) Fingerprint from PCAP data: DNS amplification attack with fragmented packets 
{
  "attack_vectors": [
    {
      "service": "Fragmented IP packets",
      "protocol": "UDP",
      "source_port": 0,
      "fraction_of_attack": null,
      "destination_ports": {
        "0": 1.0
      },
      "tcp_flags": null,
      "nr_packets": 4190,
      "nr_megabytes": 5,
      "time_start": "2013-08-15 01:32:40.901023+02:00",
      "duration_seconds": 0,
      "source_ips": [
        "75.34.122.98",
        "80.83.200.214",
        "109.2.17.144",
        "22.56.34.108",
        "98.180.25.16",
        ...
      ],
      "ethernet_type": {
        "IPv4": 1.0
      },
      "frame_len": {
        "1514": 0.684,
        "693": 0.173,
        "296": 0.057,
        "others": 0.086
      },
      "fragmentation_offset": {
        "0": 0.727,
        "1480": 0.247,
        "others": 0.026
      },
      "ttl": {
        "54": 0.159,
        "57": 0.142,
        "55": 0.123,
        "59": 0.119,
        "others": 0.457
      }
    },
    {
      "service": "DNS",
      "protocol": "UDP",
      "source_port": 53,
      "fraction_of_attack": 0.945,
      "destination_ports": "random",
      "tcp_flags": null,
      "nr_packets": 166750,
      "nr_megabytes": 21,
      "time_start": "2013-08-15 00:56:40.211654+02:00",
      "duration_seconds": 22,
      "source_ips": [
        "75.34.122.98",
        "80.83.200.214",
        "109.2.17.144",
        "22.56.34.108",
        "98.180.25.16",
        ...
      ],
      "ethernet_type": {
        "IPv4": 1.0
      },
      "frame_len": {
        "103": 0.695,
        "87": 0.208,
        "others": 0.097
      },
      "fragmentation_offset": {
        "0": 1.0
      },
      "ttl": {
        "120": 0.1,
        "119": 0.085,
        "121": 0.085,
        "118": 0.07,
        "others": 0.66
      },
      "dns_query_name": {
        "ddostheinter.net": 0.999
      },
      "dns_query_type": {
        "A": 0.999
      }
    }
  ],
  "target": "Anonymous",
  "tags": [
    "Fragmentation attack",
    "Amplification attack",
    "UDP"
  ],
  "key": "2e8c013d61ccaf88a1016828c16b9f0e",
  "time_start": "2013-08-15 00:56:40.211654+02:00",
  "time_end": "2013-08-15 00:57:03.199791+02:00",
  "duration_seconds": 22,
  "total_packets": 176393,
  "total_megabytes": 22,
  "total_ips": 8044,
  "avg_bps": 8039206,
  "avg_pps": 8017,
  "avg_Bpp": 125
}

⁠Acknowledgment

EU Flag This project has received funding from the European Union's Horizon 2020
research and innovation program under grant agreement no. 830927.

Tag summary

Content type

Image

Digest

sha256:8cf5b004a…

Size

262.8 MB

Last updated

about 1 year ago

docker pull nladc/dissector