Köra svarskommandon i livesändning på en enhet

Gäller för:

Viktigt

En del information gäller förinstallerad produkt som kan ha ändrats mycket innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som anges här.

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

Anteckning

Om du är myndighetskund i USA kan du använda de URI:er som visas i Microsoft Defender för Slutpunkt för kunder inom myndigheter i USA.

Tips

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

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com

API-beskrivning

Kör en sekvens av kommandon för livesvar på en enhet

Begränsningar

  1. Prisbegränsningar för detta API är 10 samtal per minut (ytterligare förfrågningar besvaras med HTTP 429).

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

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

  4. Tidsgränser för RunScript-kommandon efter 10 minuter.

  5. Kommandon för livesvar kan inte läggas till i kö och kan endast köras ett i taget.

  6. Om datorn som du försöker köra det här API-anropet till finns i en RBAC-enhetsgrupp som inte har en tilldelad automatiserad åtgärdsnivå, måste du minst aktivera den lägsta åtgärdsnivån för en viss enhetsgrupp.

  7. Du kan köra flera kommandon med livesvar på ett API-anrop. Men när ett live-svarskommando misslyckas körs inte alla efterföljande åtgärder.

Minimikrav

Innan du kan starta en session på en enhet kontrollerar du att du uppfyller följande krav:

Behörigheter

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

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

HTTP-begäran

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

Frågerubriker

Namn Typ Beskrivning
Auktorisering Sträng Bearer<token>. 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 Matris Kommandon som ska köras. Tillåtna värden är PutFile, RunScript och GetFile.

Kommandon

Kommandotyp Parametrar Beskrivning
PutFile Nyckel: Filnamn

Värde: <file name>

Lägger till en fil från biblioteket till enheten. Filer sparas i en arbetsmapp och tas bort när enheten startas om som standard.
RunScript Nyckel: ScriptName
Värde: <Script from library>

Tangent: Args
Värde: <Script arguments>

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

Parametern Args skickas till skriptet.

Tidsgränser efter 10 minuter.

GetFile Nyckel: Sökväg
Värde: <File path>
Samla in en fil från en enhet. Obs! Omslag i sökväg måste komma i väg.

Svar

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

    Åtgärd entitet. Om ingen dator med det angivna ID:t hittades – 404 Hittades inte.

Exempel

Exempel på förfrågan

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.

HTTP/1.1 200 Ok

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