## File: README.md # FLARE-VM Welcome to FLARE-VM - a collection of software installations scripts for Windows systems that allows you to easily setup and maintain a reverse engineering environment on a virtual machine (VM). FLARE-VM was designed to solve the problem of reverse engineering tool curation and relies on two main technologies: [Chocolatey](https://chocolatey.org) and [Boxstarter](https://boxstarter.org). Chocolatey is a Windows-based Nuget package management system, where a "package" is essentially a ZIP file containing PowerShell installation scripts that download and configure a specific tool. Boxstarter leverages Chocolatey packages to automate the installation of software and create repeatable, scripted Windows environments. ## Requirements **FLARE-VM should ONLY be installed on a virtual machine**. The VM should satisfy the following requirements: * Windows ≥ 10 * PowerShell ≥ 5 * Disk capacity of at least 60 GB and memory of at least 2GB * Usernames without spaces or other special characters * Internet connection * Tamper Protection and any Anti-Malware solution (e.g., Windows Defender) disabled, preferably via Group Policy * Windows Updates Disabled ## Installation instruction This section documents the steps to install FLARE-VM. You may also find useful the [_Building a VM for Reverse Engineering and Malware Analysis! Installing the FLARE-VM_ video](https://www.youtube.com/watch?v=i8dCyy8WMKY). ### Pre-installation * Prepare a Windows 10+ virtual machine * Install Windows in the virtual machine, for example using the raw Windows 10 ISO from https://www.microsoft.com/en-us/software-download/windows10ISO * Ensure the [requirements above](#requirements) are satisfied, including: * Disable Windows Updates (at least until installation is finished) * https://www.windowscentral.com/how-stop-updates-installing-automatically-windows-10 * Disable Tamper Protection and any Anti-Malware solution (e.g., Windows Defender), preferably via Group Policy. * GPO: [https://stackoverflow.com/questions/62174426/how-to-permanently-disable-windows-defender-real-time-protection-with-gpo](https://superuser.com/a/1757341) * Non-GPO - Manual: [https://www.maketecheasier.com/permanently-disable-windows-defender-windows-10/](https://www.maketecheasier.com/permanently-disable-windows-defender-windows-10) * Non-GPO - Automated: [https://github.com/ionuttbara/windows-defender-remover](https://github.com/ionuttbara/windows-defender-remover) * Non-GPO - Semi-Automated (User needs to toggle off Tamper Protection): [https://github.com/AveYo/LeanAndMean/blob/main/ToggleDefender.ps1](https://github.com/AveYo/LeanAndMean/blob/main/ToggleDefender.ps1) * Take a VM snapshot so you can always revert to a state before the FLARE-VM installation * NOTE for IDA Pro: If you are installing IDA Pro via `idapro.vm`, you must place your IDA Pro installer (and optionally, your license file) on the Desktop before running the FLARE-VM installer. ### FLARE-VM installation * Open a `PowerShell` prompt as administrator * Download the installation script [`installer.ps1`](https://raw.githubusercontent.com/mandiant/flare-vm/main/install.ps1) to your Desktop: * `(New-Object net.webclient).DownloadFile('https://raw.githubusercontent.com/mandiant/flare-vm/main/install.ps1',"$([Environment]::GetFolderPath("Desktop"))\install.ps1")` * Unblock the installation script: * `Unblock-File .\install.ps1` * Enable script execution: * `Set-ExecutionPolicy Unrestricted -Force` * If you receive an error saying the execution policy is overridden by a policy defined at a more specific scope, you may need to pass a scope in via `Set-ExecutionPolicy Unrestricted -Scope CurrentUser -Force`. To view execution policies for all scopes, execute `Get-ExecutionPolicy -List` * Finally, execute the installer script as follow: * `.\install.ps1` * To pass your password as an argument: `.\install.ps1 -password ` * To use the CLI-only mode with minimal user interaction: `.\install.ps1 -password -noWait -noGui` * To use the CLI-only mode with minimal user interaction and a custom config file: `.\install.ps1 -customConfig -password -noWait -noGui` * After installation it is recommended to switch to `host-only` networking mode and take a VM snapshot #### Installer Parameters Below are the CLI parameter descriptions. ``` PARAMETERS -password Current user password to allow reboot resiliency via Boxstarter. The script prompts for the password if not provided. -noPassword [] Switch parameter indicating a password is not needed for reboots. -customConfig Path to a configuration XML file. May be a file path or URL. -customLayout Path to a taskbar layout XML file. May be a file path or URL. -noWait [] Switch parameter to skip installation message before installation begins. -noGui [] Switch parameter to skip customization GUI. -noReboots [] Switch parameter to prevent reboots (not recommended). -noChecks [] Switch parameter to skip validation checks (not recommended). ``` Get full usage information by running `Get-Help .\install.ps1 -Detailed`. #### Installer GUI The Installer GUI is display after executing the validation checks and installing Boxstarter and Chocolatey (if they are not installed already). Using the installer GUI you may customize: * Package selection from FLARE-VM and Chocolatey community * Environment variable paths #### Configuration The installer will download [`config.xml`](https://raw.githubusercontent.com/mandiant/flare-vm/main/config.xml) from the FLARE-VM repository. This file contains the default configuration, including the list of packages to install and the environment variable paths. You may use your own configuration by specifying the CLI-argument `-customConfig` and providing either a local file path or URL to your `config.xml` file. For example: ``` .\install.ps1 -customConfig "https://raw.githubusercontent.com/mandiant/flare-vm/main/config.xml" ``` #### Taskbar Layout The installer will use [`CustomStartLayout.xml`](https://raw.githubusercontent.com/mandiant/flare-vm/main/CustomStartLayout.xml) from the FLARE-VM repository. This file contains the default taskbar layout. You may use your own configuration by specifying the CLI-argument `-customLayout` and providing a local file path or URL to your `CustomStartLayout.xml` file. For example: ``` .\install.ps1 -customLayout "https://raw.githubusercontent.com/mandiant/flare-vm/main/CustomStartLayout.xml" ``` ##### Things to Consider: - Items in the .xml that are not installed will not display in the taskbar (no broken links will be pinned) - Only applications (`.exe` files) or shortcuts to applications can be pinned. - If you would like to pin something that isn't an application, consider creating a shortcut that points to `cmd.exe` or `powershell` with arguments supplied that will perform that actions you would like. - If you would like to make something run with admin rights, consider making a shortcut using `VM-Install-Shortcut` with the flag `-runAsAdmin` and pinning the shortcut. #### Post installation steps You can include any post installation step you like in the configuration inside the tags `apps`, `services`, `path-items`, `registry-items`, and `custom-items`. For example: - To show known file extensions: ```xml ``` For more examples, check the default configuration file: [`config.xml`](https://raw.githubusercontent.com/mandiant/flare-vm/main/config.xml). ## Contributing - Check our [CONTRIBUTING guide](/CONTRIBUTING.md) to learn how to contribute to the project. ## Troubleshooting If your installation fails, please attempt to identify the reason for the installation error by reading through the log files listed below on your system: * `%VM_COMMON_DIR%\log.txt` * `%PROGRAMDATA%\chocolatey\logs\chocolatey.log` * `%LOCALAPPDATA%\Boxstarter\boxstarter.log` Ensure you are running the latest version of the FLARE-VM installer and that your VM satisfies the [requirements](#requirements). ### Installer Error If the installation failed due to an issue in the installation script (e.g., `install.ps1`), [report the bug in FLARE-VM](https://github.com/mandiant/flare-vm/issues/new?labels=%3Abug%3A+bug&template=bug.yml). Provide all the information requested to ensure we are able to help you. > **Note:** Rarely should `install.ps1` be the reason for an installation failure. Most likely it is a specific package or set of packages that are failing (see below). ### Package Error Packages fail to install from time to time -- this is normal. The most common reasons are outlined below: 1. Failure or timeout from Chocolatey or MyGet to download a `.nupkg` file 2. Failure or timeout due to remote host when downloading a tool 3. Intrusion Detection System (IDS) or AV product (e.g., Windows Defender) prevents a tool download or removes the tool from the system 4. Host specific issue, for example when using an untested version 5. Tool fails to build due to dependencies 6. Old tool URL (e.g., `HTTP STATUS 404`) 7. Tool's SHA256 hash has changed from what is hardcoded in the package installation script Reasons **1-4** are difficult for us to fix since we do not control them. If an issue related to reasons **1-4** is filed, it is unlikely we will be able to assist. We can help with reasons **5-7** and welcome the community to contribute fixes as well! Please [report the bug in VM-Packages](https://github.com/mandiant/VM-Packages/issues/new?labels=%3Abug%3A+bug&template=bug.yml) providing all the information requested. ### Updates Note that package updates are best effort and that updates are not being tested. If you encounter errors, perform a fresh FLARE-VM install. ### Mailing List Subscribe to the FLARE mailing list for community announcements! Email "subscribe" to [flare-external@google.com](mailto:flare-external@google.com?subject=subscribe). ## Legal Notice > This download configuration script is provided to assist cyber security analysts in creating handy and versatile toolboxes for malware analysis environments. It provides a convenient interface for them to obtain a useful set of analysis tools directly from their original sources. Installation and use of this script is subject to the Apache 2.0 License. You as a user of this script must review, accept and comply with the license terms of each downloaded/installed package. By proceeding with the installation, you are accepting the license terms of each package, and acknowledging that your use of each package will be subject to its respective license terms. --- ## File: virtualbox/README.md # VirtualBox scripts **This folder contains several scripts related to enhance building, exporting, and using FLARE-VM in VirtualBox.** The scripts have been tested in Debian 12 with GNOME 44.9. ## Clean up snapshots It is not possible to select and delete several snapshots in VirtualBox, making cleaning up your virtual machine (VM) manually after having creating a lot snapshots time consuming and tedious (possible errors when deleting several snapshots simultaneously). [`vbox-clean-snapshots.py`](vbox-clean-snapshots.py) cleans a VirtualBox VM up by deleting a snapshot and its children recursively skipping snapshots with a substring in the name. ### Example ``` $ ./vbox-remove-snapshots.py FLARE-VM.20240604 --protected empty,clean,done,important Snapshots with the following strings in the name (case insensitive) won't be deleted: clean done Cleaning FLARE-VM.20240604 🫧 Snapshots to delete: Snapshot 1 wip unpacked JS downloader deobfuscated Snapshot 6 C2 decoded Snapshot 5 wip Snapshot 4 Snapshot 3 Snapshot 2 complicated chain - all samples ready VM state: Paused ⚠️ Snapshot deleting is slower in a running VM and may fail in a changing state Confirm deletion (press 'y'):y Deleting... (this may take some time, go for an 🍦!) 🫧 DELETED 'Snapshot 1' 🫧 DELETED 'wip unpacked' 🫧 DELETED 'JS downloader deobfuscated ' 🫧 DELETED 'Snapshot 6' 🫧 DELETED 'C2 decoded' 🫧 DELETED 'Snapshot 5' 🫧 DELETED 'wip' 🫧 DELETED 'Snapshot 4' 🫧 DELETED 'Snapshot 3' 🫧 DELETED 'Snapshot 2' 🫧 DELETED 'complicated chain - all samples ready' See you next time you need to clean up your VMs! ✨ ``` ##### Before ##### After ## Check internet adapter status [`vbox-adapter-check.py`](vbox-adapter-check.py) prints the status of all internet adapters of all VMs in VirtualBox. If the argument `--dynamic_only` is provided, the script only print the status of the dynamic analysis VM (with `.dynamic` in the name). Unless the argument `--do_not_modify` is provided, if internet is detected in any dynamic analysis VM, the script sends a notification and changes the adapters type to Host-Only. The script is useful to detect internet access, which is undesirable for dynamic malware analysis. ### Example ``` $ ~/github/flare-vm/virtualbox/vbox-adapter-check.py VM {2bc66f50-9ecb-4b10-a4dd-0cc329bc383d} ⚠️ FLARE-VM.testing is connected to the internet on adapter(s): 1 VM {a23c0c37-2062-4cf0-882b-9e9747dd33b6} ✅ REMnux.20241217.dynamic network configuration is ok VM {fa0b3733-50cb-43fd-8428-745d0e9159cb} ✅ FLARE-VM.Win10.20250211.dynamic network configuration is ok VM {e5f509ed-cbc8-4abc-b052-664246207e89} ⚠️ FLARE-VM.Win10.20250211.full.dynamic is connected to the internet on adapter(s): 1, 2 VM {e5f509ed-cbc8-4abc-b052-664246207e89} ⚙️ FLARE-VM.Win10.20250211.full.dynamic set adapter 1 to hostonly VM {e5f509ed-cbc8-4abc-b052-664246207e89} ⚙️ FLARE-VM.Win10.20250211.full.dynamic set adapter 2 to hostonly ``` #### Notification ## Export snapshot [`vbox-export-snapshot.py`](vbox-export-snapshot.py) exports a VirtualBox snapshot as an Open Virtual Appliance (OVA) file. The script configures the exported VM with a single Host-Only network interface, and the resulting OVA file is named after the snapshot. A separate file containing the SHA256 hash of the OVA is also generated for verification. The script accepts an optional description for the OVA and the name of the export directory within the user's home directory (`$HOME`) where the OVA and SHA256 hash file will be saved. If no export directory is provided, the default directory name is `EXPORTED VMS`. ### Example ``` $ ./vbox-export-snapshots.py "FLARE-VM.testing" "FLARE-VM" --description "Windows 10 VM with FLARE-VM default configuration" Exporting snapshot "FLARE-VM" from "FLARE-VM.testing" {2bc66f50-9ecb-4b10-a4dd-0cc329bc383d}... VM {2bc66f50-9ecb-4b10-a4dd-0cc329bc383d} ✨ restored snapshot "FLARE-VM" VM {2bc66f50-9ecb-4b10-a4dd-0cc329bc383d} state: saved. Starting VM... VM {2bc66f50-9ecb-4b10-a4dd-0cc329bc383d} state: running. Shutting down VM... VM {2bc66f50-9ecb-4b10-a4dd-0cc329bc383d} ⚙️ network set to single hostonly adapter VM {2bc66f50-9ecb-4b10-a4dd-0cc329bc383d} 🔄 power cycling before export... (it will take some time, go for an 🍦!) VM {2bc66f50-9ecb-4b10-a4dd-0cc329bc383d} state: poweroff. Starting VM... VM {2bc66f50-9ecb-4b10-a4dd-0cc329bc383d} state: running. Shutting down VM... VM {2bc66f50-9ecb-4b10-a4dd-0cc329bc383d} 🚧 exporting ... (it will take some time, go for an 🍦!) VM {2bc66f50-9ecb-4b10-a4dd-0cc329bc383d} ✅ EXPORTED "/home/anamg/None/FLARE-VM.ova" VM {2bc66f50-9ecb-4b10-a4dd-0cc329bc383d} ✅ GENERATED "/home/anamg/None/FLARE-VM.ova.sha256": 987eed68038ce7c5072e7dc219ba82d11745267d8ab2ea7f76158877c13e3aa9 ``` ## Build FLARE-VM VM(s) [`vbox-build-flare-vm.py`](vbox-build-flare-vm.py) automates the creation and export of customized FLARE-VM VMs. The script begins by restoring a pre-existing `BUILD-READY` snapshot of a clean Windows installation. The script then copies the required installation files (such as the IDA Pro installer, FLARE-VM configuration, and legal notices) into the guest VM. After installing FLARE-VM, a `base` snapshot is taken. This snapshot serves as the foundation for generating subsequent snapshots and exporting OVA images, all based on the configuration provided in a YAML file. This configuration file specifies the VM name, the exported VM name, and details for each snapshot. Individual snapshot configurations can include custom commands to be executed within the guest, legal notices to be applied, and file/folder exclusions for the automated cleanup process. See the configuration example file [`configs/win10_flare-vm.yaml`](configs/win10_flare-vm.yaml). The `BUILD-READY` snapshot is expected to be an empty Windows installation that satisfies the FLARE-VM installation requirements and has UAC disabled. To disable UAC execute in a cmd console with admin rights and restart the VM for the change to take effect: ``` %windir%\System32\reg.exe ADD HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System /v EnableLUA /t REG_DWORD /d 0 /f ``` ## Build REMnux VM Similarly to [`vbox-build-flare-vm.py`](vbox-build-flare-vm.py), [`vbox-build-remnux.py`](vbox-build-remnux.py) automates the creation and export of customized REMnux virtual machines (VMs). The script begins by restoring a pre-existing "BUILD-READY" snapshot of a clean REMnux OVA. Required installation files (such as the IDA Pro installer and ZIPs with GNOME extensions) are then copied into the guest VM. The configuration file specifies the VM name, the exported VM name, and details for each snapshot. Individual snapshot configurations include the extension, description, and custom commands to be executed within the guest. See the configuration example file [`configs/remnux.yaml`](configs/remnux.yaml).