ddosclearinghouse/dissector
DDoS Dissector of the DDoS Clearing House - generates DDoS fingerprints from traffic captures
Image
0
988
ddosclearinghouse/dissector repository overview
View on GitHub
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.
- Pull the docker image from docker hub:
docker pull ddosclearinghouse/dissector - Run dissector in a docker container:
Note: We bind-mount the config file with DDoS-DB and MISP tokens to
docker run -i --network="host" \ --mount type=bind,source=/abs-path/to/config.ini,target=/etc/config.ini \ -v /abs-path/to/data:/data \ ddosclearinghouse/dissector -f /data/capture_file [options]/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 inyour-data-volume/fingerprints
Option 2: Installed locally
-
Install the dependencies to read PCAPs (tshark) and Flows (nfdump):
-
Clone the Dissector repository
git clone https://github.com/ddos-clearing-house/ddos_dissector; cd ddos_dissector; -
[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.txtconda create -n dissector python=3.10 conda activate dissector pip install -r requirements.txt -
Get a traffic capture file to be analized (PCAP files should have the
.pcapextension, Flows should have the.nfdumpextension) -
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] [--noverify] [--debug] [--show-target]
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 concurrently read PCAPs (default is the number of CPU cores)
--target TARGET Optional: target IP address or subnet of this attack
--ddosdb Optional: directly upload fingerprint to DDoS-DB
--misp Optional: directly upload fingerprint to MISP
--noverify Optional: Don't verify TLS certificates
--debug Optional: show debug messages
--show-target Optional: Do NOT anonymize the target IP address / network in the fingerprint
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
This project has received funding from the European Union's Horizon 2020
reseach and innovation program under grant agreement no. 830927.
Tag summary
Content type
Image
Digest
sha256:6478b43bb…
Size
378.4 MB
Last updated
over 2 years ago
docker pull ddosclearinghouse/dissector