Forensics Select Hold for Dedicated and Floating Instant Clone Desktops

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.

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 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 in vCenter so that vCenter administrators know not to alter it.
- 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.
  - 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 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.