Spuštění příkazů živé odpovědi na zařízení

  • Platí pro: Microsoft Defender for Endpoint Plan 1 and Plan 2

Důležité

Některé informace v tomto článku se týkají předvydaného produktu, který může být před komerčním vydáním podstatně změněn. Společnost Microsoft neposkytuje na zde uvedené informace žádné záruky, vyjádřené ani předpokládané.

Požadavky

Než budete moct zahájit relaci na zařízení, ujistěte se, že splňujete následující požadavky:

Podporované operační systémy

Popis rozhraní API

Spustí na zařízení posloupnost příkazů živé odpovědi.

Omezení

  • Omezení rychlosti pro toto rozhraní API jsou 10 volání za minutu (další požadavky se reagují protokolem HTTP 429).

  • 50 souběžně spuštěných relací (požadavky překračující limit omezování obdrží odpověď 429 – Příliš mnoho požadavků).

  • Pokud počítač není dostupný, bude relace zařazena do fronty po dobu až 2 hodin.

  • Po 10 minutách vyprší časový limit příkazu RunScript.

  • Příkazy živé odpovědi se nedají zařadit do fronty a dají se spouštět jenom po jednom.

  • Pokud se počítač, na kterém se pokoušíte spustit toto volání rozhraní API, je ve skupině zařízení RBAC, která nemá přiřazenou úroveň automatické nápravy, musíte pro danou skupinu zařízení alespoň povolit minimální úroveň nápravy.

  • Při jednom volání rozhraní API je možné spustit několik příkazů živé odpovědi. Pokud ale příkaz živé odpovědi selže, všechny následné akce se neprosadí.

  • Na stejném počítači není možné spustit více relací živých odpovědí (pokud už je spuštěná akce živé odpovědi, na následné požadavky se odpoví http 400 – ActiveRequestAlreadyExists).

  • Akce živé odpovědi zahájené ze stránky Zařízení nejsou v machineactions rozhraní API dostupné.

Oprávnění

K volání tohoto rozhraní API se vyžaduje jedno z následujících oprávnění. Další informace, včetně postupu při výběru oprávnění, najdete v tématu Začínáme.

Typ oprávnění Oprávnění Zobrazovaný název oprávnění
Application Machine.LiveResponse Spuštění živé odpovědi na konkrétním počítači
Delegovaný (pracovní nebo školní účet) Machine.LiveResponse Spuštění živé odpovědi na konkrétním počítači

Požadavek HTTP

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

Hlavičky požadavků

Name (Název) Typ Popis
Autorizace String Nosný<token>. Požadované.
Typ obsahu řetězec application/json. Požadované.

Text požadavku

Parametr Typ Popis
Komentování String Komentář, který chcete přidružit k akci.
Příkazy Pole Příkazy, které se mají spustit. Povolené hodnoty jsou PutFile, RunScript, GetFile (musí být v tomto pořadí bez omezení opakování).

Příkazy

Typ příkazu Parametry Popis
PutFile Klíč: FileName
Hodnota: <název souboru>		 Vloží soubor z knihovny do zařízení. Files se uloží do pracovní složky a při výchozím nastavení se odstraní, když se zařízení restartuje. POZNÁMKA: Nemá výsledek odpovědi.
Runscript Klíč: ScriptName
Hodnota: <Skript z knihovny>
Klíč: Args
Hodnota: <Argumenty skriptu>		 Spustí skript z knihovny na zařízení.
Do skriptu se předá parametr Args.
Po 10 minutách vyprší časový limit.
Získat soubor Klíč: Cesta
Hodnota: <Cesta k souboru>		 Shromážděte soubor ze zařízení. POZNÁMKA: Zpětná lomítka v cestě musí být řídicí.

Reakce

  • V případě úspěchu vrátí 201 Createdtato metoda .

  • Entita akce. Pokud se počítač se zadaným ID nenašel, zobrazí se 404 Not Found.

Příklad

Příklad požadavku

Tady je příklad požadavku.

POST https://api.security.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"
}

Příklad odpovědi

Tady je příklad odpovědi.

Možné hodnoty pro každý stav příkazu jsou "Vytvořeno", "Dokončeno" a "Selhání".

HTTP/1.1 200 Ok

Typ obsahu: application/json

{
    "@odata.context": "https://api.security.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"
                    }
                ]
            }
        }
    ]
}
  • Last updated on