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

# Configurazione dell'agente di registrazione Windows

L'agente di registrazione per Windows è utilizzato da CyberElements Bastion per aggiungere nuove funzionalità alle sessioni RDP:

- Possibilità di filtrare i flussi TCP e UDP accessibili all'utente
- Possibilità di avviare la registrazione della sessione per qualsiasi utente che si connette al server senza passare dal portale utente o dal client Desktop (funzionalità `direct access`)

Inoltre, durante le sessioni degli utenti vengono catturati eventi aggiuntivi:

- Apertura di finestre
- Chiusura di finestre
- Avvio di programmi
- Chiusura di programmi
- Contenuto degli appunti
- Attività dell'utente

## Prerequisiti

> **Compatibilità del client**
>
> Per sapere se l'agente è compatibile con i diversi sistemi operativi Microsoft Windows, consultare [la matrice di compatibilità](https://docs.cyberelements.io/bastion/4.6/it/CompatibilityMatrix/).

L'agente di registrazione richiede alcuni prerequisiti per funzionare correttamente. Alcuni riguardano soltanto la funzionalità di registrazione con agente delle applicazioni RDP e HTML5 RDP, altri l'accesso diretto con agente.

### Prerequisiti generali

L'agente di registrazione invia la registrazione della sessione dell'utente a CyberElements Bastion connettendosi all'Edge Gateway sulla porta `TCP 8443`. Per questo è necessario che il flusso di rete tra le due macchine sia aperto.

Per inviare la registrazione all'Edge Gateway in modo sicuro, l'agente di registrazione stabilisce con quest'ultimo una connessione sicura tramite TLS. TLS si basa sull'uso di certificati e, perché la connessione sia considerata affidabile e sicura, devono essere soddisfatti i vincoli seguenti:

- Il certificato del server, in questo caso l'Edge Gateway, non deve essere scaduto (data massima di validità).
- Il certificato del server, in questo caso l'Edge Gateway, deve essere emesso da un'autorità di certificazione riconosciuta come attendibile dalla macchina su cui è installato l'agente di registrazione.

  > **Informazioni aggiuntive**
  >
  > Il server su cui è installato l'agente di registrazione deve avere, come minimo, l'autorità di certificazione (CA) radice del certificato del server di registrazione nel proprio archivio locale delle autorità di certificazione attendibili.
  >
  > È quindi necessario:
  >
  > 1. Recuperare la CA radice del certificato del servizio di registrazione sull'Edge Gateway.
  > 2. Caricare questa CA sul server su cui è installato l'agente di registrazione.
  > 3. Installare la CA nell'archivio dei certificati «Trusted Root Certification Authorities» della macchina locale.
  >
  > > **Esempio con PowerShell**
  > >
  > > Un certificato in formato `.cer` può essere importato facilmente tramite PowerShell.
  > > A tale scopo, aprire un terminale PowerShell come amministratore della macchina ed eseguire il comando seguente:
  > >
  > > ```
  > > 1
  > > ```
  > >
  > > Sostituire `<PATH_TO_CERT>` con il percorso del file del certificato.
  >
  > > **Esempio con PowerShell per il certificato Systancia, senza inviare file**
  > >
  > > Questo esempio consiste nell'installare la CA radice di Systancia, utilizzata dai client CyberElements Bastion che impiegano certificati forniti da Systancia.
  > >
  > > È inoltre possibile importare il certificato senza dover inviare o scaricare il file sulla macchina su cui è installato l'agente di registrazione.
  > > A tale scopo, aprire un terminale PowerShell come amministratore della macchina ed eseguire i comandi seguenti:
  > >
  > > ```
  > >  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
  > > ```
  > >
  > > Per utilizzare questo metodo con un'altra CA, modificare il valore della variabile `base64Cert` con il certificato desiderato codificato in base 64.
- Il certificato del server, in questo caso l'Edge Gateway, non deve essere revocato.
- La macchina su cui è installato l'agente di registrazione deve poter contattare il server, in questo caso l'Edge Gateway, con un nome DNS o un indirizzo IP coperto dal certificato del server tramite il suo Common Name (CN).

### Prerequisiti specifici delle applicazioni RDP con agente utilizzate su una postazione utente macOS o Ubuntu

> **Attenzione**
>
> I prerequisiti seguenti sono necessari solo se l'utente avvia un'applicazione RDP con agente e la sua postazione non è Windows (macOS o Ubuntu).
>
> Se gli utenti di CyberElements Bastion hanno postazioni esclusivamente Windows oppure, in mancanza, utilizzano esclusivamente applicazioni HTML5 RDP, i prerequisiti seguenti possono essere ignorati.

Le chiavi di registro seguenti sono necessarie sul server di destinazione su cui è distribuito l'agente di registrazione.

In primo luogo, la prima chiave disabiliterà l'elenco dei programmi di avvio autorizzati ([documento Microsoft](https://learn.microsoft.com/en-us/windows-hardware/customize/desktop/unattend/microsoft-windows-terminalservices-publishing-wmiprovider-fdisabledallowlist)). Per impostazione predefinita, una macchina Windows autorizza solo `explorer.exe` come programma di avvio.

```
1
2
```

Se la macchina non è un server RDS, si raccomanda comunque di applicare sempre la chiave di registro seguente, per permettere all'agente di registrazione di aprirsi come programma di avvio:

```
1
2
```

### Requisiti specifici dell'accesso diretto

> **Funzionalità di accesso diretto**
>
> La funzionalità di accesso diretto permette di avviare una registrazione della sessione dell'utente per gli accessi RDP o console (connessione fisica alla macchina o tramite la modalità console dell'hypervisor) che non passano direttamente da CyberElements Bastion.
>
> Se l'utente ha l'autorizzazione ad accedere al server, la sua sessione verrà registrata. In caso contrario, per impostazione predefinita l'utente verrà disconnesso.

Perché l'agente di registrazione funzioni in modalità di accesso diretto è necessario un certificato x509. Questo certificato deve soddisfare i requisiti seguenti:

- Il certificato deve essere ancora valido (periodo di validità non scaduto).
- Il certificato deve essere di tipo (campo di utilizzo avanzato della chiave) `client authentication` (OID: 1.3.6.1.5.5.7.3.2).
- Il certificato non deve essere revocato.
- I vincoli derivanti dal [livello di sicurezza 2 di OpenSSL](https://docs.openssl.org/3.0/man3/SSL_CTX_set_security_level/#default-callback-behaviour) implicano che:
    - Il certificato deve avere una chiave privata di almeno 2048 bit con i cifrari RSA, DSA e DH; per le chiavi a curva ellittica (ECC) devono essere di almeno 224 bit.
    - La firma del certificato non deve essere MD5 o SHA-1 (è preferibile SHA-512).
- Il server di registrazione utilizzerà il campo `Common Name` (CN) per identificare il certificato e quindi la macchina su cui viene avviata una registrazione diretta. Questo campo deve essere compilato.

## Configurazioni mediante chiavi di registro

Alcune impostazioni globali sono disponibili nelle chiavi di registro e influiscono sul funzionamento dell'agente di registrazione, sia quando è utilizzato con le applicazioni sia in accesso diretto.

```
1
2
3
```

**`DisconnectOnError`**

Definisce il comportamento dell'agente di registrazione alla chiusura del registratore di sessione. Se è indicato il valore `0` (comportamento predefinito), alla chiusura del registratore la sessione dell'utente viene chiusa. Se è indicato il valore `1`, alla chiusura del registratore la sessione dell'utente viene disconnessa.

**`SessionEndTimeout`**

Definizione del tempo (in secondi) di chiusura della sessione dell'utente prima che ne venga forzato l'arresto. Per impostazione predefinita questo parametro è di 10 secondi.

## Configurazione per il funzionamento con applicazioni RDP e RDP HTML5

In questa modalità di funzionamento, gli scambi tra il Mediation Controller, l'Edge Gateway e l'agente di registrazione sono i seguenti:

```mermaid
sequenceDiagram
    autonumber
    participant MED as Mediation Controller
    participant GW as Edge Gateway
    participant AGENT as Server RDP<br/>Agente di registrazione

    MED->>+GW: Invio delle informazioni di connessione verso <br/>il server RDP con le informazioni di <br/>connessione per l'agente di registrazione
    GW->>AGENT: Inizializzazione della connessione RDP
    GW->>-AGENT: Invio delle informazioni di connessione al <br/>servizio di registrazione dell'Edge Gateway
    AGENT->>+GW: Connessione al servizio di registrazione
    GW->>-AGENT: Invio delle informazioni di filtraggio di rete
    Note over AGENT: Applicazione delle restrizioni <br/>di rete all'utente
    loop Registrazione continua della sessione
        AGENT->>+GW: Invio continuo della registrazione video <br/>+ eventi di sessione
        Note over GW: Aggiunta continua della registrazione video <br/>nella directory di archiviazione temporanea
        GW->>-MED: Invio degli eventi di sessione ricevuti
        Note over MED: Registrazione degli eventi <br/>nel database dell'organizzazione
    end
    break Fine della sessione
        AGENT->>GW: Invio dell'informazione che <br/>l'utente ha terminato la propria sessione RDP
        Note over GW: La registrazione video viene spostata <br/>nella directory di archivio
        GW->>MED: Segnalazione della fine della sessione dell'utente
        Note over MED: La sessione dell'utente passa <br/>dallo streaming live all'archivio
    end
```

1. Il Mediation Controller trasmette all'Edge Gateway le informazioni di connessione al server RDP di destinazione. Include inoltre le informazioni di connessione di cui dispone per connettersi al servizio di registrazione (FQDN dell'Edge Gateway).
2. L'Edge Gateway inizializza la connessione al server RDP.
3. L'Edge Gateway invia all'agente di registrazione le informazioni di connessione al proprio servizio di registrazione.
4. L'agente di registrazione inizializza la connessione con il servizio di registrazione.
5. Una volta connesso l'agente, il servizio di registrazione gli restituisce l'elenco delle restrizioni di flusso di rete da applicare alla sessione. Una volta ricevuto, l'agente di registrazione le applica alla sessione dell'utente.
6. L'agente di registrazione invia in modo continuo e in tempo reale la registrazione video della sessione dell'utente e tutti gli eventi della sessione (per esempio le digitazioni o gli avvii di programmi) al servizio di registrazione. Il servizio di registrazione memorizza la registrazione video in una directory temporanea.
7. Il servizio di registrazione comunica i vari eventi della sessione al Mediation Controller, che li registra poi nel database dell'organizzazione.
8. Quando la sessione RDP dell'utente termina, l'agente di registrazione lo comunica al servizio di registrazione. Il servizio di registrazione sposta quindi il video registrato nella directory di archiviazione delle registrazioni utente.
9. Il servizio di registrazione comunica la fine della sessione dell'utente al Mediation Controller. La sessione non è quindi più visibile nel Live streaming del Control Center ma passa agli Archives.

Con questa sequenza è indispensabile che l'agente di registrazione riceva le informazioni di connessione corrette al servizio di registrazione dell'Edge Gateway. Queste informazioni figurano nelle impostazioni dell'Edge Gateway, nel campo `FQDN`: ![](https://docs.cyberelements.io/bastion/4.6/img/cyberelements/CYE_Gateway_Edit.png)

In questo campo, indicare un nome DNS che i server RDP siano in grado di risolvere.

> **Importante**
>
> Il certificato assegnato al servizio di registrazione `Careserver` deve coprire il nome indicato nel campo `FQDN`. In caso contrario, l'agente di registrazione considererà la connessione non sicura e non attiverà la registrazione della sessione.

## Configurazione per il funzionamento in accesso diretto

In questa modalità di funzionamento, gli scambi tra il Mediation Controller, l'Edge Gateway e l'agente di registrazione sono i seguenti:

```mermaid
sequenceDiagram
    autonumber
    participant MED as Mediation Controller
    participant GW as Edge Gateway
    participant AGENT as Server RDP<br/>Agente di registrazione

    Note over AGENT: Rilevamento di una nuova <br/>sessione da registrare
    AGENT->>+GW: Connessione al servizio di registrazione
    GW->>-MED: Segnalazione di una nuova connessione <br/>con accesso diretto per l'utente X
    alt Se l'utente X è autorizzato
        MED->>+GW: Invio dell'informazione che l'utente X <br/>è autorizzato a connettersi e invio <br/>dell'elenco dei filtri di rete da applicare
        GW->>-AGENT: Invio delle informazioni di filtraggio <br/>di rete e dell'autorizzazione di connessione <br/>per l'utente X
        Note over AGENT: Applicazione delle restrizioni <br/>di rete all'utente X
        loop Registrazione continua della sessione
            AGENT->>+GW: Invio continuo della registrazione video <br/>+ eventi di sessione
            Note over GW: Aggiunta continua della registrazione video <br/>nella directory di archiviazione temporanea
            GW->>-MED: Invio degli eventi di sessione ricevuti
            Note over MED: Registrazione degli eventi <br/>nel database dell'organizzazione
        end
        break Fine della sessione
            AGENT->>GW: Invio dell'informazione che <br/>l'utente X ha terminato la propria sessione RDP
            Note over GW: La registrazione video viene spostata <br/>nella directory di archivio.
            GW->>MED: Segnalazione della fine della sessione dell'utente
            Note over MED: La sessione dell'utente passa <br/>dallo streaming live all'archivio
        end
    else If user X is not authorized
        MED->>+GW: Invio dell'informazione che l'utente <br/>X non è autorizzato a connettersi
        GW->>-AGENT: Invio della notifica di <br/>rifiuto di connessione dell'utente X
        Note over AGENT: Disconnessione dell'utente X
    end
```

1. L'agente di registrazione rileva una nuova sessione e avvia una connessione al servizio di registrazione di un Edge Gateway.
2. L'Edge Gateway invia le informazioni di connessione (nome utente e CN del certificato utilizzato dall'agente di registrazione) al Mediation Controller. Il Mediation Controller risponderà in due modi diversi a seconda della configurazione dei diritti di accesso.
3. Se l'utente è autorizzato a connettersi al server, il Mediation Controller comunica all'Edge Gateway l'accesso possibile per questo utente e l'elenco dei filtri di rete da applicare.
4. L'Edge Gateway restituisce queste informazioni all'agente di registrazione. Una volta ricevute, l'agente di registrazione applica i filtri di rete alla sessione dell'utente.
5. L'agente di registrazione invia in modo continuo e in tempo reale la registrazione video della sessione dell'utente e tutti gli eventi della sessione (per esempio le digitazioni o gli avvii di programmi) al servizio di registrazione. Il servizio di registrazione memorizza la registrazione video in una directory temporanea.
6. Il servizio di registrazione comunica i vari eventi della sessione al Mediation Controller, che li registra poi nel database dell'organizzazione.
7. Quando la sessione RDP dell'utente termina, l'agente di registrazione lo comunica al servizio di registrazione. Il servizio di registrazione sposta quindi il video registrato nella directory di archiviazione delle registrazioni utente.
8. Il servizio di registrazione comunica la fine della sessione dell'utente al Mediation Controller. La sessione non è quindi più visibile nel Live streaming del Control Center ma passa agli Archives.
9. Se l'utente non è autorizzato a connettersi al server, il Mediation Controller comunica all'Edge Gateway che l'accesso non è autorizzato per tale utente.
10. L'Edge Gateway trasmette l'informazione all'agente di registrazione, che disconnette la sessione dell'utente.

### Chiavi di registro

Indipendentemente dalla modalità di installazione, l'agente di registrazione dispone di tutti i componenti necessari a tutte le modalità di funzionamento previste. Pertanto, per funzionare in modalità di accesso diretto, legge le seguenti chiavi di registro al fine di determinare la propria configurazione:

```
1
2
3
4
```

**`MachineName`**

Nome del certificato che l'agente di registrazione utilizzerà per connettersi al servizio di registrazione di un Edge Gateway. Per impostazione predefinita, e se non è definito, l'agente tenterà di utilizzare un certificato con il nome della macchina.

**`LogOffOnFailure`**

Indicazione del comportamento dell'agente quando non riesce a connettersi a un Edge Gateway o quando l'utente non è autorizzato a connettersi alla macchina. Con `0` non si produce alcuna disconnessione; con `1` l'utente verrà disconnesso (comportamento predefinito).

**`RecordedSessions`**

Definizione dei tipi di sessione sottoposti a registrazione:

- `none` : non verrà effettuata alcuna registrazione degli accessi diretti (configurazione predefinita).
- `remote` : qualsiasi accesso RDP alla macchina attiverà una registrazione.
- `all` : gli accessi RDP e gli accessi da console (accesso fisico alla macchina o dalla modalità console dell'hypervisor) attiveranno la registrazione.

> **Quali valori di chiave sono necessari per l'accesso diretto?**
>
> Il solo valore di chiave necessario per attivare il meccanismo di accesso diretto è `RecordedSessions`, con il valore `remote` o `all`. Si noti che, a seconda dell'ambiente, può essere necessario anche il valore di chiave `MachineName`.

### Certificato di macchina

L'agente di registrazione tenterà di utilizzare un certificato per l'autenticazione presso il servizio di registrazione. Questo certificato deve essere stato installato nei certificati personali del computer.

L'agente utilizza il certificato il cui nome corrisponde al valore della chiave `MachineName` (vedere il [capitolo precedente](#registry-keys)) e, se non è definito, tenta di utilizzare un certificato con il nome della macchina.

### Dichiarazione degli Edge Gateway che l'agente può contattare

L'agente di registrazione utilizza informazioni locali per determinare l'elenco dei server Edge Gateway da contattare per caricare le registrazioni delle sessioni degli utenti.

Per modificare l'elenco dei server Edge Gateway che è possibile contattare, occorre prima arrestare il servizio `CleanroomAgent`.

> **Attenzione!**
>
> L'arresto del servizio `CleanroomAgent` comporta la fine della registrazione delle sessioni in corso sul server e le nuove sessioni aperte sul server non vengono registrate.

Il servizio può essere arrestato tramite PowerShell (sono necessari i diritti di amministratore):

```
1
```

Dopo aver arrestato il servizio, modificare o creare il file `[RECORDING_AGENT_DIR]\gateways.xml` seguente, dove `[RECORDING_AGENT_DIR]` è la directory di installazione dell'agente di registrazione. Con la directory di installazione predefinita, il file deve essere presente o creato in questa posizione:

- CyberElements Bastion: `C:\Program Files (x86)\Systancia\Safe\gateways.xml`

Questo file XML è composto da un tag `gateways` e da tanti tag `element` quanti sono gli Edge Gateway che è possibile contattare.

> **Esempio**
>
> Se l'agente di registrazione deve contattare un Edge Gateway il cui FQDN è `edge-gateway-1.domain.local`, il file XML sarebbe il seguente:
>
> ```
> 1
> 2
> 3
> 4
> ```
>
> Se invece gli Edge Gateway da contattare fossero due, `edge-gateway-1.domain.local` e `edge-gateway-2.domain.local`, il file sarebbe il seguente:
>
> ```
> 1
> 2
> 3
> 4
> 5
> ```

Dopo aver modificato correttamente il file `gateways.xml`, riavviare il servizio `CleanroomAgent`:

```
1
```

## Configurare il servizio di registrazione per autenticare i certificati di una PKI di terze parti

Per impostazione predefinita, il servizio di registrazione considera validi solo i certificati emessi dalla PKI di Systancia. Per utilizzare certificati di un'altra autorità di certificazione (CA), occorre seguire i passaggi per [aggiungere una CA alla directory specifica dell'Edge Gateway](https://docs.cyberelements.io/bastion/4.6/it/Usage/Configuration/EdgeGateway/AddANewTrustedCertificationAuthority/#add-to-the-edge-gateway-specific-directory).

Una volta che i certificati CA si trovano nella posizione corretta, non resta che riavviare il servizio di registrazione, sempre come superutente `root`:

> **Attenzione!**
>
> Il riavvio di questo servizio interrompe le sessioni in corso e ne termina la quasi totalità. Eseguire il comando seguente solo quando nessuna sessione utente passa attraverso l'Edge Gateway, per non avere impatti sugli utenti.

```
1
```

Dopo aver riavviato il servizio di registrazione, è possibile verificare che le nuove CA siano state prese correttamente in considerazione consultando i log del servizio:

```
1
```

I log ottenuti indicano alla fine della riga i nomi dei file di certificato caricati dal servizio di registrazione.

> **Esempio**
>
> Dopo aver aggiunto due CA denominate `MY-CA-ROOT.pem` e `MY-INTERMEDIATE-CA.pem`, i log ottenuti hanno questo aspetto (l'inizio del log è stato troncato, ma contiene, tra l'altro, la data e il nome della macchina):
>
> ```
> 1
> 2
> 3
> 4
> ```
