Interfejs API wyświetlania listy alertów
Dotyczy:
- Ochrona punktu końcowego w usłudze Microsoft Defender (plan 1)
- Ochrona punktu końcowego w usłudze Microsoft Defender (plan 2)
- Microsoft Defender XDR
Chcesz poznać usługę ochrony punktu końcowego w usłudze Microsoft Defender? Utwórz konto, aby skorzystać z bezpłatnej wersji próbnej.
Uwaga
Jeśli jesteś klientem rządowym USA, użyj identyfikatorów URI wymienionych w usłudze Microsoft Defender for Endpoint dla klientów rządowych USA.
Porada
Aby uzyskać lepszą wydajność, możesz użyć serwera bliżej lokalizacji geograficznej:
- 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
Pobiera kolekcję alertów.
Obsługuje zapytania OData V4.
Obsługiwane operatory OData:
-
$filter
on:alertCreationTime
, ,lastUpdateTime
,InvestigationId
incidentId
,id
, ,asssignedTo
,detectionSource
,lastEventTime
, ,status
, iseverity
category
właściwości. -
$top
z maksymalną wartością 10 000 $skip
-
$expand
zevidence
- Zobacz przykłady w temacie Zapytania OData w usłudze Microsoft Defender for Endpoint.
Alerty mogą być ostatnio aktualizowane zgodnie ze skonfigurowanym okresem przechowywania.
Maksymalny rozmiar strony to 10 000.
Ograniczenia szybkości dla tego interfejsu API to 100 wywołań na minutę i 1500 wywołań na godzinę.
Do wywołania tego interfejsu API jest wymagane jedno z następujących uprawnień. Aby dowiedzieć się więcej, w tym jak wybrać uprawnienia, zobacz Korzystanie z usługi Microsoft Defender dla interfejsów API punktu końcowego.
Typ uprawnień | Uprawnienie | Nazwa wyświetlana uprawnień |
---|---|---|
Aplikacja | Alert.Read.All | Read all alerts |
Aplikacja | Alert.ReadWrite.All | Read and write all alerts |
Delegowane (konto służbowe) | Alert.Read | Read alerts |
Delegowane (konto służbowe) | Alert.ReadWrite | Read and write alerts |
Uwaga
Podczas uzyskiwania tokenu przy użyciu poświadczeń użytkownika:
- Użytkownik musi mieć co najmniej następujące uprawnienia roli: (Aby uzyskać więcej informacji,
View Data
zobacz Tworzenie ról i zarządzanie nimi) - Odpowiedź zawiera tylko alerty skojarzone z urządzeniami, do których użytkownik może uzyskać dostęp, na podstawie ustawień grupy urządzeń (zobacz Tworzenie grup urządzeń i zarządzanie nimi , aby uzyskać więcej informacji)
Tworzenie grupy urządzeń jest obsługiwane w usłudze Defender for Endpoint Plan 1 i Plan 2.
GET /api/alerts
Name (Nazwa) | Wpisać | Opis |
---|---|---|
Autoryzacja | Ciąg | Element nośny {token}. Wymagane. |
Pusty
W przypadku powodzenia ta metoda zwraca wartość 200 OK i listę obiektów alertów w treści odpowiedzi.
Oto przykład żądania.
GET https://api.securitycenter.microsoft.com/api/alerts
Oto przykład odpowiedzi.
Uwaga
Wyświetlona tutaj lista odpowiedzi może zostać obcięta w celu zachowania zwięzłości. Wszystkie alerty zostaną zwrócone z rzeczywistego wywołania.
{
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Alerts",
"value": [
{
"id": "da637308392288907382_-880718168",
"incidentId": 7587,
"investigationId": 723156,
"assignedTo": "secop123@contoso.com",
"severity": "Low",
"status": "New",
"classification": "TruePositive",
"determination": null,
"investigationState": "Queued",
"detectionSource": "WindowsDefenderAv",
"category": "SuspiciousActivity",
"threatFamilyName": "Meterpreter",
"title": "Suspicious 'Meterpreter' behavior was detected",
"description": "Malware and unwanted software are undesirable applications that perform annoying, disruptive, or harmful actions on affected machines. Some of these undesirable applications can replicate and spread from one machine to another. Others are able to receive commands from remote attackers and perform activities associated with cyber attacks.\n\nA malware is considered active if it is found running on the machine or it already has persistence mechanisms in place. Active malware detections are assigned higher severity ratings.\n\nBecause this malware was active, take precautionary measures and check for residual signs of infection.",
"alertCreationTime": "2020-07-20T10:53:48.7657932Z",
"firstEventTime": "2020-07-20T10:52:17.6654369Z",
"lastEventTime": "2020-07-20T10:52:18.1362905Z",
"lastUpdateTime": "2020-07-20T10:53:50.19Z",
"resolvedTime": null,
"machineId": "12ee6dd8c833c8a052ea231ec1b19adaf497b625",
"computerDnsName": "temp123.middleeast.corp.microsoft.com",
"rbacGroupName": "MiddleEast",
"aadTenantId": "a839b112-1253-6432-9bf6-94542403f21c",
"threatName": null,
"mitreTechniques": [
"T1064",
"T1085",
"T1220"
],
"relatedUser": {
"userName": "temp123",
"domainName": "DOMAIN"
},
"comments": [
{
"comment": "test comment for docs",
"createdBy": "secop123@contoso.com",
"createdTime": "2020-07-21T01:00:37.8404534Z"
}
],
"evidence": []
}
...
]
}
Oto przykład żądania.
GET https://api.securitycenter.microsoft.com/api/alerts?$top=10&$expand=evidence
Oto przykład odpowiedzi.
Uwaga
Wyświetlona tutaj lista odpowiedzi może zostać obcięta w celu zachowania zwięzłości. Wszystkie alerty zostaną zwrócone z rzeczywistego wywołania.
{
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Alerts",
"value": [
{
"id": "da637472900382838869_1364969609",
"incidentId": 1126093,
"investigationId": null,
"assignedTo": null,
"severity": "Low",
"status": "New",
"classification": null,
"determination": null,
"investigationState": "Queued",
"detectionSource": "WindowsDefenderAtp",
"detectorId": "17e10bbc-3a68-474a-8aad-faef14d43952",
"category": "Execution",
"threatFamilyName": null,
"title": "Low-reputation arbitrary code executed by signed executable",
"description": "Binaries signed by Microsoft can be used to run low-reputation arbitrary code. This technique hides the execution of malicious code within a trusted process. As a result, the trusted process might exhibit suspicious behaviors, such as opening a listening port or connecting to a command-and-control (C&C) server.",
"alertCreationTime": "2021-01-26T20:33:57.7220239Z",
"firstEventTime": "2021-01-26T20:31:32.9562661Z",
"lastEventTime": "2021-01-26T20:31:33.0577322Z",
"lastUpdateTime": "2021-01-26T20:33:59.2Z",
"resolvedTime": null,
"machineId": "111e6dd8c833c8a052ea231ec1b19adaf497b625",
"computerDnsName": "temp123.middleeast.corp.microsoft.com",
"rbacGroupName": "A",
"aadTenantId": "a839b112-1253-6432-9bf6-94542403f21c",
"threatName": null,
"mitreTechniques": [
"T1064",
"T1085",
"T1220"
],
"relatedUser": {
"userName": "temp123",
"domainName": "DOMAIN"
},
"comments": [
{
"comment": "test comment for docs",
"createdBy": "secop123@contoso.com",
"createdTime": "2021-01-26T01:00:37.8404534Z"
}
],
"evidence": [
{
"entityType": "User",
"evidenceCreationTime": "2021-01-26T20:33:58.42Z",
"sha1": null,
"sha256": null,
"fileName": null,
"filePath": null,
"processId": null,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": null,
"parentProcessCreationTime": null,
"parentProcessFileName": null,
"parentProcessFilePath": null,
"ipAddress": null,
"url": null,
"registryKey": null,
"registryHive": null,
"registryValueType": null,
"registryValue": null,
"accountName": "name",
"domainName": "DOMAIN",
"userSid": "S-1-5-21-11111607-1111760036-109187956-75141",
"aadUserId": "11118379-2a59-1111-ac3c-a51eb4a3c627",
"userPrincipalName": "temp123@microsoft.com",
"detectionStatus": null
},
{
"entityType": "Process",
"evidenceCreationTime": "2021-01-26T20:33:58.6133333Z",
"sha1": "ff836cfb1af40252bd2a2ea843032e99a5b262ed",
"sha256": "a4752c71d81afd3d5865d24ddb11a6b0c615062fcc448d24050c2172d2cbccd6",
"fileName": "rundll32.exe",
"filePath": "C:\\Windows\\SysWOW64",
"processId": 3276,
"processCommandLine": "rundll32.exe c:\\temp\\suspicious.dll,RepeatAfterMe",
"processCreationTime": "2021-01-26T20:31:32.9581596Z",
"parentProcessId": 8420,
"parentProcessCreationTime": "2021-01-26T20:31:32.9004163Z",
"parentProcessFileName": "rundll32.exe",
"parentProcessFilePath": "C:\\Windows\\System32",
"ipAddress": null,
"url": null,
"registryKey": null,
"registryHive": null,
"registryValueType": null,
"registryValue": null,
"accountName": null,
"domainName": null,
"userSid": null,
"aadUserId": null,
"userPrincipalName": null,
"detectionStatus": "Detected"
},
{
"entityType": "File",
"evidenceCreationTime": "2021-01-26T20:33:58.42Z",
"sha1": "8563f95b2f8a284fc99da44500cd51a77c1ff36c",
"sha256": "dc0ade0c95d6db98882bc8fa6707e64353cd6f7767ff48d6a81a6c2aef21c608",
"fileName": "suspicious.dll",
"filePath": "c:\\temp",
"processId": null,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": null,
"parentProcessCreationTime": null,
"parentProcessFileName": null,
"parentProcessFilePath": null,
"ipAddress": null,
"url": null,
"registryKey": null,
"registryHive": null,
"registryValueType": null,
"registryValue": null,
"accountName": null,
"domainName": null,
"userSid": null,
"aadUserId": null,
"userPrincipalName": null,
"detectionStatus": "Detected"
}
]
},
...
]
}
Zapytania OData za pomocą usługi Microsoft Defender dla punktu końcowego
Porada
Chcesz dowiedzieć się więcej? Skontaktuj się ze społecznością zabezpieczeń firmy Microsoft w naszej społeczności technicznej: Microsoft Defender for Endpoint Tech Community.