Installing and configuring Hatching Sandbox

Install Hatching Sandbox:

apt install hatching-sandbox qemu-hardened hatching-binaries

If /dev/kvm is still owned by root:root, then the following manual steps are required (this shall be done automatically in the near future):

mknod /dev/kvm c 10 232
chown root:kvm /dev/kvm
chmod g+rw /dev/kvm

Automatically configure Hatching Sandbox for a localhost setup:

triage-setup sandbox

One may now update the configuration file of Hatching Sandbox (which is located at /var/lib/sandbox/sandbox.yaml) to change the Hatching Sandbox listening IP address.

Configuration with a remote Hatching Triage instance may look as follows:

sandbox:
    # Make API available to Triage:
    api: "172.20.0.101:8121"

Outgoing VM traffic

All outgoing/internet traffic from and to the VM is routed using the host's default if nothing is specified. The outgoing network interface can be changed by adding a section to the sandbox.yaml configuration.

The following section should be added to /var/lib/sandbox/sandbox.yaml to achieve this behavior.

network:
  routing:
    ifaces:
    - {iface: "*", out: "<outgoing interface to use>", table: <table id to use>, default4: "<default gateway IPv4 for that route>"}
  • iface should be "*".
  • out is the network interface to which traffic should be forwarded.
  • table is an unused routing table number. This is the table to which routes will be added to for VMs.
  • default4 is the next hop/default gateway used to create the route entries.

An example /var/lib/sandbox/sandbox.yaml after adding this section:

sandbox:
    api: "172.20.0.101:8121"

network:
  routing:
    ifaces:
    - {iface: "*", out: "eth2", table: 1000, default4: "192.168.2.1"}

The hatching-sandbox-net service must be restarted after adding this section to the configuration.

systemctl restart hatching-sandbox-net

Deploying analysis VMs

We're now going to deploy one or more analysis VMs using HatchVM. The hatching-vms service and tool automates most of the process, based on the configurations specified in one or more YAML files. VM related data can be found in the following paths:

  • /var/lib/sandbox/vms -> high level hatching-vms configuration
  • /var/lib/sandbox/managedvms -> VM images and instances generated with hatching-vms
  • /var/lib/sandbox/hatchvm -> temporary "dirty" VM data that exists during an analysis

Before creating VMs, make sure the hatching-sandbox-net service is running. This can be done as follows:

systemctl restart hatching-sandbox-net

Starting the hatching-sandbox-net service requires that a sandbox.yaml configuration file exists.

Creating VM YAMLs

Before we can create VMs, one or more HatchVM configuration YAMLs must be placed in /var/lib/sandbox/vms. HatchVM will use these files to create the actual VMs and install the specified software.

The YAML configurations contain multiple sections. Most should not be edited, except the machine (under vm), scripts and instances keys.

Key Subkey Description
vm contains settings that tell what OS, version, ISO, mirror, etc will be used
vm machine contains the hardware configuration of the VM.
The values of its memory and cpu_cores keys can be changed if needed.
Ensure that you give enough CPU cores and memory to meet the minimum requirements of the OS. Memory is set by a number and a size unit M or G. I.E: 4096M or 4G for 4 gigabyte memory.
Defaults are used if nothing is specified. The default values differ per OS.
env script_dirs contains the custom path(s) where additional scripts to be used during VM installation are located.
scripts contains the names of one or more scripts that perform configurations or software installations. The scripts that are commented can be added in addition to the ones already in there.
It is not recommended to remove scripts entries.
instances contains the number that specifies the amount of VMs that will be created.

Below are the recommended VM YAMLs.

Windows 10 build 2004

Copy or download the VM YAML and place it in: /var/lib/sandbox/vms/win10v2004.yaml

platform: hatchvm

vm:
    os: windows10-2004
    arch: x64
    iso_file: Win10_2004.iso
    os_product_version: pro
    machine:
        cpu_cores: 2
        audio: hda
        # uncomment to override default disk size (256GB) in bytes
        # disk: 1000000000000

scripts:
# Standard
- {name: schtasks}
- {name: setres, vars: {width: 1280, height: 720}}
- {name: windows}
- {name: windows10}
- {name: edge_update}
- {name: wallpaper-fetch}
- {name: cppredist}
- {name: dotnet472}
- {name: mscorsvw}

- {name: ie11}
- {name: adobedc}
- {name: 7zip}
- {name: vlc}

#- {name: java8-jdk}
#- {name: java8-jre}
#- {name: office2019, vars: {licenseKey: "YOUR-LICENSE-KEY", kmsserver: "YOUR-KMS-SERVER-OPTIONAL"}}
#- {name: python2}
#- {name: ccleaner}
#- {name: steam}
#- {name: skype}

- {name: firefox_124}
- {name: chrome_123}
- {name: chrome_update}

# uncomment to install additional locales, internet connectivity is required
#- {name: win-lang, vars: {locale: "de-DE"}}
#- {name: win-lang, vars: {locale: "fr-FR"}}

# for offline language pack installation, see below

# NOTE: you must download both of the following ISO files
# they are available free of charge from Microsoft
# place them in /usr/share/hatchvm/resources/
# 19041.1.191206-1406.vb_release_CLIENTLANGPACKDVD_OEM_MULTI.iso
# 19041.1.191206-1406.vb_release_amd64fre_FOD-PACKAGES_OEM_PT1_amd64fre_MULTI.iso
# the list of supported locales can be found here
# https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/available-language-packs-for-windows?view=windows-10
# uncomment both win10-lang and win10-fod for each desired locale
#- {name: win10-lang, vars: {locale: "de-DE"}}
#- {name: win10-fod, vars: {locale: "de-DE"}}
#- {name: win10-lang, vars: {locale: "fr-FR"}}
#- {name: win10-fod, vars: {locale: "fr-FR"}}

post_scripts:
- {name: setres, vars: {width: 1280, height: 720}}
- {name: schtasks}
- {name: patchandgo}
- {name: finalize}

instance_scripts:
- {name: load-iso-drivers}
- {name: random-files}
- {name: speeder}
- {name: flushdns}
- {name: browser_startup}

children:
- name: "en"
  instances: 8
  config:
      tags: ["locale:en-us"]
# uncomment to generate additional locales
#for each locale: add corresponding `win10-lang` and `win10-fod` above
#- name: "fr"
#  instances: 4
#  config:
#    tags: ["locale:fr-FR"]
#    scripts:
#      - {name: win-region, vars: {locale: "fr-FR"}}
#- name: "de"
#  instances: 4
#  config:
#    tags: ["locale:de-DE"]
#    scripts:
#      - {name: win-region, vars: {locale: "de-DE"}}

Windows 11 (21H2)

Copy or download the VM YAML and place it in: /var/lib/sandbox/vms/win11-21h2.yaml

platform: hatchvm

vm:
  os: windows11
  arch: x64
  os_product_version: pro
  iso_file: win11_eng_20220915.iso
  machine:
    cpu_cores: 2
    audio: hda
    # uncomment to override default disk size (256GB) in bytes
    # disk: 1000000000000


scripts:
- {name: schtasks}
- {name: setres, vars: {width: 1280, height: 720}}
- {name: windows}
- {name: windows11}
- {name: edge_update}
- {name: wallpaper-fetch}
- {name: cppredist}
- {name: dotnet472}
- {name: net6}
- {name: net7}
- {name: net8}
- {name: mscorsvw}
- {name: sysmon}
- {name: bsod-behaviour}

- {name: adobedc}
- {name: 7zip}
- {name: vlc}

#- {name: java8-jdk}
#- {name: java8-jre}
#- {name: office2019, vars: {licenseKey: "YOUR-LICENSE-KEY", kmsserver: "YOUR-KMS-SERVER-OPTIONAL"}}

- {name: firefox_124}
- {name: chrome_123}
- {name: chrome_update}

# the list of supported locales can be found here
# https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/available-language-packs-for-windows?view=windows-11
# uncomment to install additional locales, internet connectivity is required
#- {name: win11-lang-online, vars: {locale: "de-DE"}}
#- {name: win11-lang-online, vars: {locale: "fr-FR"}}

# for offline language pack installation, see below

# NOTE: you must download the following ISO file
# it is available free of charge from Microsoft
# place the ISO in /usr/share/hatchvm/resources/
# 22000.1.210604-1628.co_release_amd64fre_CLIENT_LOF_PACKAGES_OEM.iso
# uncomment to install additional locales
#- {name: win11-lang, vars: {locale: "de-DE"}}
#- {name: win11-lang, vars: {locale: "fr-FR"}}

post_scripts:
- {name: setres, vars: {width: 1280, height: 720}}
- {name: schtasks}
- {name: patchandgo}
- {name: finalize}

instance_scripts:
- {name: load-iso-drivers}
- {name: random-files}
- {name: speeder}
- {name: restart_clicktorun}
- {name: browser_startup}
- {name: flushdns}

children:
- name: "en"
  instances: 8
  config:
    tags: ["locale:en-us"]
# uncomment to generate additional locales
#for each locale: add corresponding `win11-lang-online` above
#- name: "fr"
#  instances: 4
#  config:
#    tags: ["locale:fr-FR"]
#    scripts:
#      - {name: win-region, vars: {locale: "fr-FR"}}
#- name: "de"
#  instances: 4
#  config:
#    tags: ["locale:de-DE"]
#    scripts:
#      - {name: win-region, vars: {locale: "de-DE"}}

Deprecated images

Windows 7

Download the VM YAML and place it in /var/lib/sandbox/vms/win7.yaml

Note: Windows 7 has been End of Support since 2020 and is provided for compatibility purposes. Windows 7 is not supported for new installations.

Windows 10 build 1703

Download the VM YAML, and place it in /var/lib/sandbox/vms/win10v1703.yaml

Note: Windows 10 build 1703 has reached its End of Support, and is provided for compatibility purposes. Windows 10 build 1703 is not supported for new installations.

Migrating from "hatchvm generate".

In the old setup, VM configuration was placed in /var/lib/sandbox/hatchvm. The new hatching-vms service also uses the /var/lib/sandbox/hatchvm directory for Sandbox-specific data, so before switching to hatching-vms it is strongly recommended to clean up old VMs once.

  1. Remove the contents of /var/lib/sandbox/hatchvm (leave an empty directory).
  2. Follow the steps below at (Re)building the VMs.

(Re)building the VMs

Required steps if hatchvm generate .. was used previously

See the Migrating from "hatchvm generate" section if this is the first time using hatching-vms and hatchvm generate .. was used before.

Analysis VMs can be generated after placing one or more HatchVM configurations in /var/lib/sandbox/vms/.

Make sure the hatching-sandbox, hatching-sandbox-net and hatching-vms service are running. This can be done by running the following command:

systemctl start hatching-sandbox-net
systemctl start hatching-sandbox
systemctl start hatching-vms

Ensure the following directory is owned by the sandbox user and group before starting the VMs build: /usr/share/hatchvm/resources. This can be achieved by running:

chown sandbox:sandbox /usr/share/hatchvm/resources

Run the following command to start the generation of the analysis VMs:

hatching-vms build

This will cause the VMs to be created in the background. This can take one or more hours, depending on how many different VMs and instances need to be created.

Running hatching-vms status will show if the build is still active. The logs of the creation can be viewed by running:

journalctl -u hatching-vms -f

Hatching-vms can detect configuration changes. Simply change a VM configuration if a change is needed and rerun hatching-vms build. Only the VMs of the changed configuration will be rebuilt.

  • To forcefully rebuild all VMs, use hatching-vms -newver build
  • To rebuild a specific VM, use hatching-vms -newver build win10 (the name of the VM matches the config file in /var/lib/sandbox/vms)

Using hatching-vms, VMs are automatically added/removed to Sandbox.

Advanced topics

Custom scripts

Scripts are provided by the hatching-hatchvm package and reside in /usr/share/hatchvm/scripts. Scripts in /usr/share/hatchvm/scripts are owned by the package and local modifications will be overwritten when the package is updated.

If you wish to modify or add scripts, to update existing software, add new software, or customize the configuration of the VM, you need to modify the VM YAML definition to include the path of the directory containing the scripts.

PowerShell scripts (with extension .ps1) and Linux scripts (with extension .sh) are then available to be defined in the scripts section of the VM YAML.

Scripts must contain a header, before the script body, with metadata for hatchvm. Refer to scripts in /usr/share/hatchvm/scripts for examples of this header and its usage (e.g. to define any necessary assets required by your script, which will be uploaded to the VM instance along with the script).

e.g. for the custom scripts custom_script1.ps1 and custom_script2.ps1 located in the directory with the path /var/lib/sandbox/custom_scripts you would make the following modifications to the VM YAML definition:

platform: hatchvm

env:
    script_dirs:
        - /usr/share/hatchvm/scripts
        - /var/lib/sandbox/custom_scripts

# vm section (omitted for clarity)

scripts:
# (existing/default scripts here)
- {name: custom_script1}
- {name: custom_script2}

Script output can be found in the log of hatching-vms while building the VM. You should confirm that your scripts are non-interactive (requiring no user input), syntactically correct, and functional before triggering a VM (re)build.

Note: This feature is for advanced users and we cannot provide support or debugging for scripts which are not provided by the hatching-hatchvm package.

Restarting Hatching Sandbox

Hatching Sandbox may be (re)started with:

systemctl restart hatching-sandbox-net hatching-sandbox

Check the status of the Sandbox services to see if they have started succesfully. Also note the log files that are produced by Hatching Sandbox:

systemctl status hatching-sandbox-net
systemctl status hatching-sandbox
ls -al /var/lib/sandbox/logs