Windows.Sys.Users#

Many Velociraptor artefacts which target the user registry, such as Windows.Registry.UserAssist, access the NTUSER.DAT hive through the Windows.Registry.NTUser artefact. However, this artefact relies on Windows.Sys.Users to enumerate the list of user profiles present on the system.
By default, the Windows.Sys.Users artefact retrieves user information from the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList\*

This works as expected on endpoint systems but fails on virtual Velociraptor clients, where this registry key relates to the one on the file server and not from the VHDX-based profiles. In such environments, since the key is from a system-based hive, it only reflects the local system users, not those stored in VHDX containers.
As a result, Velociraptor is unable to discover or parse the NTUSER.DAT hives located inside the VHDX files.
To overcome this, we explore two possible solutions:

1. Fake registry remapping: inject a synthetic ProfileList registry hive.
2. Artefact override: customise Windows.Sys.Users to support VHDX discovery logic.

Fake registry remapping
One approach to solving the user enumeration problem is to remap not only the file system to the VHDX image, but also the ProfileList registry key. By providing a custom registry hive that mimics this key, Velociraptor can be tricked into “seeing” the VHDX-hosted profiles as if they were locally present.
In the example below, we use PowerShell to:

1. Create temporary registry keys for each user.
2. Set their ProfileImagePath values to simulate the standard Windows user structure.
3. Export the registry hive to a .dat file.

# Define paths for the temporary hive and final file
$tempHivePath = "HKLM\Software\Velociraptor"
$binaryFilePath = "C:/Program Files/Velociraptor/Profile/ProfileList.dat"

# Add the users to the temp hive
reg.exe add "$($tempHivePath)\Brontosaurus" /v "ProfileImagePath" /t REG_EXPAND_SZ /d "C:\Users\Brontosaurus" /f
reg.exe add "$($tempHivePath)\Stegosaurus" /v "ProfileImagePath" /t REG_EXPAND_SZ /d "C:\Users\Stegosaurus" /f
reg.exe add "$($tempHivePath)\Tyrannosaurus" /v "ProfileImagePath" /t REG_EXPAND_SZ /d "C:\Users\Tyrannosaurus" /f

# Export the temp hive
reg exe save $tempHivePath $binaryFilePath

# Cleanup the temp hive
reg.exe delete $tempHivePath /f

Next, we configure a YAML remapping to instruct Velociraptor to mount this exported hive in place of the original ProfileList key:

- type: mount
  description: 'Registry - HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList'
  from:
    accessor: raw_reg
    prefix: |
      {
        "Path": "/"
        "DelegateAccessor": "file"
        "DelegatePath": "C:/Program Files/Velociraptor/Profile/ProfileList.dat"
      }
      path_type: registry
  "on" :
    accessor: registry
    prefix: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList
    path_type: registry

With this setup, any call to Windows.Sys.Users will retrieve the synthetic entries we defined, allowing downstream artefacts (like Windows.Registry.NTUser) to function correctly. However, this approach has limitations. It involves manual steps that must be repeated whenever new users are added. Therefore, it is most suitable for small-scale, targeted investigations or proof-of-concept testing.

Artefact Override
A more robust and scalable solution is to override the default Windows.Sys.Users artefact. The customised version maintains compatibility with standard systems while adding logic to detect and enumerate VHDX-based profiles when operating in a virtual Velociraptor client context.
The core idea is to introduce a conditional check based on the Velociraptor client’s label. If the client is tagged with a specific label (e.g., remapped_profile), the artefact will scan for NTUSER.DAT files within C:\Users\*\ instead of relying on the traditional registry key.
The VQL override below illustrates this logic:

LET GetTimestamp(High, Low) = if(condition=High,
        then=timestamp(winfiletime=High * 4294967296 + Low))

// lookupSID() may not be available on deaddisk analysis
LET Standard = SELECT split(string=Key.OSPath.Basename, sep="-")[-1] as Uid,
   "" AS Gid,
   LookupSIDCache(SID=Key.OSPath.Basename || "") AS Name,
   Key.OSPath as Description,
   ProfileImagePath as Directory,
   Key.OSPath.Basename as UUID,
   Key.Mtime as Mtime,
   {
        SELECT Mtime
        FROM stat(filename=expand(path=ProfileImagePath))
    } AS HomedirMtime,
   dict(ProfileLoadTime=GetTimestamp(
           High=LocalProfileLoadTimeHigh, Low=LocalProfileLoadTimeLow),
        ProfileUnloadTime=GetTimestamp(
           High=LocalProfileUnloadTimeHigh, Low=LocalProfileUnloadTimeLow)
   ) AS Data
FROM read_reg_key(globs=remoteRegKey, accessor="registry")

// User list for remapped VHDX profiles emulating the Standard one
LET VHDXProfile = SELECT
      OSPath.Components[-2] AS Uid,
      OSPath.Dirname AS Directory,
      OSPath.Components[-2] AS UUID,
      OSPath.Components[-2] AS Name,
      "" AS Gid,
      Mtime,
      Mtime AS HomedirMtime,
      "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\ProfileList\\" + OSPath.Components[-2] AS Description
    FROM glob(globs="C:/Users/*/NTUSER.DAT")

// Get the labels of the agent 
LET agent_config = SELECT labels FROM config

// Take the appropriate user list method
SELECT * FROM if(condition=agent_config.labels=~labelName, then=VHDXProfile, else=Standard)

Once the artefact override is written, it can be deployed at the server level using the following command:

/usr/local/bin/velociraptor —config /etc/velociraptor/server.config.yaml —definitions /etc/velociraptor/artifact_definitions frontend

With this configuration, the Velociraptor server will automatically distribute the custom artefact to clients. There’s no need to modify individual client configurations. Any virtual client launched with the appropriate label (e.g., remapped_profile) will use the VHDX logic seamlessly.
This is a better solution as it centralises logic, reduces operational overhead, and supports dynamic scaling, making it ideal for multi-user investigations.

Remapping Configuration#

Once the user enumeration issue is resolved using the artefact override, the next step is to create a remapping configuration that links specific user profile paths (e.g. C:\Users\Brontomerus) to their corresponding VHDX files.
This remapping is crucial: it allows Velociraptor’s artefacts, which expect standard Windows paths, to transparently operate on data stored within VHDX containers.
Below is an example of a remapping configuration for the NTFS accessor, pointing C:\Users\Brontomerus to a specific VHDX file:

- type: mount
  description: 'NTFS - Brontomerus'
  from:
    accessor: raw_ntfs
    prefix: |
      {
        "DelegateAccessor": "offset",
        "Delegate": {
          "DelegateAccessor": "vhdx",
          "DelegatePath": "F:/VHDX/Profile_Brontomerus.VHDX",
          "Path":"/1048576"
        },
        "Path": "/Profile"
      }
  "on":
    accessor: ntfs
    prefix: '\\.\C:\Users\Brontomerus'
    path_type: ntfs

This remapping allows the virtual Velociraptor client to access the contents of the VHDX file as if it were the actual C:\Users\Brontomerus directory on disk. To ensure full compatibility with Velociraptor artefacts, similar remappings should be created for:

• file accessor for standard file operations
• auto accessor for hybrid path resolution
• registry accessor for registry hive access

When these accessors are mapped properly, standard artefacts (like Windows.Registry.NTUser, Windows.Registry.UserAssist, etc.) will function as expected within the virtual client context.

Virtual Client Creation#

With the remapping configuration in place, we can now launch a virtual Velociraptor client. This is a standalone Velociraptor process that operates like a deaddisk client, using the remapped paths to access the contents of a specific VHDX file as if it were a local user profile.
The following PowerShell command starts the virtual client using the appropriate configuration and remapping YAML file:

Start-Process -FilePath '.\Velociraptor.exe' -ArgumentList '—config client.config.yaml —config.client-writeback-windows="velociraptor_vhdx.writeback.yaml" —config.client-local-buffer-filename-windows="C:\Windows\Temp\velociraptor_vhdx_Buffer.bin" —remap "C:\Program Files\Velociraptor\velociraptor_vhdx_remapping.yaml" —config.client-labels=remapped_profile client' -WorkingDirectory 'C:\Program Files\Velociraptor' -WindowStyle Hidden

Once launched, the virtual client behaves like any standard Velociraptor endpoint, but its file system and registry access are redirected to the contents of the mounted VHDX. This enables seamless browsing of the virtual profile via the Virtual File System (VFS).

It also allows running existing artefacts or any other profile-level checks.

This virtual client is not persistent. If the system reboots or the client crashes, the process must be relaunched. Fortunately, this can be done using the same artefact described later in this post.

All in One Remapping#

This approach loads all VHDX files into a single remapping configuration, resulting in a YAML file about 2.6 MB in size. While ideally efficient, it caused instability; the virtual client crashed during execution of simple artefacts (e.g., Generic.Client.Info), probably due to too many VHDX files being open simultaneously, exceeding system limits.

One-to-One Clients#

Here, we spun up one virtual Velociraptor client per user profile. This would work best as each profile has its own virtual client, which eases the logic. However, this resulted in excessive system resource usage and hundreds of active processes, which is not sustainable for large-scale investigations.

Batching: The Optimal Middle Ground#

The most effective approach was to launch multiple virtual clients, each handling a batch of 40 profiles. This method balances load across processes and avoids overwhelming system resources.

With this configuration, we analysed the UserAssist of 1,000 VHDX files in under 30 seconds.

Use a batching strategy tuned to your environment (e.g. 20–50 profiles per client). The optimal batch size will depend on your hardware and the size of the VHDX files.

Windows.Sys.Users (Override)#

This custom override of the standard Windows.Sys.Users artefact handles both traditional systems and virtual clients. It determines which enumeration logic to use based on a label assigned to the client (e.g. remapped_profile).
Parameters:

• remoteRegKey: Location of the registry key holding the profile list.

• labelName: Client label that signals the use of VHDX-based enumeration.

In standard mode, it enumerates from the Windows registry. For virtual clients, it uses a glob search for C:\Users\*\NTUSER.DAT, indicating valid user hives within mounted VHDX files.

Windows.Vhdx.RemapConfigBuilder#

This artefact generates the remapping configuration files required by each virtual Velociraptor client. It automatically detects user profiles, organises them into batches, and writes the YAML files to disk.
Parameters:

• vhdxFolderPath: Directory containing VHDX profile files.

• usernameExtractor: Regex used to extract usernames from filenames.

• user: Optional filter to restrict which profiles to process.

• virtualHostname: Hostname to assign to the virtual clients.

• batchSize: Number of profiles per virtual client.

• vhdxOffset: NTFS start offset inside VHDX (default: 1048576).

The artefact creates a Vhdx/Remapping directory within the Velociraptor staging directory and populates it with one YAML file per batch. Filenames are sorted using the first extracted username for easy lookup. Internally, the artefact uses:

• Shadow remapping for data, raw_reg, and zip accessors

• Mount remapping for ntfs, file, auto, and registry accessors

Once executed, the artefact will list the path of the created profiles in the results section.

Windows.Vhdx.VirtualClientRunner#

This artefact launches one Velociraptor process per remapping file, effectively simulating a client that represents a set of user profiles.
Parameters:

• customLabel: Label to assign to virtual clients (must match label used in Windows.Sys.Users).

• remappingFile: One or more remapping YAML files to launch.

It creates a subdirectory Vhdx/Writeback for temporary writeback data. Each remapping file is passed into a PowerShell process that starts the virtual client. Once executed, the artefact lists all successfully started virtual clients.

Windows.Vhdx.VirtualClientRemover#

This artefact stops running virtual clients and optionally deletes all related configuration files.
Parameters:

• RemappingFile: Specific remapping file or directory to target.

• RemoveConfiguration: If enabled, deletes Vhdx folder and its subfolders.

• ReallyKillProcess: If enabled, terminates running Velociraptor processes.

It searches for running clients based on remapping file usage and performs cleanup accordingly.