> Source: https://docs.cyberelements.io/bastion/4.6/Usage/Configuration/ConfigurationOfWindowsRecordingAgent/

# Configuring the Windows Recording Agent

The Windows recording agent is used by CyberElements Bastion 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](https://docs.cyberelements.io/bastion/4.6/CompatibilityMatrix/).

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 Bastion 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:
  > >
  > > ```
  > > 1
  > > ```
  > >
  > > 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 CyberElements Bastion 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:
  > >
  > > ```
  > >  1
  > >  2
  > >  3
  > >  4
  > >  5
  > >  6
  > >  7
  > >  8
  > >  9
  > > 10
  > > 11
  > > 12
  > > 13
  > > 14
  > > 15
  > > 16
  > > 17
  > > 18
  > > 19
  > > 20
  > > 21
  > > 22
  > > 23
  > > 24
  > > 25
  > > 26
  > > 27
  > > 28
  > > 29
  > > 30
  > > 31
  > > 32
  > > 33
  > > 34
  > > 35
  > > 36
  > > 37
  > > 38
  > > 39
  > > 40
  > > 41
  > > 42
  > > ```
  > >
  > > 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 Bastion 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](https://learn.microsoft.com/en-us/windows-hardware/customize/desktop/unattend/microsoft-windows-terminalservices-publishing-wmiprovider-fdisabledallowlist)). By default, a Windows machine only allows `explorer.exe` as a startup program.

```
1
2
```

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:

```
1
2
```

### 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 Bastion.
>
> 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) `client authentication` (OID: 1.3.6.1.5.5.7.3.2).
- The certificate must not be revoked.
- Constraints arising from [OpenSSL security level 2](https://docs.openssl.org/3.0/man3/SSL_CTX_set_security_level/#default-callback-behaviour) 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.

```
1
2
3
```

**`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:

```mermaid
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 End of 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
```

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 `FQDN` field: ![](https://docs.cyberelements.io/bastion/4.6/img/cyberelements/CYE_Gateway_Edit.png)

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:

```mermaid
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
```

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:

```
1
2
3
4
```

**`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](#registry-keys)) 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):

```
1
```

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

- CyberElements Bastion: `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:
>
> ```
> 1
> 2
> 3
> 4
> ```
>
> 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:
>
> ```
> 1
> 2
> 3
> 4
> 5
> ```

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

```
1
```

## 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](https://docs.cyberelements.io/bastion/4.6/Usage/Configuration/EdgeGateway/AddANewTrustedCertificationAuthority/#add-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.

```
1
```

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

```
1
```

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):
>
> ```
> 1
> 2
> 3
> 4
> ```
