Del via

Kjør live svarkommandoer på en enhet

  • Artikkel

Gjelder for:

Viktig

Noe informasjon i denne artikkelen er knyttet til et forhåndsutgitt produkt, som kan endres vesentlig før det utgis kommersielt. Microsoft gir ingen garantier, uttrykt eller underforstått, med hensyn til informasjonen som er oppgitt her.

Vil du oppleve Microsoft Defender for endepunkt? Registrer deg for en gratis prøveperiode.

Obs!

Hvis du er us Government-kunde, kan du bruke URI-ene som er oppført i Microsoft Defender for Endpoint for US Government-kunder.

Tips

Hvis du vil ha bedre ytelse, kan du bruke serveren nærmere geografisk plassering:

  • 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
  • ina.api.security.microsoft.com

API-beskrivelse

Kjører en sekvens med live-svarkommandoer på en enhet

Begrensninger

  1. Satsbegrensninger for denne API-en er 10 oppkall per minutt (flere forespørsler svares med HTTP 429).

  2. 25 samtidig kjørende økter (forespørsler som overskrider begrensningsgrensen mottar et svar på «429 – for mange forespørsler».

  3. Hvis maskinen ikke er tilgjengelig, legges økten i kø i opptil tre dager.

  4. KjøreScript-kommando tidsavbrudd etter 10 minutter.

  5. Live-svarkommandoer kan ikke settes i kø og kan bare kjøres én om gangen.

  6. Hvis maskinen du prøver å kjøre dette API-kallet er i en RBAC-enhetsgruppe som ikke har et automatisert utbedringsnivå tilordnet, må du i det minste aktivere minimum utbedringsnivå for en gitt enhetsgruppe.

    Obs!

    Oppretting av enhetsgruppe støttes i Defender for Endpoint Plan 1 og Plan 2.

  7. Flere live-svarkommandoer kan kjøres på ett enkelt API-kall. Når en live-svarkommando mislykkes, utføres imidlertid ikke alle etterfølgende handlinger.

  8. Flere økter for direkte respons kan ikke utføres på samme maskin (hvis handlingen for direkte respons allerede kjører, blir påfølgende forespørsler besvart med HTTP 400 – ActiveRequestAlreadyExists).

Obs!

Handlinger for direkte respons som er startet fra enhetssiden, er ikke tilgjengelige i machineactions-API-en.

Minimumskrav

Før du kan starte en økt på en enhet, må du sørge for at du oppfyller følgende krav:

Tillatelser

Én av følgende tillatelser er nødvendig for å kalle opp denne API-en. Hvis du vil ha mer informasjon, inkludert hvordan du velger tillatelser, kan du se Komme i gang.

Tillatelsestype Tillatelse Visningsnavn for tillatelse
Program Machine.LiveResponse Kjør direkte svar på en bestemt maskin
Delegert (jobb- eller skolekonto) Machine.LiveResponse Kjør direkte svar på en bestemt maskin

HTTP-forespørsel

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

Forespørselshoder

Navn Type: Beskrivelse
Autorisasjon Streng <Bærertoken>. Påkrevd.
Innholdstype streng program/json. Påkrevd.

Forespørselstekst

Parameter Type: Beskrivelse
Kommentar Streng Kommentar som skal knyttes til handlingen.
Kommandoer Matrise Kommandoer som skal kjøres. Tillatte verdier er PutFile, RunScript, GetFile (må være i denne rekkefølgen uten grense for repetisjoner).

Kommandoer

Kommandotype Parametere Beskrivelse
PutFile Nøkkel: Filnavn

Verdi: <filnavn>

 Plasserer en fil fra biblioteket på enheten. Filer lagres i en arbeidsmappe og slettes når enheten startes på nytt som standard. OBS! Har ikke noe svarresultat.
RunScript Nøkkel: Skriptnavn
Verdi: <Skript fra bibliotek>

Nøkkel: Argumenter
Verdi: <Skriptargumenter>

 Kjører et skript fra biblioteket på en enhet.

Parameteren Args sendes til skriptet.

Tidsavbrudd etter 10 minutter.
GetFile Nøkkel: Bane
Verdi: <Filbane>		 Samle inn fil fra en enhet. OBS! Omvendte skråstreker i banen må være escaped.

Svar

  • Hvis vellykket, returnerer denne metoden 201 Opprettet.

    Handlingsenhet. Hvis maskinen med den angitte ID-en ikke ble funnet – finner du ikke 404.

Eksempel

Eksempel på forespørsel

Her er et eksempel på forespørselen.

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

Eksempel på svar

Her er et eksempel på svaret.

Mulige verdier for hver kommandostatus er Opprettet, Fullført og Mislykket.

HTTP/1.1 200 Ok

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

Tips

Vil du lære mer? Engasjer deg med Microsoft Security-fellesskapet i det tekniske fellesskapet vårt: Microsoft Defender for Endpoint Tech Community.