Dela via

Köra livesvarskommandon på en enhet

  • Artikel

Gäller för:

Viktigt

Viss information i den här artikeln gäller en förhyrd produkt som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckta eller underförstådda, med avseende på den information som tillhandahålls här.

Vill du uppleva Microsoft Defender för Endpoint? Registrera dig för en kostnadsfri utvärderingsversion.

Obs!

Om du är en us government-kund använder du de URI:er som anges i Microsoft Defender för Endpoint för amerikanska myndighetskunder.

Tips

För bättre prestanda kan du använda servern närmare din geoplats:

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

Kör en sekvens med livesvarskommandon på en enhet

Begränsningar

  1. Hastighetsbegränsningar för det här API:et är 10 anrop per minut (ytterligare begäranden besvaras med HTTP 429).

  2. 25 sessioner som körs samtidigt (begäranden som överskrider begränsningsgränsen får svaret "429 – För många förfrågningar").

  3. Om datorn inte är tillgänglig köas sessionen i upp till tre dagar.

  4. RunScript-kommandot överskrider tidsgränsen efter 10 minuter.

  5. Livesvarskommandon kan inte placeras i kö och kan bara köras en i taget.

  6. Om den dator som du försöker köra det här API-anropet finns i en RBAC-enhetsgrupp som inte har tilldelats någon automatiserad reparationsnivå måste du minst aktivera den lägsta reparationsnivån för en viss enhetsgrupp.

    Obs!

    Skapande av enhetsgrupp stöds i Defender för Endpoint Plan 1 och Plan 2.

  7. Flera live-svarskommandon kan köras på ett enda API-anrop. Men när ett live-svarskommando misslyckas körs inte alla efterföljande åtgärder.

  8. Flera live-svarssessioner kan inte köras på samma dator (om livesvarsåtgärden redan körs besvaras efterföljande begäranden med HTTP 400 – ActiveRequestAlreadyExists).

Obs!

Livesvarsåtgärder som initieras från sidan Enhet är inte tillgängliga i API:et machineactions.

Minimikrav

Innan du kan starta en session på en enhet måste du uppfylla följande krav:

Behörigheter

En av följande behörigheter krävs för att anropa det här API:et. Mer information, inklusive hur du väljer behörigheter, finns i Kom igång.

Behörighetstyp Behörighet Visningsnamn för behörighet
Program Machine.LiveResponse Köra livesvar på en specifik dator
Delegerat (arbets- eller skolkonto) Machine.LiveResponse Köra livesvar på en specifik dator

HTTP-begäran

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

Frågerubriker

Namn Typ Beskrivning
Tillstånd Sträng <Ägartoken>. Obligatoriskt.
Content-Type sträng application/json. Obligatoriskt.

Frågebrödtext

Parameter Typ Beskrivning
Kommentar Sträng Kommentar som ska associeras med åtgärden.
Kommandon Samling Kommandon som ska köras. Tillåtna värden är PutFile, RunScript, GetFile (måste vara i den här ordningen utan begränsning för upprepningar).

Kommandon

Kommandotyp Parametrar Beskrivning
PutFile Nyckel: FileName

Värde: <filnamn>

 Placerar en fil från biblioteket till enheten. Filer sparas i en arbetsmapp och tas bort när enheten startas om som standard. Obs! Har inget svarsresultat.
RunScript Nyckel: ScriptName
Värde: <Skript från bibliotek>

Nyckel: Args
Värde: <Skriptargument>

 Kör ett skript från biblioteket på en enhet.

Args-parametern skickas till skriptet.

Tidsgränser efter 10 minuter.
GetFile Nyckel: Sökväg
Värde: <Filsökväg>		 Samla in filen från en enhet. Obs! Omvänt snedstreck i sökvägen måste vara undantagna.

Svar

  • Om det lyckas returnerar den här metoden 201 Skapad.

    Åtgärdsentitet. Om datorn med det angivna ID:t inte hittades – 404 Hittades inte.

Exempel

Exempel på begäran

Här är ett exempel på begäran.

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

Svarsexempel

Här är ett exempel på svaret.

Möjliga värden för varje kommandostatus är "Skapad", "Slutförd" och "Misslyckades".

HTTP/1.1 200 Ok

Innehållstyp: 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"
                    }
                ]
            }
        }
    ]
}

Tips

Vill du veta mer? Interagera med Microsoft Security-communityn i vår Tech Community: Microsoft Defender för Endpoint Tech Community.