The purpose of the forensics select hold feature is to provide accurate and non-modified data for legal, security, and operational needs. The currently supported use case allows the live capture of data associated with a user’s desktop on a periodic basis when a user is put into a select hold for legal, incident response, or operational reasons. Putting a user on forensics select hold makes the user’s desktops temporarily persistent, thus avoiding refreshing or deletion (“re-imaging”) of the desktop and providing the administrator with the ability to access the user's desktop for investigative purposes with minimum impact to the user's experience.

This feature is supported for floating and dedicated Windows instant-clone desktop pools.

How the Forensics Select Hold Feature Works

  • Role-based access control

    The forensics feature is controlled by the global privilege FORENSICS. The Super Administrator can assign this privilege to another administrator, who is known as the Forensics Administrator, but this privilege is not enabled for the Super Administrator by default. For more information, see "Global Privileges" in the Horizon 8 Administration document.

  • Archival datastore

    The archival datastore is a mounted NFS or VMFS set globally in LDAP. Horizon 8 reads this setting from LDAP to determine where to place archived data. By default, the setting is to use the same datastore that the pool is on.

  • Select hold workflow
    • Putting users on hold
      A hold can only be applied at an individual AD user level. When the Forensic Administrator puts a user on hold using the API, the following occur:
      • If the user is already using a VM, then the hold applies to the VM they are currently logged into, and to any other VMs assigned to the user.
      • When that user logs into a VM, Horizon 8 changes the state of the instant clone VM from stateless to stateful, but leaves the stateful VM in its original pool.
      • The user under hold continues to log back into the same VM and to see all the previous changes they made to their desktop. Horizon 8 does not alter the content of the VM in any way.
      • A status indicator in the administration console shows that the VM is in hold.
      • The VM is tagged as Forensic and protected in vCenter so that vCenter administrators do not accidentally alter or delete the VM.
    • During the hold period
      After a user is put on hold, the forensics team can access the stateful desktop for investigation as well as capture the live data on the fly. For this data capture, the forensics administrator has the following options.
      • Use the Archive API. The Archive API can work across multiple VMs and multiple users. You can only archive an individual VM when the user is not logged in. If user is logged in, then the archival command needs to be delayed until the user logs out.
        Archival operation is as follows:
        • The VM is shut down.
        • All disks are consolidated.
        • All snapshots are consolidated.
        • The VMDK file is copied to the selected archival location.
        • The VM is re-synced to the target image.
      • Use your own scripts or third party tools. In this case, you can choose whether to archive just hypervisor memory, just the VMDKs of the VMs, or both hypervisor memory and VMDKs.

        The isHeldUser environment variable indicates whether the user connecting to the session is a held user. Based on the value of this variable, you can trigger data collection scripts when a held user logs on to a desktop. A script can be triggered when the Script Host Service is running on the Connection Server VM. For more information, see Activate the VMware Horizon View Script Host Service in the Horizon Remote Desktop Features and GPOs document.

      Things to note during the hold period:
      • A held VM cannot be refreshed, recovered, removed, or put into maintenance mode. This applies only to the held VM, not to any other VMs in the same pool.
      • A pool containing held VMs cannot be deleted.
      • When the auto shrink capability of the pool is set, Horizon 8 prioritizes the held VM so that it is not lost.
      • When the instant clone pool needs to undergo pool refresh or patch update, there are two possible options:
        • When a pool containing held VMs needs to be refreshed and the archival datastore is not set, push image ignores the stateful VMs. This preserves the VMs under hold for forensics purposes, and the user continues to be directed to the persistent VM when they log in. These VMs must then be patched with separate tools like persistent VMs.
        • When a pool containing held VMs needs to be refreshed and the archival datastore is set, Horizon 8 first performs a push image on all the other VMs in the pool, then archives the held VMs. After the held VMs have been archived, Horizon 8 performs a normal push image process on them. The next time the held user logs back in, they get a pristine VM, which turns into a stateful VM, and the process repeats. Note that every time a patch operation happens, additional storage is required to copy and archive the stateful VM.
    • Removing users from hold

      When the Forensics Administrator releases a user from hold using the API, the following occur.

      • Horizon 8 turns the VM back into a stateless VM.
      • The Forensic tag applied when the VM is put on hold is removed and the VM can be deleted from vCenter.
      • On the next user logoff, the VM is deleted and recreated from the golden image, thus reverting to a pristine state.
  • Forensic operations in the Events database

    All operations, including granting of the FORENSICS privilege and holding/releasing users, are captured in the Events database. This can be used to notify any scripts that need to run.

Using APIs to Perform Forensics Select Hold Functions

You can use Horizon APIs to perform forensics select hold as described below. For each API, there is a link to its documentation on the VMware {code} website.

  • Create Forensic Administrator Role and Assign a User
    1. Create the custom Forensic Administrator role using the following API:
      /config/v1/roles

      Documentation for this API is found here.

    2. Assign the custom Forensic Administrator role by following the instructions in "Create an Administrator in Horizon Console" in the Horizon 8 Administration guide.
  • Designate a datastore for archiving
    To designate a datastore for archiving virtual disks and memory, use the following API: 
    /config/v1/virtual-centers/{id}/action/mark-datastores-for-archival

    Documentation for this API is found here.

  • Put User on Hold
    To put a user on hold, use the following API: 
    /external/v1/ad-users-or-groups/action/hold
    The API returns the desktop ID, pool ID, and machine state for all desktops that are assigned to the held user. You can use this alert information to trigger scripted data collection. Documentation for this API is found here.

    In vCenter, the ForensicHold tag is applied to all the VMs used by held users.

  • Archive the Virtual Disk and Memory of a VM
    To archive the virtual disk and memory of a VM, use the following API: 
    /inventory/v1/machines/action/archive

    Documentation for this API is found here.

    • Archiving occurs when the user logs out of the held VM.
    • When VMs have been archived, they are shown inside the Archive folder on the archive datastore (as specified above in the API) in vCenter.
    • If a VM has more than one disk, then only the primary disk is archived. Multi-disk archival is not supported in this release.
  • Release User From Hold
    To release a user from hold, use the following API: 
    /external/v1/ad-users-or-groups/action/release-hold

    The API returns the desktop ID, pool ID, and machine state for all desktops that are assigned to the held user. You can use this alert information to trigger scripted data collection. Documentation for this API is found here.

  • List Held Users
    To list held users, use the following API: 
    /external/v1/ad-users-or-groups/held-users-or-groups

    Documentation for this API is found here.

  • List Held Machines
    To produce a list of machines currently on hold, use the following API: 
    /inventory/v3/machines

    Documentation for this API is found here.

    Note: This API returns all machines. In the response, VMs on hold have the value "held_machine": true.