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

  • Článek

Platí pro:

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

Chcete vyzkoušet Defender pro Endpoint? Zaregistrujte se a získejte bezplatnou zkušební verzi,

Poznámka

Pokud jste zákazníkem státní správy USA, použijte identifikátory URI uvedené v Microsoft Defender for Endpoint pro zákazníky státní správy USA.

Tip

Pro lepší výkon můžete použít server blíže k vašemu geografickému umístění:

  • 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

Popis rozhraní API

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

Omezení

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

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

  3. Pokud počítač není dostupný, je relace zařazená do fronty po dobu až tří dnů.

  4. Po 10 minutách dojde k vypršení časových limitů příkazů RunScriptu.

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

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

    Poznámka

    Vytváření skupin zařízení je podporováno v defenderu for Endpoint Plan 1 a Plan 2.

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

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

Poznámka

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

Minimální požadavky

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

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.securitycenter.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í. Soubory se ukládají do pracovní složky a ve výchozím nastavení se při restartování zařízení odstraní. 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.

Vypršení časových limitů po 10 minutách
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

  • Pokud je tato metoda úspěšná, vrátí 201 Vytvořeno.

    Entita akce. Pokud se počítač se zadaným ID nenašel– 404 Nenalezlo se.

Příklad

Příklad požadavku

Tady je příklad požadavku.

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

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

Tip

Chcete se dozvědět více? Engage s komunitou Microsoft Security v naší technické komunitě: Microsoft Defender for Endpoint Tech Community.