Condividi tramite

Eseguire comandi di risposta dinamica in un dispositivo

  • Articolo

Si applica a:

Importante

Alcune informazioni in questo articolo fanno riferimento alle caratteristiche di un prodotto prima del rilascio, che possono essere modificate sostanzialmente prima della distribuzione al pubblico. Microsoft non fornisce alcuna garanzia, esplicita o implicita, in relazione alle informazioni contenute in questo documento.

Se si desidera provare Microsoft Defender per endpoint, iscriversi a una versione di valutazione gratuita.

Nota

Se si è un cliente del governo degli Stati Uniti, usare gli URI elencati in Microsoft Defender per endpoint per i clienti del governo degli Stati Uniti.

Consiglio

Per ottenere prestazioni migliori, è possibile usare il server più vicino alla posizione geografica:

  • us.api.security.microsoft.com
  • eu.api.security.microsoft.com
  • uk.api.security.microsoft.com
  • au.api.security.microsoft.com
  • swa.api.security.microsoft.com

Descrizione DELL'API

Esegue una sequenza di comandi di risposta dinamica in un dispositivo

Limitazioni

  1. Le limitazioni di frequenza per questa API sono di 10 chiamate al minuto (le richieste aggiuntive vengono inviate con HTTP 429).

  2. 25 sessioni in esecuzione simultaneamente (le richieste che superano il limite di limitazione ricevono una risposta "429 - Troppe richieste").

  3. Se il computer non è disponibile, la sessione viene accodata per un massimo di tre giorni.

  4. Timeout dei comandi RunScript dopo 10 minuti.

  5. I comandi di risposta dinamica non possono essere accodati e possono essere eseguiti solo uno alla volta.

  6. Se il computer che si sta tentando di eseguire questa chiamata API si trova in un gruppo di dispositivi controllo degli accessi in base al ruolo a cui non è assegnato un livello di correzione automatizzato, è necessario almeno abilitare il livello di correzione minimo per un determinato gruppo di dispositivi.

    Nota

    La creazione di gruppi di dispositivi è supportata in Defender per endpoint Piano 1 e Piano 2.

  7. È possibile eseguire più comandi di risposta dinamica in una singola chiamata API. Tuttavia, quando un comando di risposta dinamica ha esito negativo, tutte le azioni successive non verranno eseguite.

  8. Non è possibile eseguire più sessioni di risposta live nello stesso computer(se l'azione di risposta dinamica è già in esecuzione, le richieste successive vengono inviate con HTTP 400 - ActiveRequestAlreadyExists).

Nota

Le azioni di risposta in tempo reale avviate dalla pagina Dispositivo non sono disponibili nell'API machineactions.

Requisiti minimi

Prima di avviare una sessione in un dispositivo, assicurarsi di soddisfare i requisiti seguenti:

Autorizzazioni

Per chiamare questa API è necessaria una delle autorizzazioni seguenti. Per altre informazioni, incluso come scegliere le autorizzazioni, vedere Introduzione.

Tipo di autorizzazione Autorizzazione Nome visualizzato autorizzazioni
Applicazione Machine.LiveResponse Eseguire una risposta dinamica in un computer specifico
Delegato (account aziendale o dell'istituto di istruzione) Machine.LiveResponse Eseguire una risposta dinamica in un computer specifico

Richiesta HTTP

POST https://api.securitycenter.microsoft.com/API/machines/{machine_id}/runliveresponse

Intestazioni di richiesta

Nome Tipo Descrizione
Autorizzazione Stringa Token di connessione<>. Obbligatorio.
Content-Type stringa application/json. Obbligatorio.

Corpo della richiesta

Parametro Tipo Descrizione
Comment Stringa Commento da associare all'azione.
Comandi Array Comandi da eseguire. I valori consentiti sono PutFile, RunScript, GetFile (devono essere in questo ordine senza limiti per le ripetizioni).

Comandi

Tipo di comando Parametri Descrizione
PutFile Chiave: FileName

Valore: <nome file>

 Inserisce un file dalla libreria al dispositivo. I file vengono salvati in una cartella di lavoro e vengono eliminati al riavvio del dispositivo per impostazione predefinita. NOTA: non ha un risultato di risposta.
RunScript Chiave: ScriptName
Valore: <script dalla libreria>

Chiave: Args
Valore: <argomenti dello script>

 Esegue uno script dalla libreria in un dispositivo.

Il parametro Args viene passato allo script.

Timeout dopo 10 minuti.
GetFile Chiave: Percorso
Valore: <percorso del file>		 Raccogliere file da un dispositivo. NOTA: le barre rovesciate nel percorso devono essere precedute da caratteri di escape.

Risposta

  • Se ha esito positivo, questo metodo restituisce 201 Created.

    Entità azione. Se il computer con l'ID specificato non è stato trovato - 404 Non trovato.

Esempio

Esempio di richiesta

Ecco un esempio della richiesta.

POST https://api.securitycenter.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/runliveresponse

```JSON
{
   "Commands":[
      {
         "type":"RunScript",
         "params":[
            {
               "key":"ScriptName",
               "value":"minidump.ps1"
            },
            {
               "key":"Args",
               "value":"OfficeClickToRun"
            }

         ]
      },
      {
         "type":"GetFile",
         "params":[
            {
               "key":"Path",
               "value":"C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
            }
         ]
      }
   ],
   "Comment":"Testing Live Response API"
}

Esempio di risposta

Ecco un esempio della risposta.

I valori possibili per ogni stato del comando sono "Created", "Completed" e "Failed".

HTTP/1.1 200 Ok

Content-type: application/json

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#MachineActions/$entity",
    "id": "{machine_action_id}",
    "type": "LiveResponse",
    "requestor": "analyst@microsoft.com",
    "requestorComment": "Testing Live Response API",
    "status": "Pending",
    "machineId": "{machine_id}",
    "computerDnsName": "hostname",
    "creationDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
    "lastUpdateDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
    "errorHResult": 0,
    "commands": [
        {
            "index": 0,
            "startTime": null,
            "endTime": null,
            "commandStatus": "Created",
            "errors": [],
            "command": {
                "type": "RunScript",
                "params": [
                    {
                        "key": "ScriptName",
                        "value": "minidump.ps1"
                    },{
                        "key": "Args",
                        "value": "OfficeClickToRun"
                    }
                ]
            }
        }, {
            "index": 1,
            "startTime": null,
            "endTime": null,
            "commandStatus": "Created",
            "errors": [],
            "command": {
                "type": "GetFile",
                "params": [{
                        "key": "Path", "value": "C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
                    }
                ]
            }
        }
    ]
}

Consiglio

Per saperne di più, Collaborare con la community di Microsoft Security nella community tech: Microsoft Defender per endpoint Tech Community.