Quick Start

This page provides an overview in how to getting started with ForTrace++, after the successful installation.

Installation of VMs

Note

Please read the instructions in libvirt Tuning.

This section is concerned with the installation of VMs through Virtual Machine Manager. There are other GUI frontends to libvirt available, however they are not discussed in this guide.

Installation of a Windows VM

Installation of a Windows 10 VM

Please install a new VM via Virtual Machine Manager on your host VM. For this scenario we will use a Windows 10 machine. The ISO can be downloaded directly from Microsoft below this Link. Every version of Windows 10 should be compatible to this scenario. Regarding the language, please select ‘English International’ or ‘English (United States)’, since ForTrace++ assumes the OS to be set to English.

  1. Open Virtual Machine Manager

  2. Select ‘Create a new virtual machine’

  3. Select ‘Local install media (ISO image or CDROM)’ > Forward

  4. Enter the path to the downloaded Windows 10 ISO and choose the correct operating system you are installing (this should be done automatically) > Forward

  5. Select a suitable amount of memory and CPUs, for example

    1. Memory: 8192

    2. CPU: 6

  6. Select ‘Create a disk image for the virtual machine’ and allocate at least 40GiB > Forward

  7. Give the VM a meaningful name (should default to ‘win10’). This name is important for later steps. Under ‘Network selection’ make sure the ‘default’ network is selected > Finish

Configuration of Windows and installation of necessary programs

  1. Boot the Windows 10 VM that you have created in the previous step

  2. Complete the general Windows setup, for it is not automated at this moment

    1. You may leave the values for ‘Language to install’ and ‘Time and currency format’, but change the value of ‘Keyboard or input method’ to US

    2. During the windows setup you are asked for a product key. Select ‘I don’t have a product key’

    3. Install the ‘Windows 10 Home’ edition for the two scenarios

    4. Select ‘United States’ for the region and ‘US’ for keyboard layout

    5. Create a local account with the username fortrace and the password fortrace

    NOTE: any other combination of username and password is fine as well but has to be updated in the configuration files of the scenarios

    1. Answer the security questions as you like, since we don’t need them for this scenario

    2. Adjust the privacy setting for your device as you prefer

    3. Skip the ‘customise experience step’

    4. Select Not now in the ‘Let Cortana help you get things done’ screen

  3. Continue with the displayed Microsoft Edge setup

    1. You can sign in with a Google account if you prefer, but you don’t have to do so for these scenarios

    2. For ‘Overall appearance’ just select the default values

    3. On the start page you are greeted with a cookie banner, which you can but don’t have to accept

  4. Disable mouse acceleration

    1. Press ‘meta+r’ to open the Run dialogue

    2. Enter ‘main.cpl’ to open the Mouse Properties

    3. Select the registry card ‘Pointer Options’ and disable the option ‘Enhance pointer precision’

  5. Open ‘Settings’

    1. Open ‘Network & Internet’

    2. Open ‘Properties’ of the active Ethernet connection to the libvirt network

    3. Set the ‘Network Profile’ to Private

  6. Open ‘Settings’

    1. Open ‘System’

    2. Select ‘Notifications & actions’

    3. Disable ‘Get notifications from apps and other senders’

    4. Disable all checkboxes in the screen to stop Windows from nagging you

  7. Due to SeaBIOS limitation: Disable SecureBootEncodeUEFI to suppress CMD popup Source

    1. Open ‘Task Scheduler’

    2. Navigate to ‘Task Scheduler Library\Microsoft\Windows\PI’

    3. Select ‘SecureBootEncodeUEFI’ and click ‘Disable’

  8. Open ‘Settings’

    1. Open ‘Update & Security’

    2. Apply the recent Windows Updates and wait for all of them to be downloaded

    It is the best to make sure all updates are applied before the snapshot is taken so the VM does not start to behave strangely

    1. Most likely it will be necessary to perform a restart, hence hit ‘Update and restart’

  9. Power off the VM and create a snapshot (once the VM is off)

    1. Select ‘Manage VM snapshots’ (located in second ribbon)

    2. Select the ‘+’ symbol to create a new snapshot and give it the name ‘init_setup’.

    Like the VM name, the snapshot name is important for the execution of the scenario

Installation of a Windows 11 VM

Follow this guide to install a Windows 11 VM, with a local account, and optimize it.

Installation of a Linux VM

Interaction with ForTrace++

There are two major approaches to interact with ForTrace++: the programmatic approach or the interaction through the Generator component.

Programmatic

This approach relies on the API offered through ForTrace++.

Non-Programmatic

  • Generator with YAML files

YAML Configuration Files

The YAML configuration files can and should be used to configure existing scenarios that are using the ForTrace++ API. Hence, it is possible to generate slightly different datasets without the need to write extra code. When creating new scenarios, programmers are encouraged to supply said configuration files and offer the possibility to make changes to their scenario through a configuration file.

The general layout of a ForTrace++ YAML configuration file

Root configuration

Since configuration files are used VM-centric, meaning one configuration is used to control one VM, another kind of configuration file is necessary to enable scenarios with multiple VMs: the root configuration file.

This kind of configuration can be identified by looking at the domain entry of the file:

1domain:
2  - "<Path_to_another_yaml_file>"
3  - "<Path_to_another_yaml_file>"

Domain Section

A normal, non-root YAML configuration of ForTrace++ is domain-centric. Thus, the domain section contains the most general and relevant information to interact with a domain. The configuration below is taken from the first Linux example.

 1domain:
 2  username: "kali"
 3  password: "kali"
 4  name: "kali"
 5  network: "default"
 6  os_type: OSType.LINUX
 7  shell_type: ShellType.ZSH
 8  package_manager: PackageManager.APT
 9  desktop_environment: DesktopEnvironmentType.GNOME
10  start_sniffer: False
11  snapshot: "clean-install"
12  dump_ram: False
13  dump_images: False

  • username: Name of the main user of the system. This name will be used to perform the installation of any required software.

  • password: Password of the main user

  • name: Name of the VM to be booted

  • network: Name of the network the VM should be bound to. It might be None, so the VM is not connected to any network

  • os_type: Expected operating system type. See fortrace.utility.distribution_constants.OSType for all supported types. Use full qualified names, e.g., OSType.Linux

  • shell_type: This feature is mainly Linux/macOS specific and is used to define the type of the shell that is opened when establishing a shell connection via virsh. Please check which login shell is used by your distribution. See fortrace.utility.distribution_constants.ShellType for all supported values. Use full qualified names, e.g., ShellType.ZSH

  • package_manager: Package manager to be used for installing packages. See fortrace.utility.distribution_constants.PackageManager for all supported types. Use full qualified names, e.g., PackageManager.APT

  • desktop_environment: Desktop environment of the domain. Omit this line when dealing with domain without one. See fortrace.utility.distribution_constants.DesktopEnvironmentType for all supported types. Use full qualified names, e.g., DesktopEnvironmentType.GNOME

  • start_sniffer: Can either be True or False and determines whether the network traffic of this domain is captured with dumpcap. Please make sure it is installed and correctly configured as described in the Installation instructions.

  • snapshot: Specify a snapshot from which the guest should be booted. If the snapshot does not exist, it will be created from the current state of the guest and is available for future iterations.

  • dump_ram: Can either be True or False and determines whether ForTrace++ should perform a RAM dump, once the scenario is completed

  • dump_images: Can either be a bool or a list, depending on the configuration of the domain. False or the absence of this parameter means that no image dump should be performed, once the scenario is concluded. If a domain has more than one disk, either a list of disks to be dumped, or True can be specified, where the latter means that all disks of the domain will be dumped. If a list of names is provided, use the ones from the libvirt domain XML file of the domain, found in the disk section, in the target sub-element, named dev (in the snipped below, the disk is named sda).

1<disk type="file" device="disk">
2  <driver name="qemu" type="qcow2" discard="unmap"/>
3  <source file="/var/lib/libvirt/images/win10.qcow2"/>
4  <target dev="sda" bus="sata"/>
5  <address type="drive" controller="0" bus="0" target="0" unit="0"/>
6</disk>

Generator Section

This generator section contains parameters used to configure the semi-random action generator’s behavior.

 1generator:
 2  seed: 1234
 3  action_delta_minimum: 5
 4  action_delta_maximum: 10
 5  actions:
 6    web_browsing:
 7      application: "Firefox"
 8      operations:
 9        - name: "browsing"
10          amount: 30
11          source: c-http-0
12          enable_scraping: True
13        - name: "browsing"
14          amount: 10
15          source: c-http-1
16          enable_scraping: True
17        - name: "download"
18          amount: 10
19          source: c-http-2
20        - name: "web_search"
21          amount: 5
22          source: c-web-search
23          # search_engine: "Google"
24    file_management:
25      application: "Files"
26      operations:
27        - name: 'copy'
28          amount: 5
29          source: web_browsing
30          destination: "/home/kali/Documents"
31        - name: 'to_trash'
32          amount: 5
33          source: web_browsing
34        - name: 'open'
35          amount: 2
36          source: attackProFTPD
37    attackProFTPD:
38      generator:
39        import: "from examples.Linux.ProFTPD_attack.kali_attacker import ProFTPAttack"
40        construct:
41          template: "ProFTPAttack($domain, $config, $key)"
42          substitutions:
43            key: "value"

  • generator: This section controls the behavior of the ForTrace++ Generator component fortrace.generator.Generator

  • seed: Specify the seed of the Generator here. It can be used to run reproducible scenarios (same seed = same scenario)

  • action_delta_minimum: The minimum amount of seconds that has to pass between two distinct action elements

  • action_delta_maximum: The maximum amount of seconds that can pass between two distinct action elements

  • actions: This section defines action elements, the Generator will execute

  • web_browsing: Default action supported by the Generator on all operating systems. With ‘application’ one is able to define the application to be used. Make sure the browser is truly supported and installed on the system. Below you may specify the ‘operations’ to be performed. Refer to the Generator’s _execute_action_http to see the supported operations

  • file_management: Like web browsing, this is an operation supported per default for each operating system. As source one may specify the name of an action, as long as it yields any files to be used. If you specify a collection, make sure the files are already present on the VM.

  • attackProFTPD: Special kind of action. The nested ‘generator’ section must follow this distinctive pattern, because the Generator will create this object. The ‘import’ statement is used to import the object at runtime, thus keeping the Generator import statements as small as possible and support new classes without rewriting the Generator’s code. Below ‘construct’ the actual call to the imported objects constructor. The values $domain and $config are automatically substituted by the Generator. Further arguments can be specified in the ‘substitutions’ section with key:value pairs.