v1toko/dgad

DGA Detective - Hunt domains generated by Domain Generation Algorithms to identify malware traffic

---

Hunt domains generated by Domain Generation Algorithms to identify malware traffic

---

All COSSAS projects are hosted on GitLab with a push mirror to GitHub. For issues/contributions check CONTRIBUTING.md

What is it?

Domain generation algorithms (DGAs) are typically used by attackers to create fast changing domains for command & control channels. The DGA detective is able to tell whether a domain is created by such an algorithm or not by using a variety of classification methods such as TCN and LSTM. For example, a domain like wikipedia.com is not generated by an algorithm, whereas ksadjfhlasdkjfsakjdf.com is.

	Domain	Classification
✅	wikipedia.org	OK
❌	ksadjfhlasdkjfsakjdf.com	DGA

More information can be found on cossas-project.org.

Installation

To install the DGA Detective, we recommend using a virtual environment:

# recommended: use a virtual environment
python -m venv .venv
source .venv/bin/activate
pip install dgad

How to use?

The DGA Detective can be used a Python package, through a command line interface or remotely through gRPC.

Python package

import dgad
etc.

CLI

usage: dgad [-h] [--domains [DOMAIN [DOMAIN ...]]] [--model MODEL] [--csv CSV] [-q]

optional arguments:
  -h, --help            show this help message and exit
  --domains [DOMAIN [DOMAIN ...]]
                        space separated list of 1 or more domains you want DGA detective to classify
  --model MODEL         the hdf5 keras model file to pass to the classifier
  --csv CSV             csv file containing the domains to classify. This file must have a column 'domain'. The classification will be stored in the same file under a column
                        'classification'
  -q, --quiet           disables stdout

For example, if you want to classify one or several domains:

# classify one domain
$ dgad --domain wikipedia.org
          domain classification
0  wikipedia.org             ok

# classify several domains
$ dgad --domains wikipedia.org ksadjfhlasdkjfsakjdf.com
                     domain classification
0             wikipedia.org             ok
1  ksadjfhlasdkjfsakjdf.com            DGA

But you can also classify a large list of domains:

# classify from/to a csv file
$ dgad --csv your_csv_file.csv

gRPC

Server

To initialize a DGA Detective server listening on port 50054

# listens by default on port 50054
python dgad/grpc/classifier_server.py

# you can override default logging and port like this
LOG_LEVEL=info LISTENING_PORT=55666 python dgad/grpc/classifier_server.py

Client

A client example is provided at dgad/grpc/classifier_client.py

# you can override default destination host and port like this
GRPC_HOST=x.x.x.x GRPC_PORT=55666 python dgad/grpc/classifier_client.py

Contributing

Contributions to the DGA Detective are highly appreciated and more than welcome. Please read CONTRIBUTING.md for more information about our contributions process.

Setup development environment

To create a development environment to make a contribution, follow these steps:

Requirements

• python >= 3.7
• poetry

Setup

# checkout this repository
git clone [email protected]:cossas/dgad.git
cd dgad

# install project, poetry will spawn a new venv
poetry install

# (optional) install pre-commit hooks
pre-commit install
pre-commit install --hook-type commit-msg

# gRPC code generation
python -m grpc_tools.protoc -I dgad/grpc/protos --python_out=dgad/grpc --grpc_python_out=dgad/grpc dgad/grpc/protos/classification.proto

About

DGA Detective is developed by TNO in the SOCCRATES innovation project. SOCCRATES has received funding from the European Union’s Horizon 2020 Research and Innovation program under Grant Agreement No. 833481.