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 Ochrona punktu końcowego w usłudze Microsoft Defender 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
Opis interfejsu API
Pobiera kolekcję alertów.
Obsługuje zapytania OData V4.
Obsługiwane operatory OData:
$filteron:alertCreationTime, ,lastUpdateTime,InvestigationIdincidentId,id, ,asssignedTo,detectionSource,lastEventTime, ,status, iseveritycategorywłaściwości.$topz maksymalną wartością 10 000$skip$expandz o.o.evidence- Zobacz przykłady w temacie Zapytania OData z Ochrona punktu końcowego w usłudze Microsoft Defender.
Ograniczenia
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ę.
Uprawnienia
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 Używanie interfejsów API Ochrona punktu końcowego w usłudze Microsoft Defender.
| 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 Datazobacz Twórca i zarządzanie rolami) - 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 Twórca i zarządzanie grupami urządzeń, aby uzyskać więcej informacji)
Tworzenie grupy urządzeń jest obsługiwane w usłudze Defender for Endpoint Plan 1 i Plan 2.
Żądanie HTTP
GET /api/alerts
Nagłówki żądań
| Name (Nazwa) | Wpisać | Opis |
|---|---|---|
| Autoryzacji | Ciąg | Element nośny {token}. Wymagane. |
Treść żądania
Pusty
Odpowiedzi
W przypadku powodzenia ta metoda zwraca wartość 200 OK i listę obiektów alertów w treści odpowiedzi.
Przykład 1 — wartość domyślna
Żądanie
Oto przykład żądania.
GET https://api.securitycenter.microsoft.com/api/alerts
Odpowiedzi
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": []
}
...
]
}
Przykład 2 — uzyskiwanie 10 najnowszych alertów z powiązanymi dowodami
Żądanie
Oto przykład żądania.
GET https://api.securitycenter.microsoft.com/api/alerts?$top=10&$expand=evidence
Odpowiedzi
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"
}
]
},
...
]
}
Zobacz też
Zapytania OData z Ochrona punktu końcowego w usłudze Microsoft Defender
Porada
Chcesz dowiedzieć się więcej? Engage ze społecznością microsoft security w naszej społeczności technicznej: Ochrona punktu końcowego w usłudze Microsoft Defender Tech Community.
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla