Kør direkte svar-kommandoer på en enhed

  • Artikel

Gælder for:

Vigtigt!

Nogle oplysninger i denne artikel er relateret til et produkt, der er udgivet på forhånd, og som kan blive ændret væsentligt, før det udgives kommercielt. Microsoft giver ingen garantier, udtrykt eller stiltiende, med hensyn til de oplysninger, der er angivet her.

Vil du opleve Microsoft Defender for Endpoint? Tilmeld dig en gratis prøveversion.

Bemærk!

Hvis du er us government-kunde, skal du bruge de URI'er, der er angivet i Microsoft Defender for Endpoint for us Government-kunder.

Tip

For at opnå en bedre ydeevne kan du bruge serveren tættere på din geografiske placering:

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

Kører en sekvens af kommandoer til direkte svar på en enhed

Begrænsninger

  1. Hastighedsbegrænsninger for denne API er 10 kald pr. minut (yderligere anmodninger besvares med HTTP 429).

  2. 25 sessioner, der kører samtidigt (anmodninger, der overskrider begrænsningsgrænsen, modtager et svar på "429 – for mange anmodninger").

  3. Hvis computeren ikke er tilgængelig, sættes sessionen i kø i op til tre dage.

  4. RunScript-kommandotimeout efter 10 minutter.

  5. Live response-kommandoer kan ikke sættes i kø og kan kun udføres én ad gangen.

  6. Hvis den computer, du forsøger at køre dette API-kald, er i en RBAC-enhedsgruppe, der ikke har fået tildelt et automatiseret afhjælpningsniveau, skal du som minimum aktivere afhjælpningsniveauet for en given enhedsgruppe.

    Bemærk!

    Oprettelse af enhedsgruppe understøttes i Defender for Endpoint Plan 1 og Plan 2.

  7. Der kan køres flere live response-kommandoer på et enkelt API-kald. Men når en direkte svar-kommando mislykkes, udføres alle efterfølgende handlinger ikke.

  8. Flere live-svar-sessioner kan ikke udføres på den samme computer (hvis live-svar-handlingen allerede kører, besvares efterfølgende anmodninger med HTTP 400 – ActiveRequestAlreadyExists).

Bemærk!

Live response-handlinger, der startes fra enhedssiden, er ikke tilgængelige i machineactions-API'en.

Minimumskrav

Før du kan starte en session på en enhed, skal du sørge for at opfylde følgende krav:

Tilladelser

En af følgende tilladelser er påkrævet for at kalde denne API. Hvis du vil vide mere, herunder hvordan du vælger tilladelser, skal du se Kom i gang.

Tilladelsestype Tilladelse Vist navn for tilladelse
Program Machine.LiveResponse Kør direkte svar på en bestemt maskine
Uddelegeret (arbejds- eller skolekonto) Machine.LiveResponse Kør direkte svar på en bestemt maskine

HTTP-anmodning

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

Anmodningsheadere

Navn Type Beskrivelse
Tilladelse String Ihændehavertoken<>. Kræves.
Indholdstype Streng application/json. Kræves.

Brødtekst i anmodning

Parameter Type Beskrivelse
Kommenter String Kommentar, der skal knyttes til handlingen.
Kommandoer Array Kommandoer, der skal køres. Tilladte værdier er PutFile, RunScript, GetFile (skal være i denne rækkefølge uden nogen grænse for gentagelser).

Kommandoer

Kommandotype Parametre Beskrivelse
PutFile Nøgle: Filnavn

Værdi: <filnavn>

 Placerer en fil fra biblioteket på enheden. Filer gemmes i en arbejdsmappe og slettes som standard, når enheden genstartes. BEMÆRK! Har ikke et svarresultat.
RunScript Nøgle: ScriptName
Værdi: <Script fra bibliotek>

Nøgle: Args
Værdi: <Scriptargumenter>

 Kører et script fra biblioteket på en enhed.

Args-parameteren overføres til scriptet.

Timeout efter 10 minutter.
Hent fil Nøgle: Sti
Værdi: <Filsti>		 Indsaml fil fra en enhed. BEMÆRK! Omvendte skråstreger i stien skal have escape-tegn.

Svar

  • Hvis det lykkes, returnerer denne metode 201 Created.

    Handlingsobjekt. Hvis computeren med det angivne id ikke blev fundet - 404 blev ikke fundet.

Eksempel

Eksempel på anmodning

Her er et eksempel på anmodningen.

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

Svareksempel

Her er et eksempel på svaret.

De mulige værdier for hver kommandostatus er "Oprettet", "Fuldført" og "Mislykket".

HTTP/1.1 200 Ok

Indholdstype: program/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

Vil du vide mere? Engage med Microsoft Security-community'et i vores tech-community: Microsoft Defender for Endpoint Tech Community.