Kør direkte svar-kommandoer på en enhed
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
- ina.api.security.microsoft.com
Kører en sekvens af kommandoer til direkte svar på en enhed
Hastighedsbegrænsninger for denne API er 10 kald pr. minut (yderligere anmodninger besvares med HTTP 429).
25 sessioner, der kører samtidigt (anmodninger, der overskrider begrænsningsgrænsen, modtager et svar på "429 – for mange anmodninger").
Hvis computeren ikke er tilgængelig, sættes sessionen i kø i op til tre dage.
RunScript-kommandotimeout efter 10 minutter.
Live response-kommandoer kan ikke sættes i kø og kan kun udføres én ad gangen.
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.
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.
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.
Før du kan starte en session på en enhed, skal du sørge for at opfylde følgende krav:
Kontrollér, at du kører en understøttet version af Windows, macOS eller Linux.
Enheder skal køre en af følgende:
Windows 11
Windows 10
- Version 1909 eller nyere
- Version 1903 med KB4515384
- Version 1809 (RS 5) med KB4537818
- Version 1803 (RS 4) med KB4537795
- Version 1709 (RS 3) med KB4537816
Windows Server 2019 – Kun tilgængelig for offentlig prøveversion
Windows Server 2022
macOS(kræver yderligere konfigurationsprofiler)
- 13 (Ventura)
- 12 (Monterey)
- 11 (Big Sur)
Linux
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 |
POST https://api.securitycenter.microsoft.com/API/machines/{machine_id}/runliveresponse
Navn | Type | Beskrivelse |
---|---|---|
Autorisation | String | Ihændehavertoken<>. Kræves. |
Indholdstype | streng | application/json. Kræves. |
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). |
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 |
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. |
Hvis det lykkes, returnerer denne metode 201 Created.
Handlingsobjekt. Hvis computeren med det angivne id ikke blev fundet - 404 blev ikke fundet.
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"
}
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? Kontakt Microsoft Security-community'et i vores Tech Community: Microsoft Defender for Endpoint Tech Community.