Eseguire comandi di risposta dinamica in un dispositivo

Si applica a:

• Microsoft Defender per endpoint Piano 2

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

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).

Requisiti minimi

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

• Verificare che sia in esecuzione una versione supportata di Windows, macOS o Linux.

  I dispositivi devono eseguire una delle operazioni seguenti:

  • Windows 11

  • Windows 10

    • Versione 1909 o successiva
    • Versione 1903 con KB4515384
    • Versione 1809 (RS 5) con KB4537818
    • Versione 1803 (RS 4) con KB4537795
    • Versione 1709 (RS 3) con KB4537816

  • Windows Server 2019 - Applicabile solo per l'anteprima pubblica

    • Versione 1903 o (con KB4515384) successiva
    • Versione 1809 (con KB4537818)

  • Windows Server 2022

  • macOS(richiede profili di configurazione aggiuntivi)

    • 13 (Ventura)
    • 12 (Monterey)
    • 11 (Big Sur)

  • Linux

    • Distribuzioni del server Linux supportate e versioni del kernel

Autorizzazioni

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

Richiesta HTTP

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

Intestazioni di richiesta

Corpo della richiesta

Comandi

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"
                    }
                ]
            }
        }
    ]
}

Argomenti correlati

• Ottenere l'API azione del computer
• Risultato di risposta in temo reale
• Annullare azione dei computer