Repository of hystck framework as submitted to IFIP ICDF 11.9 2020
Hystck is a tool that aims towards the automatic generation of traffic through multiple applications. Supported applications include Firefox, Thunderbird, Pidgin and a variety of botnet attacks. There are further applications hystck can emulate user input for, but they are of little interest for the generation of network traffic.
There are different categories of outputs:
- notset
- debug
- info
- warning
- error
- critical
For info there are different starting symbols describing different actions:
- [i] means: Information; May mean, that a function is not fully implemented yet.
- [~] means: Task started and in progress.
- [+] means: Task successfully ended.
- means: There have been errors and the program has been terminated.
Ready compiled html version of the documentation can be found in docs/build. The wiki attached to this repository also contains all information needed to install and run hystck and will be updated and maintained alongside the Sphinx documentation.
The documentation can be found in docs/src/. As the folder name suggests this only contains the source
files of the documentation. In order to get it in readable format you need to install sphinx and inside the folder
run the command make html. After this you will find the newest documentation in HTML format in the subfolder
_build/html. Just open the index.html with the browser of your choosing.
[1] http://www.sphinx-doc.org/en/master/# for documentation pip install -U Sphinx for installation
The partially automated installation requires just a few steps to set up the host components of hystck.
First, make sure the name of the user and your chosen paths for the virtual machine data, the location of your cloned hystck repository and the path to your tcpdump binary you want to install hystck on is correctly configured in config.json This is important, since the setup script later adds this user to the libvirtd-group, which is required to create clones of the virtual guest machines.
A new user can be added with the following command:
$ sudo adduser hystck
If you want to install hystck on a new user, please create that user before running any part of the installation process. Additionally, it is imperative to give the new user root permissions as the installation script has to be called with sudo.
$ sudo usermod -a -G sudo hystck
In these two examples replace hystck with a username of your choice. Make sure it matches the username in config.json. You will also need to make several other adjustments, most importantly allowing you new user to access GUI functionalities. An easy way to do so is editing the .bashrc file by adding export DISPLAY=:0 (NOTE: You may need to add a different value - check before altering your .bashrc file.). Then run xauth, exit the console session, call xhost + and switch to your chosen new user. This is one of multiple ways of allowing GUI functions for a new user.
NOTE: Please adjust the username and ID in config.json, hystck-pool.xml and backing-pool.xml.
To run the following commands, you will need to download hystck now. Hystck can be found here: Github link. Clone or download the repository and navigate into /install_tools.
In this folder, you will find a shell script called linux_installation.sh. To install the further parts of hystck's host component, run the script initially without root privileges (you will be asked to enter your password once the script starts) and choose h when the console prompts you to make a choice. The script will then install all necessary packages including the appropriate Python version.
$ ./linux_installation.sh
Please choose if this installation is host (h) or guest (g) side installation:
Selection: h
...
The first step in creating your virtual Windows 10 guest is creating the virtual machine. To do this, you will need to obtain a Windows 10 image. We recommend downloading an ISO-file from an official source.
Next, you need to set up the virtual machine. While this can be done via the graphical interface of the virt-manager, we recommend running the win10install.sh install script found in the install_tools folder
$ sudo ./win10install.sh path/to/isofile
or simply copying the command seen below:
$ virt-install --name windows-template \
--ram 4096 \
--vcpus sockets=1,cores=2,threads=1 \
--disk pool=hystck-pool,bus=sata,size=40,format=qcow2 \
--cdrom /home/hystck/Win10_1903_V1_German_x64.iso \
--network network=public \
--network network=private \
--graphics spice,listen=0.0.0.0 \
--noautoconsole \
-v
$ sudo chown [user] [path-to-pool]windows-template.qcow2
Either method would require you to adapt the --cdrom parameter with the correct path and name of your installation medium. You might also want to change --ram, disk space (size) or --vcpus depending on your available resources. When starting the virtual machine, make sure to name your primary user hystck. Additionally, it is important not to set a password when first starting the guest component. Otherwise, hystck will be unable to log into the default chosen user. If, for any reason the auto login does not work with your Windows 10 guest component, this link should guide you through the process of (re-)enabling auto login.
While most of the installation of the Windows guest can be automated, a few steps have to be done manually.
First and foremost, hystck has to be downloaded and moved or copied to your desktop. It can be found here.
Next, you simply have to run install.bat with admin privileges. It is located in the install_tools folder. This will install two .msi files located in the same folder.
The first step in creating your virtual Ubuntu guest is creating the virtual machine. To do this, you will need to obtain a Ubuntu image. We recommend downloading an ISO-file from an official source.
Although we recommend Ubuntu 19.10, you can use other versions as well - the installation process should remain the same.
Next, you need to set up the virtual machine. While this can be done via the graphical interface of the virt-manager, we recommend running the ubuntu19.10install.sh install script found in the install_tools folder
$ sudo ./ubuntu19.10install.sh path/to/isofile
or simply copying the command seen below:
$ virt-install --name linux-template \
--ram 4096 \
--vcpus sockets=1,cores=2,threads=1 \
--disk pool=hystck-pool,bus=sata,size=40,format=qcow2 \
--cdrom /home/hystck/ubuntu-19.10-desktop-amd64.iso \
--network network=public \
--network network=private \
--graphics spice,listen=0.0.0.0 \
--noautoconsole \
-v
$ sudo chown [user] [path-to-pool]linux-template.qcow2
Either method would require you to adapt the --cdrom parameter with the correct path and name of your installation medium. You might also want to change --ram or --vcpus depending on your available resources. When starting the virtual machine, make sure to name your primary user hystck. During your initial setup, you will be asked for your user credentials. On this screen, it is important to choose the option Log in automatically. This is required for hystck, so no manual user inputs are needed on the guest side when synthesizing traffic. If your auto login does not work, this guide will help you activate it after setting up your host machine.
Once you are able to start the virtual machine and the OS has been installed and initialized, you should eject the installation medium.
The automated installation for a guest running Ubuntu is similar to the installation of the host machine described in the host chapter.
First and foremost, hystck has to be downloaded and moved or copied to your desktop. It can be found here.
Next, you will want to install all applications used to generate traffic. Both Firefox and Thunderbird are the default mail and browsing applications used by hystck.
After hystck has been downloaded and your traffic generating application have been installed, simply navigate into install_tools and run linux_installation.sh and choose the option for the guest installation. You will be asked to enter your password as root privileges are required for parts of the installation. Do not execute the entire script as root (with sudo).
$ ./linux_installation.sh
Please choose if this installation is host (h) or guest (g) side installation:
Selection: g
...
This will install Python and then run the pre_setup.py with the vm parameter to start installing all necessary python modules.
A more in-depth explanation of the installation can be found here.