Configure event detection policies

Session Recording supports centralized configuration of event detection policies. You can create policies in the Session Recording policy console to log various events.

Events that can be detected

Session Recording detects target events and tags those events in recordings for later search and playback. You can search for events of interest from large amounts of recordings and locate those events during playback.

System-defined events

Session Recording can detect and log the following system-defined events that occur during recorded sessions:

• Insertion of USB mass storage devices

• Application starts and ends

• App failures

• App installs and uninstalls

• File renaming, creation, deletion, and moving operations within sessions

• File transfers between session hosts (VDAs) and client devices (including mapped client drives and generic redirected mass storage devices)

• Web browsing activities

• Topmost window events

• Clipboard activities

• Windows registry modifications

• User account modifications

• RDP connections

• Performance data (data points related to the recorded session)

• Popup window events

• Printing activities

For example:

• Events in an event-only recording in the web player:
• Events in a screen recording in the web player:

• Events in the Session Recording player:

  For more events in the Session Recording player, see the event descriptions later in this article.

Note:

Applications built by PowerBuilder might exit unexpectedly when there are active policies detecting web browsing activities and topmost window events. To avoid the issue, use PowerBuilder 2019 R3 to build your applications.

Insertion of USB mass storage devices

Session Recording can detect the insertion of a Client Drive Mapping (CDM) mapped or generic redirected USB mass storage device in a client where Citrix Workspace app for Windows or for Mac is installed. Session Recording tags these events in the recording.

Note:

To use an inserted USB mass storage device and detect the insertion events, set the Client USB device redirection policy to Allowed in Citrix Studio.

Currently, only the insertion of USB mass storage devices (USB Class 08) can be detected.

Application starts and ends

Session Recording supports detection of both application starts and ends. When you add a process to the App monitoring list, apps driven by the added process and its child processes are monitored. Child processes of a parent process that starts before Session Recording runs can also be captured.

Session Recording adds the process names, cmd.exe, powershell.exe, and wsl.exe, to the App monitoring list by default. If you select Log app start events and Log app end events for an event detection policy, the starts and ends of the Command Prompt, PowerShell, and Windows Subsystem for Linux (WSL) apps are logged no matter whether you manually add their process names to the App monitoring list. The default process names are not visible on the App monitoring list.

In addition, Session Recording provides a full command line for each app start event logged.

Application failures

Session Recording detects app exits and unresponsive apps if you select Log app failures when creating your event detection policy. The Log app failures rule applies to all apps.

App installs and uninstalls

The Log app installs and uninstalls rule applies to all apps.

User account modifications

Session Recording can detect account creation, enablement, disablement, deletion, name changes, and password modification attempts.

RDP connections

Session Recording can detect RDP connections initiated from the VDA hosting the recorded session.

File renaming, creation, deletion, and moving operations within sessions and file transfers between session hosts (VDAs) and client devices

Session Recording can detect renaming, creation, deletion, and moving operations on target files and folders that you specify in the File monitoring list. Session Recording can also detect file transfers between session hosts (VDAs) and client devices (including mapped client drives and generic redirected mass storage devices). Selecting the Log sensitive file events option triggers the detection of file transfers, no matter whether you specify the File monitoring list.

Note:

To enable file drag and drop and capture the drag and drop events, set the Drag and Drop policy to Enabled in Citrix Studio.

Web browsing activities

Session Recording can detect user activities on supported browsers and tag the events in the recording. The browser name, URL, and page title are logged. For an example, see the following screen capture.

When you move your cursor away from a webpage that has focus, your browsing of this webpage is tagged without showing the browser name. This feature can be used to estimate how long a user stays on a webpage. For an example, see the following screen capture.

List of supported browsers:

• Google Chrome
• Microsoft Edge Chromium
• Mozilla Firefox

Note:

This feature requires Session Recording Version 1906 or later.

Topmost window events

Session Recording can detect the events when the window of an app is on top of all others. The process name, title, and process number are logged.

Clipboard activities

Session Recording can detect copy operations of text, images, and files using the clipboard. The process name and file path are logged for a file copy. The process name and title are logged for a text copy. The process name is logged for an image copy.

Note: Content of copied text is not logged by default. To log text content, go to the Session Recording agent and set HKEY_LOCAL_MACHINE\SOFTWARE\ Citrix\SmartAuditor\Agent\CaptureClipboardContent to 1(the default value is 0).

Windows registry modifications

Starting with Version 2109, Session Recording can detect and log the following registry modifications while recording sessions:

For example:

To enable this registry monitoring functionality, select the Log registry modifications option for your event detection policy.

Performance data (data points related to the recorded session)

When creating your event detection policy, select Log performance data to enable the session data overlay feature. The feature introduces a screen overlay during session playback in the web player. It is a semi-transparent overlay that you can relocate and hide. The overlay features the following data points related to the recorded session:

• Round trip time
• Network (send)
• Network (receive)
• CPU usage
• Memory usage

Popup window events

When users open or close a confidential file or access a folder, a popup window might appear, showing a prompt or asking for a password. Session Recording can now monitor such popup window events while recording sessions. Popup windows in web browsers are not monitored.

Attributes of a popup window event are recorded, including the process name and content of the prompt.

Printing activities

Session Recording monitors printing activities that occur during recorded sessions and tags them as events in recordings for later search and playback.

For an example printing activity event in the Session Recording player, see the following screen capture:

Custom events

The Session Recording agent provides the IUserApi COM interface that third-party applications can use to add application-specific event data into recorded sessions. Based on the event customization, Session Recording can block sensitive information and log the session pause and session resume events accordingly.

Sensitive information blocking

Session Recording lets you skip certain periods when recording the screen and blocks sensitive information in these periods during session playback. To use this feature, use Session Recording 2012 and later.

To use this feature, complete the following steps:

1. In Session Recording Agent Properties, select the Allow third party applications to record custom data on this VDA machine check box and click Apply.

   

2. Grant users permission to invoke the Session Recording Event API (IUserApi COM interface).

   Session Recording adds access control to the event API COM interface starting with version 7.15. Only authorized users are allowed to invoke the functionality to insert event metadata into a recording.

   Logon users with local administrator privileges are granted with this permission by default. To grant other users this permission, use the Windows DCOM configuration tool:

   1. On the Session Recording agent, run comcnfg.exe to open the Windows DCOM configuration tool.

      

      

      If you are granting permission to users who are not members of the domain administrator group and the Session Recording agent is running on Windows Server 2019 or later, or Windows 10 or later, proceed to step b. Otherwise, skip step b and go to step c directly.

   2. Select Console Root > Component Services > Computers > My Computer from the left navigation.

      Right-click My Computer and select Properties.

      

      Select the COM Security tab, and then click Edit Default to add users with Local Activation permission in the Launch and Activation Permissions section.

      

      

   3. Select Console Root > Component Services > Computers > My Computer > DCOM Config from the left navigation.

      

      Right-click Citrix Session Recording Agent and choose Properties.

      

   4. Select the Security tab, and then click Edit to add users with Local Activation permission in the Launch and Activation Permissions section.

      

      

   Note:

   DCOM configuration takes effect immediately. There is no need to restart any services or the machine.

3. Start a Citrix virtual session.

4. Start PowerShell and change the current drive to the <Session Recording agent installation path>\Bin folder to import the SRUserEventHelperSnapin.dll module.

5. Run the Session-Pause and Session-Resume cmdlets to set parameters for triggering sensitive information blocking.

   Parameter	Description	Required or Optional
   -APP	The app name that calls the Session-Pause and Session-Resume cmdlets.	Required
   -Reason	The reason that content is blocked. If you leave this parameter unspecified, the default setting shows, stating Content Blocked and Sensitive information exists and is blocked. If you set this parameter, the reason you specify shows when you navigate to the blocked period during session playback. This parameter is available for both the Session-Pause and Session-Resume cmdlets.	Optional
   -AheadSeconds	This parameter is available for the Session-Pause cmdlet only. It lets you configure the amount of time of the screen recording you want to bypass before sensitive information is detected. The default value is 1 s.	Optional

   For example, you can run Session-Pause similar to the following:

   

Search for and play back recordings with tagged events

Search for recordings with tagged events

The Session Recording player allows you to perform advanced searches for recordings with tagged events.

1. In the Session Recording player, click Advanced Search on the tool bar or choose Tools > Advanced Search.
2. Define your search criteria in the Advanced Search dialog box.

The Events tab allows you to search for tagged events in sessions by Event text or Event type or both. You can use the Events, Common, Data/Time, and Other filters in combination to search for recordings that meet your criteria.

Note:

• The Event type list itemizes all event types. You can select an event type to search. Selecting Any Citrix-defined event means to search for all recordings with any type of events logged by Citrix Session Recording.
• The Event text filter supports partial match. Wildcards are not supported.
• The Event text filter is case-insensitive when matching.
• For the types of events, the words App Start, App End, Client drive mapping, and File Rename do not participate in matching when you search by Event text. Therefore, when you type App Start, App End, Client drive mapping, or File Rename in the Event text box, no result can be found.

You can use events to navigate through a recorded session, or skip to the points where the events are tagged.

System-defined event detection policy

The system-defined event detection policy is Do not detect. It’s inactive by default. When it’s active, no events are logged.

You cannot modify or delete the system-defined event detection policy.

Create a custom event detection policy

Considerations

You can specify which events to log. A wizard within the Session Recording policy console helps you create rules. For each rule you create, you select the events to log and specify which sessions the rule applies to through the rule criteria settings.

For each rule, choose at least one of the following items to create the rule criteria:

• Users or Groups. Creates a list of users or groups to which the rule applies.
• Published Applications or Desktop. Creates a list of published applications or desktops to which the rule applies.
• Delivery Groups or Machines. Creates a list of Delivery Groups or machines to which the rule applies.
• IP Address or IP Range. Creates a list of IP addresses or ranges of IP addresses to which the rule applies. The IP addresses mentioned here are the IP addresses of the Citrix Workspace apps.

• Filter. Creates a list of smart access tags to which the rule applies. You can configure contextual access (smart access) using smart access policies on Citrix NetScaler.

  

  Contextual access (smart access) is available for Session Recording 2402 and later. It lets you apply policies based on the user access context including:

  • The user’s location
  • IP address range
  • Delivery group
  • Device type
  • Installed applications

Steps

To create a custom event detection policy:

1. Log on as an authorized Policy Administrator to the server where the Session Recording policy console is installed.

2. Start the Session Recording policy console. By default, there is no active event detection policy.

3. Select Event Detection Policies in the left pane. From the menu bar, choose Add New Policy to create an event detection policy.

4. (Optional) Right-click the new event detection policy and rename it.

   

5. Right-click the new event detection policy and select Add Rule.

   1. Specify one or more target events to monitor by selecting the check box next to each event type. Scroll down the window to view all available event types.

      

      • Log CDM mapped USB events: Logs the insertion of a Client Drive Mapping (CDM) mapped mass storage device in a client where Citrix Workspace app for Windows or for Mac is installed.

      • Log generic USB redirection: Logs the insertion of a generic redirected mass storage device in a client where Citrix Workspace app for Windows or for Mac is installed.

      • Log app start events: Logs the starts of target applications.

      • Log app end events: Logs the ends of target applications.

        Note:

        The Log app end events check box is grayed out before you select Log app start events.

      • App monitoring list: When you select Log app start events and Log app end events, use the App monitoring list to specify target applications to monitor and to avoid an excessive number of events from flooding the recordings.

        Note:

        • To capture the start and end of an application, add the process name of the application in the App monitoring list. For example, to capture the start of Remote Desktop Connection, add the process name mstsc.exe to the App monitoring list. When you add a process to the App monitoring list, applications driven by the added process and its child processes are monitored. Session Recording adds the process names, cmd.exe, powershell.exe, and wsl.exe, to the App monitoring list by default. If you select Log app start events and Log app end events for an event detection policy, the starts and ends of the Command Prompt, PowerShell, and Windows Subsystem for Linux (WSL) apps are logged regardless of whether you manually add their process names to the App monitoring list. The default process names aren’t visible on the App monitoring list.
        • Separate process names with a semicolon (;).
        • Only the exact match is supported. Wildcards aren’t supported.
        • Process names you add are case-insensitive.
        • To avoid an excessive number of events from flooding the recordings, do not add any system process names (for example, explorer.exe) and web browsers in the registry.

      • Log file operations: Logs operations on target files in the File monitoring list and logs file transfers between session hosts (VDAs) and client devices (including mapped client drives and generic redirected mass storage devices). Selecting this option triggers the logging of file transfers, no matter whether the File monitoring list is specified.

        • File events presented in the web player

          

        • File events presented in the Session Recording Player

          

      • File monitoring list: When you select Log file operations, use the File monitoring list to specify target files to monitor. You can specify folders to capture all files within them. No file is specified by default, which means no file is captured by default.

        Note:

        • To capture renaming, creation, deletion, or moving operations on a file, add the path string of the file folder (not the file name or the root path of the file folder) in the File monitoring list. For example, to capture renaming, creation, deletion, and moving operations on the sharing.ppt file in C:\User\File, add the path string C:\User\File in the File monitoring list.
        • Both local file paths and remote shared folder paths are supported. For example, to capture operations on the RemoteDocument.txt file in the \\remote.address\Documents folder, add the path string \\remote.address\Documents in the File monitoring list.
        • Separate monitored paths with a semicolon (;).
        • Only exact matches are supported. Wildcards aren’t supported.
        • Path strings are case-insensitive.

        Limitations:

        • Copying files or folders from a monitored folder to an unmonitored folder isn’t captured.
        • When the length of a file or folder path including the file or folder name exceeds 260 characters, operations on the file or folder aren’t captured.
        • Pay attention to the database size. To prevent large numbers of events from being captured, back up or delete the “Event” table regularly.
        • When large numbers of events are captured in a short time, the player displays and the database stores only one event for each type to avoid storage expansion.

      • Log web browsing activities: Logs user activities on supported browsers and tags the browser name, URL, and page title in the recording.

        

        List of supported browsers:

        • Google Chrome
        • Microsoft Edge Chromium
        • Mozilla Firefox

      • Log topmost window events: Logs the topmost window events and tags the process name, title, and process number in the recording.

        

      • Log clipboard activities: Logs copy operations of text, images, and files using the clipboard. The process name and file path are logged for a file copy. The process name and title are logged for a text copy. The process name is logged for an image copy.

      • Log registry modifications: Logs the following Windows registry modifications: add a key or value, rename a key or value, change an existing value, and delete a key or value.

      • Registry monitoring list: When you select Log registry modifications, type the absolute paths of the registries you want to monitor and separate the paths with a semicolon (;). Start a path with HKEY_USERS, HKEY_LOCAL_MACHINE, or HKEY_CLASSES_ROOT. For example, you can type HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows;HKEY_CLASSES_ROOT\GuestStateVDev. If you leave this list unspecified, no registry modification is captured.

      • Log app failures: Logs unexpected app exits and unresponsive apps. This rule applies to all apps.

      • Log user account modifications: Logs the following user account modifications: account creation, enablement, disablement, deletion, lockout, name changes, and password modification attempts.

      • Log RDP connections: Logs RDP connections initiated from the VDA hosting the recorded session.

      • Log app installs and uninstalls: Logs app installs and uninstalls during the recorded session. This rule applies to all apps.

      • Log performance data: Enables the session data overlay feature. Select this check box to view data points related to the recorded session.

      • Log popup windows: Logs popup windows that might appear when users open or close a confidential file or access a folder.

      • Log printing activities: Logs printing activities that occur during recorded sessions.

   2. Select and edit the rule criteria.

      Similar to creating a custom recording policy, you can choose one or more rule criteria:

      • Users or Groups
      • Published Applications or Desktop
      • Delivery Groups or Machines
      • IP Address or IP Range 
      • Filter

      To obtain the lists of published applications or desktops and delivery groups or VDA machines, you must have the read permission as a site administrator. Configure the administrator read permission on the Delivery Controller of the site.

      For more information, see the instructions in the Create a custom recording policy section.

      Note:

      Some sessions might not meet any rule criteria in an event detection policy. For these sessions, the action of the fallback rule applies, which is always Do not detect. You cannot modify or delete the fallback rule.

   3. Follow the wizard to complete the configuration.

      

After a session that matches an event detection policy starts, the session ID and its event registry values appear in the Session Recording agent. For example:

Compatibility with registry configurations

When Session Recording is newly installed or upgraded, no active event detection policy is available by default. In this case, each Session Recording agent respects the registry values under HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\SmartAuditor\SessionEvents to determine whether to log specific events. For a description of the registry values, see the following table:

Here are some compatible scenarios:

• If your Session Recording is newly installed or upgraded from a release earlier than 1811 that doesn’t support event detection (logging), the related registry values on each Session Recording agent are the default. Because there is no active event detection policy by default, no events are logged.

• If your Session Recording is upgraded from a release earlier than 1811 that supports event detection but has the feature disabled before your upgrade, the related registry values on each Session Recording agent remain the default. Because there is no active event detection policy by default, no events are logged.

• If your Session Recording is upgraded from a release earlier than 1811 that supports event detection and has the feature partially or fully enabled before your upgrade, the related registry values on each Session Recording agent remain the same. Because there is no active event detection policy by default, the event detection behavior remains the same.

• If your Session Recording is upgraded from 1811, the event detection (logging) policies configured in the policy console remain in use.

Caution:

Activating the system-defined or a custom event detection policy means to ignore the relevant registry settings on each Session Recording agent. If you do so, you can’t use registry settings for event detection any more.