Configuring the Windows Recording Agent

The Windows recording agent is used by cyberelements.io / cyberelements Cleanroom to add new features for RDP sessions:

• Ability to filter TCP and UDP streams accessible by the user
• Ability to trigger session recording for any user connecting to the server without going through the user portal or Desktop client (direct access feature)

In addition, additional events are captured during user sessions:

• Window opening
• Window closing
• Program launch
• Program closing
• Clipboard contents
• User activity

Prerequisites

Client compatibility

To find out whether the agent is compatible with different Microsoft Windows operating systems, refer to the compatibility matrix.

The recording agent requires a few prerequisites to function properly. Some of these are only intended for agent-based recording functionality for RDP and HTML5 RDP applications, while others concern direct agent-based access.

General prerequisites

The recording agent sends the user session recording back to cyberelements.io and cyberelements Cleanroom by connecting to the Edge Gateway on port TCP 8443. This requires the network flow between the two machines to be open.

To securely send the recording back to the Edge Gateway, the recording agent establishes a secure connection with the latter using TLS. TLS relies on the use of certificates, and the following constraints must be validated for the connection to be considered reliable and secure:

• The server certificate, in this case the Edge Gateway, must not have expired (maximum validity date).

• The server certificate, in this case the Edge Gateway, must be issued by a certification authority recognized as trustworthy by the machine on which the recording agent is installed.

  Additional information

  The server on which the recording agent is installed must have, at a minimum, the root certification authority (CA) of the recording server certificate in its local store of trusted certification authorities.

  It is therefore necessary to:

  1. Retrieve the root CA of the certificate from the recording service on the Edge Gateway.
  2. Upload this CA to the server where the recording agent is installed.
  3. Install the CA in the “Trusted Root Certification Authorities” certificate store on the local machine.

  Example with PowerShell

  You can easily import a certificate in .cer format via PowerShell.
  To do this, open a PowerShell terminal as the machine administrator and run the following command:

  Import-Certificate -FilePath "<PAHT_TO_CERT>" -CertStoreLocation "Cert:\LocalMachine\Root"
  

  Replace <PATH_TO_CERT> with the path to the certificate file.

  Example with PowerShell for the Systancia certificate without sending files

  This example involves installing the Systancia root CA, which is used by default on cyberelements.io or for cyberelements Cleanroom clients using certificates provided by Systancia.

  It is also possible to import the certificate without having to send/download the file to the machine where the recording agent is installed.
  To do this, open a PowerShell terminal as the machine administrator and run the following commands:

  # Systancia Root certificate
  $base64Cert = "MIIFIDCCBAigAwIBAgIBADANBgkqhkiG9w0BAQUFADCBjTELMAkGA1UEBhMCRlIx
  FDASBgNVBAoTC0lQZGl2YSBSb290MR0wGwYDVQQLExRJUGRpdmEgU2VjdXJpdHkg
  RGVwdDEqMCgGA1UEAxMhSVBkaXZhIFJvb3QgQ2VydGlmaWNhdGUgQXV0aG9yaXR5
  MR0wGwYJKoZIhvcNAQkBFg5wa2lAaXBkaXZhLmNvbTAeFw0wNTA4MjIxNTAwMzla
  Fw0zMDA4MjIxNTAwMzlaMIGNMQswCQYDVQQGEwJGUjEUMBIGA1UEChMLSVBkaXZh
  IFJvb3QxHTAbBgNVBAsTFElQZGl2YSBTZWN1cml0eSBEZXB0MSowKAYDVQQDEyFJ
  UGRpdmEgUm9vdCBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkxHTAbBgkqhkiG9w0BCQEW
  DnBraUBpcGRpdmEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA
  ua59tx+RkIPZbGaSwkV0w5fuPBpY3sbLTk/eR2uN7j9zMu0pq38LfibCVsNGlifh
  GfT5CEbrNL7KvlEVY/It1QluYxNgknlcBP1roJG/xHNcUNmbvCFYLy9N3Nd0J/gC
  Vd8tdB4exqyKEoNuqX18rLpSJJOUZdQCeGdF9r+w6vmHdRMeVS44qIiBPv9Bxzgf
  GXBxAlSqfuDDJ3eZEMsWF/kJrbm4Uhav2ACl5qjHgSSTKMoGoEWOJNkB7Mq/khxc
  TnixIpM2s1rpEfhIetPo4BHsyKv7wqWrS6ouwu5AbzT5t3UqaN77CLqcZJGQ3vC0
  IGKBuEcwigd7W6qkX1/XMwIDAQABo4IBhzCCAYMwDwYDVR0TAQH/BAUwAwEB/zAd
  BgNVHQ4EFgQU+lu7XBGohR2DKD+D+abZEODRHjkwgboGA1UdIwSBsjCBr4AU+lu7
  XBGohR2DKD+D+abZEODRHjmhgZOkgZAwgY0xCzAJBgNVBAYTAkZSMRQwEgYDVQQK
  EwtJUGRpdmEgUm9vdDEdMBsGA1UECxMUSVBkaXZhIFNlY3VyaXR5IERlcHQxKjAo
  BgNVBAMTIUlQZGl2YSBSb290IENlcnRpZmljYXRlIEF1dGhvcml0eTEdMBsGCSqG
  SIb3DQEJARYOcGtpQGlwZGl2YS5jb22CAQAwCwYDVR0PBAQDAgEGMBkGA1UdEQQS
  MBCBDnBraUBpcGRpdmEuY29tMBkGA1UdEgQSMBCBDnBraUBpcGRpdmEuY29tMBEG
  CWCGSAGG+EIBAQQEAwIABzA+BglghkgBhvhCAQ0EMRYvSVBkaXZhIFJvb3QgQ2Vy
  dGlmaWNhdGlvbiBBdXRob3JpdHkgQ2VydGlmaWNhdGUwDQYJKoZIhvcNAQEFBQAD
  ggEBACaAgBQK7TATXieb9OdKm+l7/GpePo8f2bRKnkqeRS+HXBKYkvqVJdbJnhJm
  YPOdmhr9ATzt+488tQREAGzqPCp5eiVExPgvomNeG77X57KqbgCA1F7zGJqjP1FL
  771FIWvFXp80ReM/zhcM+MY3sa5LADgOEl5NhoMNHT8AhLKwZ81j5nuwxyG9ICCN
  5GjwgsnK/agmum4+RKeybIWuC/JTsSnu5OImXsmrlUiakp2l+VsZ1rRRNRNUlSbg
  Q3T8kj5ajB0lv2I0kj4fN9wDxzdHEn7nEAmv0t6Y5Te0g/VK3VWhuqeLStaahgip
  hmOVxbu5Ijfug5/3Eemep34NsYk="
  
  # Convert the certificate and store it in memory
  $certBytes = [Convert]::FromBase64String($base64Cert)
  
  # Create a certificate object
  $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
  $cert.Import($certBytes)
  
  # Open the trusted root certificate store on the local machine and add the Systancia root certificate
  $store = New-Object System.Security.Cryptography.X509Certificates.X509Store("Root", "LocalMachine")
  $store.Open([System.Security.Cryptography.X509Certificates.OpenFlags]::ReadWrite)
  $store.Add($cert)
  $store.Close()
  

  To use this method with another CA, please change the value of the base64Cert variable to the base 64-encoded certificate of your choice.

• The server certificate, in this case the Edge Gateway, must not be revoked.

• The machine on which the recording agent is installed must be able to contact the server, in this case the Edge Gateway, with a DNS name or IP address that is covered by the server certificate via its Common Name (CN).

Specific prerequisites for RDP applications with agents used on a macOS or Ubuntu user workstation

Warning

The following prerequisites are only necessary if the user launches an RDP application with an agent and their workstation is not Windows (macOS or Ubuntu).

If cyberelements.io or cyberelements Cleanroom users have workstations exclusively running Windows or, if not, exclusively use HTML5 RDP applications, then the following prerequisites can be ignored.

The following registry keys are required on the target server where the recording agent is deployed.

First, the first key will disable the list of authorized startup programs (Microsoft document). By default, a Windows machine only allows explorer.exe as a startup program.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Terminal Server\TSAppAllowList]
"fDisabledAllowList"=dword:00000001

If the machine is not an RDS server, then applying the following registry key is always recommended in order to allow the recording agent to open as a startup program:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal Server]
"HonorLegacySettings"=dword:00000001

Specific requirements for direct access

Direct access feature

The direct access feature allows you to trigger a recording of the user's session for RDP or console access (physical connection to the machine or via the hypervisor's console mode) that does not go directly through cyberelements.io or cyberelements Cleanroom.

If the user has permission to access the server, their session will be recorded. If this is not the case, then by default, the user will be disconnected.

For the recording agent to operate in direct access mode, an x509 certificate is required. This certificate must meet the following requirements:

• The certificate must still be valid (validity period not expired).
• The certificate must be of the type (advanced key usage field) authentification du client (OID: 1.3.6.1.5.5.7.3.2).
• The certificate must not be revoked.
• Constraints arising from OpenSSL security level 2 imply that:
  • The certificate must have a private key of at least 2048 bits with RSA, DSA, and DH ciphers; for elliptic curve keys (ECC), they must be at least 224 bits.
  • The certificate signature must not be MD5 or SHA-1 (SHA-512 is preferred).
• The recording server will use the Common Name (CN) field to identify the certificate and therefore the machine where a direct recording is triggered. This field must be completed.

Configurations via registry keys

Some global settings are available in registry keys to affect the operation of the recording agent both when used with applications and in direct access.

[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\IpdivaSafe]
"DisconnectOnError"=dword:00000000
"SessionEndTimeout"=dword:0000000a

DisconnectOnError

Defines the behavior of the recording agent when the session recorder is closed. If the value 0 is specified (default behavior), then when the recorder is closed, the user's session will be closed. If the value 1 is specified, then the user's session will be disconnected when the recorder is closed.

SessionEndTimeout

Definition of the time (in seconds) for closing the user session before a forced session shutdown is performed. By default, this parameter is set to 10 seconds.

Configuration for operation with RDP and HTML5 RDP applications

In this operating mode, exchanges between the Mediation Controller, the Edge Gateway, and the recording agent are as follows:

sequenceDiagram
    autonumber
    participant MED as Mediation Controller
    participant GW as Edge Gateway
    participant AGENT as RDP Server<br/>Recording Agent

    MED->>+GW: Sending login information to <br/>the RDP server with login information <br/>for the recording agent
    GW->>AGENT: Initializing the RDP connection
    GW->>-AGENT: Sending login information to the <br/>Edge Gateway recording service
    AGENT->>+GW: Connecting to the recording service
    GW->>-AGENT: Sending network filtering information
    Note over AGENT: Applying network <br/>restrictions to the user
    loop Continuous session recording
        AGENT->>+GW: Continuous sending of video recording <br/>+ session events
        Note over GW: Continuous addition of video recording <br/>to the temporary storage directory
        GW->>-MED: Sending of received session events
        Note over MED: Recording of events <br/>in the organization's database
    end 
    break Fin de session
        AGENT->>GW: Sending information that <br/>the user has ended their RDP session
        Note over GW: The video recording is moved <br/>to the archive directory
        GW->>MED: Indication of the end of the user's session
        Note over MED: The user's session switches <br/>from live streaming to the archive
    end

Hold "Ctrl" to enable pan & zoom

1. The Mediation Controller provides the Edge Gateway with the connection information for the target RDP server. It also includes the connection information it has for connecting to the recording service (FQDN of the Edge Gateway).
2. The Edge Gateway initializes the connection to the RDP server.
3. The Edge Gateway sends the connection information for its recording service to the recording agent.
4. The recording agent initializes the connection with the recording service.
5. Once the agent is connected, the recording service returns the list of network flow restrictions to be applied to the session. Once received, the recording agent applies them to the user's session.
6. The recording agent continuously uploads the video recording of the user's session and all session events (e.g., keystrokes or program launches) to the recording service in real time. The recording service stores the video recording in a temporary directory.
7. The recording service reports the various session events to the Mediation Controller, which then records them in the organization's database.
8. When the user's RDP session ends, the recording agent reports the information to the recording service. The recording service then moves the recorded video to the user recording archive directory.
9. The recording service reports the end of the user's session to the Mediation Controller. The session is therefore no longer visible in the Control Center's Live Streaming but switches to the Archives.

With this sequence, it is essential that the recording agent receives the correct connection information for the Edge Gateway recording service. This information is contained in the Edge Gateway settings in the FDQN field:

In this field, enter a DNS name that the RDP servers will be able to resolve.

Important

The certificate assigned to the Careserver recording service must cover the name specified in the FQDN field. Otherwise, the recording agent will consider the connection to be unsafe and will not trigger session recording.

Configuration for direct access operation

In this operating mode, exchanges between the Mediation Controller, the Edge Gateway, and the recording agent are as follows:

sequenceDiagram
    autonumber
    participant MED as Mediation Controller
    participant GW as Edge Gateway
    participant AGENT as RDP Server<br/>Recording Agent

    Note over AGENT: Detection of a new <br/>session to be recorded
    AGENT->>+GW: Connecting to the recording service
    GW->>-MED: Indication of a new connection <br/>with direct access for user X
    alt If user X is authorized  
        MED->>+GW: Send information that user X <br/>is authorized to connect and send <br/>the list of network filters to apply
        GW->>-AGENT: Send network filtering information <br/>and connection authorization <br/>for user X
        Note over AGENT: Application of network <br/>restrictions to user X
        loop Continuous session recording
            AGENT->>+GW: Continuous sending of video recording <br/>+ session events
            Note over GW: Continuous addition of video recording <br/>to the temporary storage directory
            GW->>-MED: Sending of received session events
            Note over MED: Recording of events <br/>in the organization's database
        end 
        break End of session
            AGENT->>GW: Sending information that <br/>user X has ended their RDP session
            Note over GW: The video recording is moved <br/>to the archive directory.
            GW->>MED: Indication of the end of the user's session
            Note over MED: The user's session switches <br/>from live streaming to the archive
        end
    else If user X is not authorized
        MED->>+GW: Send information that user <br/>X is not authorized to log in
        GW->>-AGENT: Send notification of <br/>user X's login denial
        Note over AGENT: Log out user X
    end

Hold "Ctrl" to enable pan & zoom

1. A new session is detected by the recording agent, which initiates a connection to the recording service of an Edge Gateway.
2. The Edge Gateway sends the connection information (username and CN of the certificate used by the recording agent) to the Mediation Controller. The Mediation Controller will respond in two different ways depending on the access rights settings.
3. If the user is authorized to connect to the server, the Mediation Controller reports back to the Edge Gateway the possible access for this user and the network filter list to be applied.
4. The Edge Gateway returns this information to the recording agent. Once received, the recording agent applies the network filters to the user's session.
5. The recording agent continuously uploads the video recording of the user's session and all session events (e.g., keystrokes or program launches) to the recording service in real time. The recording service stores the video recording in a temporary directory.
6. The recording service reports the various session events to the Mediation Controller, which then records them in the organization's database.
7. When the user's RDP session ends, the recording agent reports the information to the recording service. The recording service then moves the recorded video to the user recording archive directory.
8. The recording service reports the end of the user's session to the Mediation Controller. The session is therefore no longer visible in the Control Center's Live Streaming but switches to the Archives.
9. If the user is not authorized to connect to the server, the Mediation Controller reports the unauthorized access for that user to the Edge Gateway.
10. The Edge Gateway forwards the information to the recording agent, which disconnects the user's session.

Registry keys

Regardless of how it is installed, the recording agent has all the components necessary for all of its intended modes of operation. Therefore, in order to operate in direct access mode, it reads the following registry keys to determine its configuration:

[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\IpdivaSafe]
"MachineName"="my-rdp-server.domain.local"
"LogOffOnFailure"=dword:00000001
"RecordedSessions"="none"

MachineName

Name of the certificate that the recording agent will use to connect to the recording service of an Edge Gateway. By default, and if not defined, the agent will attempt to use a certificate with the name of the machine.

LogOffOnFailure

Indication of the agent's behavior when it cannot connect to an Edge Gateway or if the user is not authorized to connect to the machine. If 0, no disconnection will occur, whereas with 1 the user will be disconnected (default behavior).

RecordedSessions

Definition of session types constrained by recording:

• none : no direct access recording will be performed (default setting).
• remote : any RDP access to the machine will trigger a recording.
• all : RDP access and console access (physical access to the machine or from the hypervisor console mode) will trigger recording.

What key values are required for direct access?

The only key value required to enable the direct access mechanism is RecordedSessions with a value of remote or all. Note that depending on the environment, the MachineName key value may also be required.

Machine certificate

The recording agent will attempt to use a certificate for authentication with the recording service. This certificate must have been installed in the computer's personal certificates.

The agent will use the certificate whose name corresponds to the key value MachineName (see previous chapter) and if it is not defined, it will attempt to use a certificate with the name of the machine.

Declaration of Edge Gateways that the agent can contact

The recording agent uses local information to determine the list of Edge Gateway servers to contact in order to upload user session recordings.

To modify the list of Edge Gateway servers that can be contacted, you must first stop the CleanroomAgent service.

Warning!

Stopping the CleanroomAgent service causes the recording of current sessions on the server to end, and any new sessions opened on the server will not be recorded.

The service can be stopped via PowerShell (administrator rights required):

Stop-Service CleanroomAgent

After stopping the service, modify or create the following [RECORDING_AGENT_DIR]\gateways.xml file [RECORDING_AGENT_DIR] where is the installation directory of the recording agent. With the default installation directory, the file must be present or created at this location:

• cyberelements.io: C:\Program Files (x86)\Systancia\cyberelements\gateways.xml
• cyberelements Cleanroom: C:\Program Files (x86)\Systancia\Safe\gateways.xml

This XML file consists of a gateways tag and as many element tags as there are Edge Gateways that can be contacted.

Example

If the recording agent needs to contact an Edge Gateway with its FQDN edge-gateway-1.domain.local, the XML file would be as follows:

<?xml version="1.0"?>
<gateways>
    <element>edge-gateway-1.domain.local</element>
</gateways>

But if there were two Edge Gateways to contact, edge-gateway-1.domain.local and edge-gateway-2.domain.local, the file would be as follows:

<?xml version="1.0"?>
<gateways>
    <element>edge-gateway-1.domain.local</element>
    <element>edge-gateway-2.domain.local</element>
</gateways>

After correctly modifying the gateways.xml file, restart the CleanroomAgent service:

Start-Service CleanroomAgent

Configuring the recording service to authenticate certificates from a third-party PKI

By default, the recording service only considers certificates issued by the Systancia PKI to be valid. In order to use certificates from another Certification Authority (CA), you must follow the steps for adding a CA to the Edge Gateway specific directory.

Once the CA certificate(s) are in the correct location, all that remains is to restart the recording service, again as superuser root:

Warning!

Restarting this service will stop current sessions and terminate almost all of them. Only execute the following command when no user sessions are passing through the Edge Gateway so as not to impact users.

systemctl restart ipdivacarerecord

After restarting the recording service, you can check that the new CAs have been correctly taken into account by consulting the service logs:

journalctl -xeu ipdivacarerecord -g loadCaDir -S today

The logs obtained will indicate at the end of the line the names of the certificate files that have been loaded by the recording service.

Example

After adding two CAs named MY-CA-ROOT.pem and MY-INTERMEDIATE-CA.pem. The logs obtained will look like this (the beginning of the log has been truncated but it contains, among other things, the date and the name of the machine):

TRACE tls.TLS.Context.loadCaDir load ca file: MY-CA-ROOT.pem
TRACE tls.TLS.Context.loadCaDir load ca file: MY-INTERMEDIATE-CA.pem
TRACE tls.TLS.Context.loadCaDir load ca file: oldIPdiva_-928617624.pem
TRACE tls.TLS.Context.loadCaDir load ca file: newIPdiva_1957857431.pem