# Azioni remote

Isolare un dispositivo, modificarne la registrazione MFA, associarne l'utente ed eseguire comandi sui dispositivi tramite l'API di gestione.

Requires: Device Identity (DIAM)

> **Add-on richiesto:** le azioni remote richiedono l'add-on **DIAM** (Device Identity) con la funzionalità **deviceTrust**.

Su un dispositivo connesso è possibile intervenire dalla console. Le azioni seguenti costituiscono la parte di risposta agli incidenti dell'inventario dei dispositivi: consentono di contenere una macchina, modificare ciò che richiede all'accesso o correggere a chi appartiene, senza intervenire fisicamente su di essa.

## Azioni nella console

Aprire un dispositivo nell'[inventario dei dispositivi](https://dts-identity.com/it/docs/endpoints/device-inventory.md) e utilizzare il relativo menu **Azioni**.

| Azione | Effetto |
|---|---|
| **Isola** | Isola il dispositivo dalla rete per contenere un incidente. Vedere [cosa blocca l'isolamento](#what-isolation-actually-blocks). |
| **Annulla isolamento** | Rimuove le regole di isolamento e ripristina il normale accesso alla rete. |
| **Configura MFA per il dispositivo** | Imposta la registrazione MFA del dispositivo su **Obbligatorio**, **Facoltativa** o **Disabilitato**, con verifica sul dispositivo. È bloccata finché un [criterio di conformità dei dispositivi](https://dts-identity.com/it/docs/security/conditional-access/device-compliance-policies.md#windows-logon) imposta la modalità per questo dispositivo. Vedere [MFA all'accesso a Windows](https://dts-identity.com/it/docs/endpoints/windows-logon-mfa.md). |
| **Vincola utente** / **Vincola gruppo** | Collega un account del sistema operativo del dispositivo a un account dipendente a scelta, oppure consente a ogni membro di un gruppo di utilizzare il dispositivo. L'account del sistema operativo è precompilato con quello dell'ultimo accesso e può invece essere digitato, così un dispositivo può essere associato prima che il suo utente acceda per la prima volta: il nome utente senza il dominio, e il nome breve del dominio (`DEV`, non `dev.example.com`) oppure, per un account locale, il nome del computer. Su Windows il dominio è obbligatorio. Vengono suggeriti gli account il cui nome utente corrisponde. Un dispositivo può avere più account associati (uno per account del sistema operativo) e gruppi; l'elenco **Account associati** nella scheda Panoramica li mostra ed è il punto in cui si rimuove un'associazione. Un dispositivo il cui utente attivo non è uno dei suoi utenti associati viene segnalato nell'elenco, ed è così che diventa visibile un dispositivo che ha cambiato proprietario. |
| **Install updates** | Installa gli aggiornamenti del sistema operativo che il dispositivo ha segnalato come mancanti. Vedere [installare gli aggiornamenti mancanti](#installing-missing-updates). |
| **Raccogli diagnostica** | Chiede all'Endpoint Agent i suoi log e il suo stato delle ultime 24, 48 o 72 ore, pseudonimizzati sul dispositivo. Vedere [pacchetti di diagnostica](#diagnostics-packages). |
| **Elimina dispositivo** | Rimuove il record dall'inventario. Non disinstalla nulla sulla macchina. |

Ogni azione viene scritta nel [log di audit](https://dts-identity.com/it/docs/monitoring/audit-logs.md), inclusa l'indicazione di chi l'ha avviata.

### Cosa blocca effettivamente l'isolamento [#what-isolation-actually-blocks]

L'isolamento installa regole firewall locali sull'endpoint. È una misura di contenimento, non un interruttore di spegnimento: viene deliberatamente mantenuta una connettività sufficiente a mantenere gestibile la macchina e a consentire di rimuovere nuovamente l'isolamento.

**Bloccato:** tutto il restante traffico in entrata e in uscita, IPv4 e IPv6.

**Deliberatamente ancora consentiti:**

- La connessione del dispositivo verso la piattaforma, in modo da poter annullare l'isolamento da remoto.
- DNS, DHCP e la configurazione automatica del proxy, in modo che la macchina mantenga la risoluzione dei nomi e l'assegnazione degli indirizzi di base.
- L'autenticazione di dominio Windows, in modo che l'accesso al dominio continui a funzionare.
- La sincronizzazione dell'ora, in modo che l'orologio resti corretto (Endpoint Agent).
- Il traffico di loopback sulla macchina stessa.

Due proprietà sono rilevanti dal punto di vista operativo. Le regole sono **persistenti e applicate all'avvio**, quindi un riavvio non rimuove l'isolamento, e l'isolamento è attivo prima dell'avvio del servizio client. Inoltre le regole vengono **rimosse solo annullando l'isolamento**, oppure disinstallando l'[Endpoint Agent](https://dts-identity.com/it/docs/endpoints/device-client.md#uninstall), che prima rimuove l'isolamento. La disinstallazione del [legacy client](https://dts-identity.com/it/docs/endpoints/legacy-client.md) da una macchina isolata la lascia isolata, quindi in quel caso annullare prima l'isolamento. Se l'isolamento separa un dispositivo dalla piattaforma, `dts-agent revert-isolation` sul dispositivo lo rimuove localmente.

L'isolamento è disponibile su Windows, macOS e Linux con l'Endpoint Agent, e su Windows con il legacy client. Su una macchina Linux che ospita container, l'isolamento interrompe anche la rete dei container, e un firewall proprio dell'host può comunque bloccare ciò che l'isolamento consente.

### Isolamento parziale

Un dispositivo può segnalare **Parzialmente isolato**. Si tratta di uno stato, non di una modalità selezionabile: il client confronta le regole di isolamento effettivamente presenti con l'insieme completo previsto e segnala l'isolamento parziale quando alcune, ma non tutte, sono in vigore. In genere significa che un isolamento o un annullamento è stato completato solo in parte. Considerarlo come "non contenuto" e ripetere l'azione.

## Installare gli aggiornamenti mancanti [#installing-missing-updates]

> **Nota:** l'installazione degli aggiornamenti fa parte del patch management, che richiede il piano **Pro** con l'add-on **DIAM**. Negli altri piani la scheda Patch mancanti continua a elencare gli aggiornamenti mancanti, ma non mostra pulsanti di installazione.

La scheda **Patch mancanti** di un dispositivo elenca gli aggiornamenti del sistema operativo che la macchina ha segnalato come mancanti.
Con l'endpoint agent attuale è possibile installarli da lì. Su un dispositivo con il precedente DTS Client, e su Linux, i pulsanti di installazione sono disattivati.

Ogni aggiornamento ha un proprio pulsante **Installa**, e **Installa tutti gli aggiornamenti in sospeso** sopra la sezione **Aggiornamenti di sistema**
li avvia tutti in un'unica esecuzione. L'azione cumulativa chiede prima una conferma; un singolo aggiornamento
si avvia immediatamente, a meno che non sia contrassegnato con *Riavvio richiesto*, nel qual caso viene chiesta anch'essa una conferma. Gli aggiornamenti che provengono
dal catalogo delle vulnerabilità anziché dalla macchina stessa non hanno un pulsante: sono
aggiornamenti delle applicazioni, e questa azione gestisce solo il meccanismo di aggiornamento del sistema operativo.

Cosa succede dopo il clic:

- Il dispositivo conferma l'**avvio**, non il completamento. Un'installazione dura da alcuni minuti ad alcune
  ore in background, quindi la console non segnala mai un aggiornamento come installato.
- La patch mantiene un indicatore **Installation requested** finché il dispositivo non segnala di nuovo il proprio stato, e
  **tutti i pulsanti di installazione del dispositivo sono bloccati** finché l'indicatore resta attivo. Una macchina installa un solo insieme di aggiornamenti
  alla volta, quindi questo impedisce anche a due amministratori di sovrapporre installazioni. L'indicatore decade
  dopo due ore, nel caso in cui un'installazione non dia mai riscontro.
- **Un'installazione non riuscita viene indicata presso l'aggiornamento.** Il dispositivo riporta ciò che ha comunicato il proprio meccanismo
  di aggiornamento, con le sue parole, e i pulsanti tornano subito disponibili anziché dopo le due
  ore. Un messaggio resta presso l'aggiornamento finché questo non viene installato o non si avvia un altro tentativo.
- **Ogni esecuzione conclusa è registrata nel log di audit**, come `DEVICE_UPDATES_INSTALLED` o
  `DEVICE_UPDATES_FAILED` con il messaggio del dispositivo, così l'esito resta leggibile dopo la scomparsa
  dell'indicatore e un [allarme](https://dts-identity.com/it/docs/monitoring/alarms.md) può segnalare le installazioni non riuscite.
- L'elenco viene corretto quando il dispositivo invia il successivo rapporto di stato. **Aggiorna stato del dispositivo**
  nell'intestazione del dispositivo richiede subito tale rapporto anziché attendere quello giornaliero, e l'avviso
  sull'installazione in corso ripete il pulsante.
- **Il dispositivo non viene mai riavviato.** Un aggiornamento contrassegnato con *Riavvio richiesto* diventa effettivo dopo il successivo
  riavvio, che resta a carico dell'utente o della normale manutenzione.

Requisiti e limiti:

- Il dispositivo deve essere **Connesso**. Le installazioni non vengono messe in coda per i dispositivi offline: un'installazione
  differita verrebbe eseguita giorni dopo, in un momento arbitrario, rispetto a un elenco che era attuale al momento
  della messa in coda.
- L'azione richiede l'**endpoint agent attuale**. Non è offerta per i dispositivi che eseguono il client
  precedente, né su Linux, dove l'agent non gestisce alcun meccanismo di aggiornamento.
- Su Windows viene eseguita una sola sessione di installazione alla volta. La console blocca i pulsanti mentre
  un'installazione è aperta, quindi la situazione si presenta raramente; una richiesta che arriva comunque viene rifiutata con un
  messaggio anziché scartata silenziosamente.

### Aggiornamenti delle applicazioni [#application-updates]

Sui dispositivi Windows con l'endpoint agent attuale, la scheda Patch mancanti elenca anche gli **Aggiornamenti delle applicazioni**
provenienti dal catalogo dei pacchetti, e un aggiornamento confermato ha un proprio pulsante **Scarica e installa**. Il dispositivo scarica
autonomamente il programma di installazione dall'indirizzo del produttore, lo verifica rispetto al checksum del catalogo e alla firma
del produttore e lo esegue in modalità silenziosa; la console non gestisce mai il file. Tutto quanto descritto sopra vale anche qui: il
dispositivo conferma l'avvio, i pulsanti restano bloccati durante l'esecuzione, un errore viene mostrato presso l'aggiornamento e
il dispositivo non viene mai riavviato. Un aggiornamento che si completa solo con un riavvio viene segnalato come installato.

Un aggiornamento di applicazione senza pulsante ne indica il motivo sotto di sé, ad esempio:

- il pacchetto è **Non confermato** (più pacchetti corrispondono, oppure il programma di installazione è diverso da quello
  installato): sceglierlo con **Scegli pacchetto** accanto all'aggiornamento;
- l'applicazione è **Installato in un profilo utente**, oppure il suo programma di installazione **installa per singolo utente**;
- più applicazioni sul dispositivo corrispondono allo stesso pacchetto, ad esempio due runtime affiancati;
- il programma di installazione **non ha una modalità silenziosa**, rimuove prima la versione installata oppure è contenuto in un
  archivio;
- le informazioni sull'aggiornamento **non sono attuali**: le installazioni utilizzano dati del catalogo risalenti al massimo a sette giorni;
- il dispositivo esegue macOS: lì gli aggiornamenti delle applicazioni vengono elencati, ma non installati.

L'installazione degli aggiornamenti delle applicazioni funziona anche su un dispositivo isolato: l'isolamento lascia passare l'endpoint
agent stesso, ed è l'agent a scaricare il programma di installazione. Non è disponibile tramite l'API.

## Pacchetti di diagnostica [#diagnostics-packages]

Quando un dispositivo si comporta in modo anomalo e nessuno può accedere alla macchina, **Raccogli diagnostica** nel menu Azioni chiede all'Endpoint Agent i suoi log e il suo stato delle ultime 24, 48 o 72 ore. Il dispositivo deve essere connesso. Su un dispositivo che esegue ancora il precedente DTS Client la voce di menu è disattivata. Il pacchetto arriva entro circa mezzo minuto ed è elencato nella scheda **Diagnostica** del dispositivo, da cui si scarica come file JSON.

- **Pseudonimizzato sul dispositivo.** Prima che il pacchetto lasci la macchina, l'agent sostituisce nomi utente, indirizzi email, nomi di dominio e di host, SID, indirizzi IP e MAC, numeri di serie e percorsi dei profili con segnaposto come `user-1` o `host-2`. Lo stesso valore riceve lo stesso segnaposto in tutto il pacchetto, così le relazioni restano leggibili. La corrispondenza non lascia mai il dispositivo. Codici di errore, timestamp, versioni e stati restano invariati.
- **Mai inclusi:** chiavi, token, password, codici, registri eventi di Windows e i dati grezzi sulla postura.
- **Dimensioni.** L'agent mantiene un pacchetto sotto 1 MB e, se necessario, scarta le righe di log più vecchie. Un pacchetto di questo tipo viene contrassegnato come troncato.
- **Conservazione.** Un pacchetto viene eliminato 14 giorni dopo la raccolta.
- **Audit.** La raccolta viene registrata come `DEVICE_COMMAND_SENT` e ogni download come `DEVICE_DIAGNOSTICS_DOWNLOADED`, ciascuno con l'amministratore che l'ha eseguito.

Un pacchetto pseudonimizzato resta un dato personale. Lo trasmetta al supporto solo nell'ambito dell'accordo sul trattamento dei dati che copre la Sua istanza.

## Dispositivi offline e comandi in coda

Un dispositivo viene considerato offline circa dieci secondi dopo l'ultimo check-in.

Tre azioni possono essere **messe in coda per la riconnessione**: **Isola**, **Annulla isolamento** e **Configura MFA per il dispositivo**. Se il dispositivo è offline, la console propone di mettere in coda il comando, che viene recapitato automaticamente non appena il dispositivo torna disponibile. Ogni altra azione non riesce immediatamente su un dispositivo offline anziché essere memorizzata.

Regole della coda:

- **Un solo comando in sospeso per ambito.** L'isolamento e la registrazione MFA vengono messi in coda separatamente, ma un comando di isolamento più recente sostituisce uno più vecchio in sospeso, quindi un dispositivo non può accumulare istruzioni contraddittorie.
- **I comandi in coda scadono dopo sette giorni** se il dispositivo non torna mai disponibile.
- **Le azioni in sospeso sono visibili nella pagina del dispositivo** e possono essere annullate prima della consegna.
- Anche la consegna viene registrata nel log di audit, così da poter vedere sia quando un comando è stato messo in coda sia quando ha effettivamente raggiunto il dispositivo.

## Tramite l'API [#through-the-api]

> **Nota:** richiede la funzionalità **deviceTrust**.

Gli stessi comandi sono disponibili a livello programmatico, ed è questo il mezzo per integrare il contenimento in un playbook SOAR o nei propri strumenti.

```bash
curl -X POST https://<your-instance>/api/v1/devices/<deviceUid>/query/Isolate \
  -H "Authorization: Bearer <access token>" \
  -H "Content-Type: application/json" \
  -d '{"queueIfOffline": true}'
```

La chiamata richiede lo scope `devices.query`. Impostare `queueIfOffline` su `true` per ottenere il comportamento di coda descritto sopra; il valore predefinito è `false`, quindi una semplice chiamata verso un dispositivo offline non riesce immediatamente anziché essere differita.

### Comandi disponibili

| Comando | Parametri | Scopo |
|---|---|---|
| `Isolate` | nessuno | Isolare il dispositivo dalla rete. |
| `RevertIsolation` | nessuno | Ripristinare l'accesso alla rete. |
| `SetMfaEnrollment` | `enrollment`: `Required`, `Optional`, `Disabled` | Impostare la registrazione MFA per l'accesso a Windows. |
| `RequestFullUpdate` | nessuno | Chiedere al dispositivo di inviare di nuovo la propria postura completa. Non modifica nulla sull'endpoint. |
| `GetProcessList` | nessuno | Restituire i processi attualmente in esecuzione. |
| `TerminateProcesses` | `pids` (endpoint agent) o `signature` (legacy client) | Arrestare i processi con questi id, letti da `GetProcessList` dello stesso dispositivo, oppure quelli di un prodotto rilevato. L'Endpoint Agent non arresta mai sé stesso né un processo critico per il sistema. |
| `Run` | `signature` | Avviare un prodotto rilevato. Solo legacy client. |
| `Scan` | `signature`, `scanType`: `full`, `default` o `path`, `path`, `clean` | Avviare una scansione antimalware del prodotto di sicurezza indicato. |
| `UpdateDefinitions` | `signature` | Aggiornare le definizioni antimalware del prodotto indicato. |
| `EnableRTP` | `signature` | Riattivare la protezione in tempo reale. |
| `SetFirewallState` | `signature`, `operation`: `enable` o `disable`, `password` | Abilitare o disabilitare un prodotto firewall. |
| `SetAgentState` | `signature`, `operation`: `enable` o `disable` | Abilitare o disabilitare un agent di patch management. Solo legacy client. |
| `GetProductInfo` | `productList` | Leggere i dettagli dei prodotti indicati. Solo legacy client. |
| `GetRunningState` | `signatureList` | Verificare se i prodotti indicati sono in esecuzione. Solo legacy client. |
| `BlockEndpointDestinations` | `destinations` | Bloccare specifici indirizzi o reti IPv4 sull'endpoint. Solo legacy client. |
| `UnblockEndpointDestinations` | `filterKeys` | Rimuovere i blocchi di destinazione impostati in precedenza. Solo legacy client. |
| `GetEndpointBlockedDestinationsList` | nessuno | Elencare i blocchi di destinazione attualmente in vigore. Solo legacy client. |
| `DownloadMissingPatches` | `patches` | Scaricare gli aggiornamenti del sistema operativo che il dispositivo ha segnalato come mancanti. Senza l'elenco, tutti quelli offerti. |
| `InstallMissingPatches` | `patches` | Installare tali aggiornamenti. Il dispositivo non viene mai riavviato per questo. |
| `CollectDiagnostics` | `hours` (da 1 a 72, predefinito 24) | Restituire i log e lo stato dell'agent per quella finestra, pseudonimizzati sul dispositivo. Tramite l'API il pacchetto va al chiamante e non viene memorizzato. |

Il parametro `patches` contiene gli identificativi che il dispositivo stesso ha segnalato in `missingPatches`: un numero KB su Windows, l'identificativo proprio dell'aggiornamento dove non esiste un numero KB, un'etichetta di aggiornamento su macOS. Leggerli prima dai dati sulle patch del dispositivo. Questi due comandi richiedono l'endpoint agent attuale; agiscono sul meccanismo di aggiornamento proprio del sistema operativo e su Linux ricevono la risposta "non supportato".

Il parametro `signature` identifica un prodotto di sicurezza **così come viene segnalato da quel dispositivo**. Leggerlo prima dai dati sui prodotti del dispositivo stesso, con `GetProductInfo`, anziché presumere un identificativo stabile tra macchine diverse.

Su un dispositivo con l'Endpoint Agent, `Scan`, `UpdateDefinitions` ed `EnableRTP` agiscono su Microsoft Defender (Windows) e `SetFirewallState` sul firewall del sistema operativo (Windows e macOS); `signature` resta obbligatorio ma non viene valutato. Un comando contrassegnato come *solo legacy client* viene rifiutato per un dispositivo di questo tipo. Sul legacy client, i comandi a livello di prodotto agiscono su software di sicurezza di terze parti installato sull'endpoint e funzionano solo dove quel prodotto supporta l'operazione. Considerare un errore come "il prodotto ha rifiutato" e non come "il dispositivo non è raggiungibile"; i due casi vengono segnalati in modo diverso.

Il blocco delle destinazioni si applica solo a IPv4.

## Risoluzione dei problemi

- **Il comando è andato in timeout.** Il dispositivo era raggiungibile ma non ha risposto in tempo. Verificare che sia ancora connesso, quindi riprovare. Solo le tre azioni che possono essere messe in coda sopravvivono a una riconnessione; tutto il resto deve essere avviato di nuovo.
- **L'azione è stata messa in coda anche se il dispositivo sembra online.** L'elenco mostra l'ultimo stato noto. Se il dispositivo ha smesso di effettuare il check-in pochi secondi fa, viene già considerato offline.
- **Un dispositivo resta isolato dopo la rimozione del client.** Con il legacy client le regole firewall sono locali e sopravvivono al client. Reinstallare un client, annullare l'isolamento, quindi disinstallarlo correttamente. L'Endpoint Agent rimuove l'isolamento quando viene disinstallato.
- **Il dispositivo segnala un isolamento parziale.** Avviare di nuovo **Isola** o **Annulla isolamento** per riportarlo a uno stato definito.

## Vedere anche

- [Inventario dei dispositivi](https://dts-identity.com/it/docs/endpoints/device-inventory.md): l'elenco dei dispositivi e le pagine di dettaglio.
- [MFA all'accesso a Windows](https://dts-identity.com/it/docs/endpoints/windows-logon-mfa.md): l'effetto dell'impostazione di registrazione MFA sull'endpoint.
- [Endpoint Agent](https://dts-identity.com/it/docs/endpoints/device-client.md): ciò che viene eseguito sulla macchina.
- [Log di audit](https://dts-identity.com/it/docs/monitoring/audit-logs.md): dove vengono registrati ogni comando e la relativa consegna.
