Delen via

Live-antwoordopdrachten uitvoeren op een apparaat

  • Artikel

Van toepassing op:

Belangrijk

Sommige informatie in dit artikel heeft betrekking op een vooraf uitgebracht product dat aanzienlijk kan worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, expliciet of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

Wilt u Microsoft Defender voor Eindpunt ervaren? Meld u aan voor een gratis proefversie.

Opmerking

Als u een klant van de Amerikaanse overheid bent, gebruikt u de URI's die worden vermeld in Microsoft Defender voor Eindpunt voor klanten van de Amerikaanse overheid.

Tip

Voor betere prestaties kunt u de server dichter bij uw geografische locatie gebruiken:

  • 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-beschrijving

Voert een reeks live-antwoordopdrachten uit op een apparaat

Beperkingen

  1. Frequentiebeperkingen voor deze API zijn 10 aanroepen per minuut (extra aanvragen worden beantwoord met HTTP 429).

  2. 25 gelijktijdig uitgevoerde sessies (aanvragen die de beperkingslimiet overschrijden, ontvangen een antwoord '429 - Te veel aanvragen').

  3. Als de machine niet beschikbaar is, wordt de sessie maximaal drie dagen in de wachtrij geplaatst.

  4. Time-outs van RunScript-opdrachten na 10 minuten.

  5. Opdrachten voor live-antwoorden kunnen niet in de wachtrij worden geplaatst en kunnen alleen één voor één worden uitgevoerd.

  6. Als de computer waarop u deze API-aanroep probeert uit te voeren zich in een RBAC-apparaatgroep bevindt waaraan geen geautomatiseerd herstelniveau is toegewezen, moet u ten minste het minimale herstelniveau voor een bepaalde apparaatgroep inschakelen.

    Opmerking

    Het maken van een apparaatgroep wordt ondersteund in Defender for Endpoint Plan 1 en Plan 2.

  7. Er kunnen meerdere opdrachten voor live-antwoorden worden uitgevoerd op één API-aanroep. Wanneer een live-antwoordopdracht echter mislukt, worden alle volgende acties niet uitgevoerd.

  8. Meerdere live-antwoordsessies kunnen niet worden uitgevoerd op dezelfde computer (als er al een live-antwoordactie wordt uitgevoerd, worden volgende aanvragen beantwoord met HTTP 400 - ActiveRequestAlreadyExists).

Opmerking

Live-responsacties die zijn geïnitieerd vanaf de pagina Apparaat, zijn niet beschikbaar in de machineactions-API.

Minimumeisen

Voordat u een sessie op een apparaat kunt starten, moet u voldoen aan de volgende vereisten:

Machtigingen

Een van de volgende machtigingen is vereist om deze API aan te roepen. Zie Aan de slag voor meer informatie, waaronder het kiezen van machtigingen.

Machtigingstype Machtiging Weergavenaam van machtiging
Toepassing Machine.LiveResponse Live-antwoord uitvoeren op een specifieke computer
Gedelegeerd (werk- of schoolaccount) Machine.LiveResponse Live-antwoord uitvoeren op een specifieke computer

HTTP-aanvraag

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

Aanvraagheaders

Naam Type Beschrijving
Vergunning Tekenreeks Bearer-token<>. Vereist.
Content-Type reeks application/json. Vereist.

Aanvraagtekst

Parameter Type Beschrijving
Opmerking Tekenreeks Opmerking om aan de actie te koppelen.
Opdrachten Array Opdrachten die moeten worden uitgevoerd. Toegestane waarden zijn PutFile, RunScript, GetFile (moet in deze volgorde staan zonder limiet voor herhalingen).

Opdrachten

Opdrachttype Parameters Omschrijving
PutFile Sleutel: Bestandsnaam

Waarde: <bestandsnaam>

 Hiermee plaatst u een bestand uit de bibliotheek op het apparaat. Bestanden worden opgeslagen in een werkmap en worden standaard verwijderd wanneer het apparaat opnieuw wordt opgestart. OPMERKING: Heeft geen antwoordresultaat.
RunScript Sleutel: ScriptName
Waarde: <Script uit bibliotheek>

Sleutel: Args
Waarde: <Scriptargumenten>

 Hiermee wordt een script uitgevoerd vanuit de bibliotheek op een apparaat.

De parameter Args wordt doorgegeven aan uw script.

Time-outs na 10 minuten.
GetFile Sleutel: Pad
Waarde: <Bestandspad>		 Bestand van een apparaat verzamelen. OPMERKING: Backslashes in pad moeten worden gesnapt.

Antwoord

  • Als dit lukt, retourneert deze methode 201 Gemaakt.

    Actie-entiteit. Als de computer met de opgegeven id niet is gevonden, is 404 niet gevonden.

Voorbeeld

Voorbeeld van aanvraag

Hier volgt een voorbeeld van de aanvraag.

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

Antwoordvoorbeeld

Hier volgt een voorbeeld van het antwoord.

Mogelijke waarden voor elke opdrachtstatus zijn 'Gemaakt', 'Voltooid' en 'Mislukt'.

HTTP/1.1 200 Ok

Inhoudstype: toepassing/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

Wil je meer weten? Engage met de Microsoft Security-community in onze Tech Community: Microsoft Defender voor Eindpunt Tech Community.