All COSSAS projects are hosted on GitLab with a push mirror to GitHub. For issues/contributions check CONTRIBUTING.md
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.
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
The DGA Detective can be used a Python package, through a command line interface or remotely through gRPC.
import dgad
etc.
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
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
Contributions to the DGA Detective are highly appreciated and more than welcome. Please read CONTRIBUTING.md for more information about our contributions process.
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
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.