Uruchamianie poleceń odpowiedzi na żywo na urządzeniu

  • Artykuł

Dotyczy:

Ważna

Niektóre informacje zawarte w tym artykule odnoszą się do wersji wstępnej produktu, który może zostać znacznie zmodyfikowany do czasu wydania wersji komercyjnej. Firma Microsoft nie udziela żadnych gwarancji, wyrażonych ani dorozumianych, w odniesieniu do informacji podanych tutaj.

Chcesz poznać usługę ochrony punktu końcowego w usłudze Microsoft Defender? Utwórz konto, aby skorzystać z bezpłatnej wersji próbnej.

Uwaga

Jeśli jesteś klientem rządowym USA, użyj identyfikatorów URI wymienionych w Ochrona punktu końcowego w usłudze Microsoft Defender dla klientów rządowych USA.

Porada

Aby uzyskać lepszą wydajność, możesz użyć serwera bliżej lokalizacji geograficznej:

  • 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

Opis interfejsu API

Uruchamia sekwencję poleceń odpowiedzi na żywo na urządzeniu

Ograniczenia

  1. Ograniczenia szybkości dla tego interfejsu API to 10 wywołań na minutę (dodatkowe żądania są odbierane przy użyciu protokołu HTTP 429).

  2. 25 współbieżnie uruchomionych sesji (żądania przekraczające limit ograniczania przepustowości otrzymują odpowiedź "429 — zbyt wiele żądań").

  3. Jeśli maszyna nie jest dostępna, sesja jest umieszczana w kolejce przez maksymalnie trzy dni.

  4. Limity czasu poleceń w języku RunScript po 10 minutach.

  5. Polecenia odpowiedzi na żywo nie mogą być umieszczane w kolejce i mogą być wykonywane tylko jeden raz.

  6. Jeśli maszyna, na której próbujesz uruchomić to wywołanie interfejsu API, znajduje się w grupie urządzeń RBAC, która nie ma przypisanego poziomu automatycznego korygowania, musisz przynajmniej włączyć minimalny poziom korygowania dla danej grupy urządzeń.

    Uwaga

    Tworzenie grupy urządzeń jest obsługiwane w usłudze Defender for Endpoint Plan 1 i Plan 2.

  7. Wiele poleceń odpowiedzi na żywo można uruchomić w jednym wywołaniu interfejsu API. Jeśli jednak polecenie odpowiedzi na żywo zakończy się niepowodzeniem, wszystkie kolejne akcje nie zostaną wykonane.

  8. Nie można wykonać wielu sesji odpowiedzi na żywo na tej samej maszynie (jeśli akcja odpowiedzi na żywo jest już uruchomiona, kolejne żądania są odpowiadane za pomocą protokołu HTTP 400 — ActiveRequestAlreadyExists).

Uwaga

Akcje odpowiedzi na żywo zainicjowane na stronie Urządzenie nie są dostępne w interfejsie API machineactions.

Minimalne wymagania

Przed zainicjowaniem sesji na urządzeniu upewnij się, że spełniasz następujące wymagania:

Uprawnienia

Do wywołania tego interfejsu API jest wymagane jedno z następujących uprawnień. Aby dowiedzieć się więcej, w tym jak wybrać uprawnienia, zobacz Wprowadzenie.

Typ uprawnień Uprawnienie Nazwa wyświetlana uprawnień
Aplikacja Machine.LiveResponse Uruchamianie odpowiedzi na żywo na określonej maszynie
Delegowane (konto służbowe) Machine.LiveResponse Uruchamianie odpowiedzi na żywo na określonej maszynie

Żądanie HTTP

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

Nagłówki żądań

Name (Nazwa) Wpisać Opis
Autoryzacji Ciąg Token> elementu nośnego<. Wymagane.
Typ zawartości Ciąg application/json. Wymagane.

Treść żądania

Parametr Wpisać Opis
Komentowanie Ciąg Komentarz do skojarzenia z akcją.
Polecenia Tablicy Polecenia do uruchomienia. Dozwolone wartości to PutFile, RunScript, GetFile (muszą być w tej kolejności bez limitu powtórzeń).

Polecenia

Typ polecenia Parametry Opis
PutFile Klucz: Nazwa pliku

Wartość: <nazwa pliku>

 Umieszcza plik z biblioteki na urządzeniu. Pliki są zapisywane w folderze roboczym i są usuwane po domyślnym ponownym uruchomieniu urządzenia. UWAGA: Nie ma wyniku odpowiedzi.
RunScript Klucz: ScriptName
Wartość: <skrypt z biblioteki>

Klucz: Args
Wartość: <argumenty skryptu>

 Uruchamia skrypt z biblioteki na urządzeniu.

Parametr Args jest przekazywany do skryptu.

Limity czasu po 10 minutach.
Getfile Klucz: ścieżka
Wartość: <Ścieżka pliku>		 Zbierz plik z urządzenia. UWAGA: Ukośnienia odwrotne w ścieżce muszą być blokami ucieczki.

Odpowiedzi

  • Jeśli to się powiedzie, ta metoda zwróci wartość 201 Utworzono.

    Jednostka akcji. Jeśli nie znaleziono maszyny o określonym identyfikatorze — nie znaleziono 404.

Przykład

Przykład żądania

Oto przykład żądania.

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

Przykład odpowiedzi

Oto przykład odpowiedzi.

Możliwe wartości dla każdego stanu polecenia to "Utworzono", "Ukończono" i "Niepowodzenie".

HTTP/1.1 200 Ok

Typ zawartości: 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"
                    }
                ]
            }
        }
    ]
}

Porada

Chcesz dowiedzieć się więcej? Engage ze społecznością microsoft security w naszej społeczności technicznej: Ochrona punktu końcowego w usłudze Microsoft Defender Tech Community.