heiDGAF - Domain Generation Algorithms Finder

Machine learning-based DNS classifier for detecting Domain Generation Algorithms (DGAs), tunneling, and data exfiltration by malicious actors.
Explore the docs »

View Demo · Report Bug · Request Feature

Continuous Integration

If you want to use heiDGAF, just use the provided Docker compose to quickly bootstrap your environment:

docker compose -f docker/docker-compose.yml up

The following table lists the most important configuration parameters with their default values. The configuration options can be set in the config.yaml in the root directory.

Install all Python requirements:

python -m venv .venv
source .venv/bin/activate

sh install_requirements.sh

Alternatively, you can use pip install and enter all needed requirements individually with -r requirements.*.txt.

Now, you can start each stage, e.g. the inspector:

python src/inspector/main.py

Currently, we enable two trained models, namely XGBoost and RandomForest.

python -m venv .venv
source .venv/bin/activate

pip install -r requirements/requirements.train.txt

For training our models, we rely on the following data sets:

• CICBellDNS2021
• DGTA Benchmark
• DNS Tunneling Queries for Binary Classification
• UMUDGA - University of Murcia Domain Generation Algorithm Dataset
• Real-CyberSecurity-Datasets

However, we compute all feature separately and only rely on the domain and class. Currently, we are only interested in binary classification, thus, the class is either benign or malicious.

(back to top)

loglines:
  fields:
    - [ "timestamp", RegEx, '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$' ]
    - [ "status_code", ListItem, [ "NOERROR", "NXDOMAIN" ], [ "NXDOMAIN" ] ]
    - [ "client_ip", IpAddress ]
    - [ "dns_server_ip", IpAddress ]
    - [ "domain_name", RegEx, '^(?=.{1,253}$)((?!-)[A-Za-z0-9-]{1,63}(?<!-)\.)+[A-Za-z]{2,63}$' ]
    - [ "record_type", ListItem, [ "A", "AAAA" ] ]
    - [ "response_ip", IpAddress ]
    - [ "size", RegEx, '^\d+b$' ]

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

(back to top)

Distributed under the EUPL License. See LICENSE.txt for more information.

(back to top)