# Quick Start This page provides an overview in how to getting started with ForTrace++, after the successful installation. ## Installation of VMs ```{eval-rst} .. note:: Please read the instructions in :doc:`libvirt Tuning `. ``` This section is concerned with the installation of VMs through [Virtual Machine Manager](https://virt-manager.org/). 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](https://www.microsoft.com/en-us/software-download/windows10ISO). 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 6. Answer the security questions as you like, since we don't need them for this scenario 7. Adjust the privacy setting for your device as you prefer 8. Skip the 'customise experience step' 9. 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 5. 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' 6. 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 7. 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 8. Due to SeaBIOS limitation: Disable SecureBootEncodeUEFI to suppress CMD popup [Source](https://learn.microsoft.com/en-us/answers/questions/1363453/securebootencodeuefi-exe-shell-window-opening-afte) 1. Open 'Task Scheduler' 2. Navigate to 'Task Scheduler Library\Microsoft\Windows\PI' 3. Select 'SecureBootEncodeUEFI' and click 'Disable' 9. 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 3. Most likely it will be necessary to perform a restart, hence hit 'Update and restart' 10. 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](https://mag37.org/posts/guide_w11_vm_with_virtman/) 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: ```{code-block} yaml :linenos: true domain: - "" - "" ``` ### 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. ```{code-block} yaml :linenos: true domain: username: "kali" password: "kali" name: "kali" network: "default" os_type: OSType.LINUX shell_type: ShellType.ZSH package_manager: PackageManager.APT desktop_environment: DesktopEnvironmentType.GNOME start_sniffer: False snapshot: "clean-install" dump_ram: False 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 {py:class}`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 {py:class}`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 {py:class}`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 {py:class}`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**). ```{code-block} xml :linenos: true
``` ### Generator Section This *generator* section contains parameters used to configure the semi-random action generator's behavior. ```{code-block} yaml :linenos: true generator: seed: 1234 action_delta_minimum: 5 action_delta_maximum: 10 actions: web_browsing: application: "Firefox" operations: - name: "browsing" amount: 30 source: c-http-0 enable_scraping: True - name: "browsing" amount: 10 source: c-http-1 enable_scraping: True - name: "download" amount: 10 source: c-http-2 - name: "web_search" amount: 5 source: c-web-search # search_engine: "Google" file_management: application: "Files" operations: - name: 'copy' amount: 5 source: web_browsing destination: "/home/kali/Documents" - name: 'to_trash' amount: 5 source: web_browsing - name: 'open' amount: 2 source: attackProFTPD attackProFTPD: generator: import: "from examples.Linux.ProFTPD_attack.kali_attacker import ProFTPAttack" construct: template: "ProFTPAttack($domain, $config, $key)" substitutions: key: "value" ``` - `generator`: This section controls the behavior of the ForTrace++ Generator component {py:class}`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.