Freigeben über

Ausführen von Liveantwortbefehlen auf einem Gerät

  • Artikel

Gilt für:

Wichtig

Einige Informationen in diesem Artikel beziehen sich auf ein vorab veröffentlichtes Produkt, das vor der kommerziellen Veröffentlichung möglicherweise erheblich geändert wird. Microsoft übernimmt in Bezug auf die hier bereitgestellten Informationen keine Gewährleistung, weder ausdrücklich noch konkludent.

Möchten Sie Microsoft Defender für Endpunkt ausprobieren? Registrieren Sie sich für eine kostenlose Testversion.

Hinweis

Wenn Sie ein US Government-Kunde sind, verwenden Sie bitte die URIs, die in Microsoft Defender for Endpoint für US Government-Kunden aufgeführt sind.

Tipp

Um die Leistung zu verbessern, können Sie den Server näher an Ihrem geografischen Standort verwenden:

  • 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

API-Beschreibung

Führt eine Sequenz von Liveantwortbefehlen auf einem Gerät aus.

Begrenzungen

  1. Die Ratenbeschränkungen für diese API sind 10 Aufrufe pro Minute (zusätzliche Anforderungen werden mit HTTP 429 beantwortet).

  2. 25 gleichzeitig ausgeführte Sitzungen (Anforderungen, die den Drosselungsgrenzwert überschreiten, erhalten die Antwort "429 – Zu viele Anforderungen").

  3. Wenn der Computer nicht verfügbar ist, wird die Sitzung bis zu drei Tage in die Warteschlange eingereiht.

  4. RunScript-Befehlstimeouts nach 10 Minuten.

  5. Liveantwortbefehle können nicht in die Warteschlange eingereiht und nur einzeln ausgeführt werden.

  6. Wenn sich der Computer, auf dem Sie diesen API-Aufruf ausführen möchten, in einer RBAC-Gerätegruppe befindet, der keine automatisierte Wiederherstellungsebene zugewiesen ist, müssen Sie mindestens die minimale Wartungsstufe für eine bestimmte Gerätegruppe aktivieren.

    Hinweis

    Die Erstellung von Gerätegruppen wird in Defender für Endpunkt Plan 1 und Plan 2 unterstützt.

  7. Mehrere Liveantwortbefehle können für einen einzelnen API-Aufruf ausgeführt werden. Wenn jedoch ein Liveantwortbefehl fehlschlägt, werden nicht alle nachfolgenden Aktionen ausgeführt.

  8. Mehrere Liveantwortsitzungen können nicht auf demselben Computer ausgeführt werden (wenn die Liveantwortaktion bereits ausgeführt wird, werden nachfolgende Anforderungen mit HTTP 400 – ActiveRequestAlreadyExists beantwortet).

Hinweis

Über die Seite Gerät initiierte Liveantwortaktionen sind in der machineactions-API nicht verfügbar.

Mindestanforderungen

Bevor Sie eine Sitzung auf einem Gerät initiieren können, stellen Sie sicher, dass Sie die folgenden Anforderungen erfüllen:

Berechtigungen

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, einschließlich der Auswahl von Berechtigungen, finden Sie unter Erste Schritte.

Berechtigungstyp Berechtigung Anzeigename der Berechtigung
App Machine.LiveResponse Ausführen einer Liveantwort auf einem bestimmten Computer
Delegiert (Geschäfts-, Schul- oder Unikonto) Machine.LiveResponse Ausführen einer Liveantwort auf einem bestimmten Computer

HTTP-Anforderung

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

Anforderungsheader

Name Typ Beschreibung
Authorization String Bearertoken<>. Erforderlich.
Content-Type string application/json. Erforderlich.

Anforderungstext

Parameter Typ Beschreibung
Kommentar Zeichenfolge Kommentar, der der Aktion zugeordnet werden soll.
Befehle Array Auszuführende Befehle. Zulässige Werte sind PutFile, RunScript und GetFile (müssen in dieser Reihenfolge ohne Beschränkung auf Wiederholungen liegen).

Befehle

Befehlstyp Parameter Beschreibung
Putfile Schlüssel: FileName

Wert: <Dateiname>

 Fügt eine Datei aus der Bibliothek auf dem Gerät ab. Dateien werden in einem Arbeitsordner gespeichert und gelöscht, wenn das Gerät standardmäßig neu gestartet wird. HINWEIS: Hat kein Antwortergebnis.
RunScript Schlüssel: ScriptName
Wert: <Skript aus Bibliothek>

Schlüssel: Args
Wert: <Skriptargumente>

 Führt ein Skript aus der Bibliothek auf einem Gerät aus.

Der Args-Parameter wird an Ihr Skript übergeben.

Timeouts nach 10 Minuten.
GetFile Schlüssel: Pfad
Wert: <Dateipfad>		 Sammeln von Dateien von einem Gerät. HINWEIS: Umgekehrte Schrägstriche im Pfad müssen mit Escapezeichen versehen werden.

Antwort

  • Bei erfolgreicher Ausführung gibt diese Methode 201 Created zurück.

    Aktionsentität. Wenn der Computer mit der angegebenen ID nicht gefunden wurde: 404 Nicht gefunden.

Beispiel

Anforderungsbeispiel

Hier sehen Sie ein Beispiel für die Anforderung.

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

Anforderungsbeispiel

Hier ist ein Beispiel für die Antwort.

Mögliche Werte für jeden Befehl status sind "Created", "Completed" und "Failed".

HTTP/1.1 200 Ok

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

Tipp

Möchten Sie mehr erfahren? Engage mit der Microsoft-Sicherheitscommunity in unserer Tech Community: Microsoft Defender for Endpoint Tech Community.