API של התראות רשימה
חל על:
- Microsoft Defender עבור תוכנית 1 של נקודת קצה
- Microsoft Defender עבור תוכנית 2 של נקודת קצה
- Microsoft Defender XDR
רוצה להתנסות ב- Microsoft Defender עבור נקודת קצה? הירשם לקבלת גירסת ניסיון ללא תשלום.
הערה
אם אתה לקוח של ממשלת ארה"ב, השתמש בURI המפורטים ב- Microsoft Defender עבור נקודת קצה עבור לקוחות של ממשלת ארה"ב.
עצה
לקבלת ביצועים טובים יותר, באפשרותך להשתמש בשרת קרוב יותר למיקום הגיאוגרפי שלך:
- 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
תיאור API
אחזור אוסף של התראות.
תומך בשאילתות OData V4.
אופרטורים נתמכים של OData:
$filter
ב:alertCreationTime
,lastUpdateTime
,incidentId
,InvestigationId
id
,asssignedTo
,detectionSource
,lastEventTime
,status
, ומאפייניםcategory
severity
.$top
עם הערך המרבי של 10,000$skip
$expand
שלevidence
- ראה דוגמאות בשאילתות OData עם Microsoft Defender עבור נקודת קצה.
מגבלות
באפשרותך לקבל התראות עודכנו לאחרונה בהתאם לת תקופת השמירה שתצורתה נקבעה.
גודל העמוד המרבי הוא 10,000.
דרג מגבלות עבור API זה הן 100 שיחות בדקה ו- 1,500 שיחות בשעה.
הרשאות
אחת מההרשאות הבאות נדרשת כדי לקרוא ל- API זה. לקבלת מידע נוסף, כולל כיצד לבחור הרשאות, ראה שימוש בממשקי Microsoft Defender עבור נקודת קצה API.
סוג הרשאה | הרשאה | שם תצוגה של הרשאה |
---|---|---|
יישום | Alert.Read.All | Read all alerts |
יישום | Alert.ReadWrite.All | Read and write all alerts |
מוסמך (חשבון בעבודה או בבית ספר) | התראה.קריאה | Read alerts |
מוסמך (חשבון בעבודה או בבית ספר) | Alert.ReadWrite | Read and write alerts |
הערה
בעת השגת אסימון באמצעות אישורי משתמש:
- למשתמש דרושה לפחות הרשאת התפקיד הבאה:
View Data
(ראה Create ולנהל תפקידים לקבלת מידע נוסף) - התגובה כוללת רק התראות המשויכות למכשירים שהמשתמש יכול לגשת אליהם, בהתבסס על הגדרות קבוצת מכשירים (ראה Create ולנהל קבוצות מכשירים לקבלת מידע נוסף)
יצירת קבוצת מכשירים נתמכת ב- Defender for Endpoint Plan 1 ובתוכנית 2.
בקשת HTTP
GET /api/alerts
כותרות בקשות
Name | סוג | תיאור |
---|---|---|
ההרשאות | מחרוזת | נושא {token}. נדרש . |
גוף הבקשה
ריק
תגובה
אם שיטה זו מצליחה, היא מחזירה 200 אישור ורשימה של אובייקטי התראה בגוף התגובה.
דוגמה 1 - ברירת מחדל
בקשה
להלן דוגמה לבקשה.
GET https://api.securitycenter.microsoft.com/api/alerts
תגובה
להלן דוגמה לתגובה.
הערה
רשימת התגובות המוצגת כאן עשויה להיחתך לתדירות. כל ההתראות יוחזרו משיחה בפועל.
{
"@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": []
}
...
]
}
דוגמה 2 - קבל 10 התראות האחרונות עם ראיות קשורות
בקשה
להלן דוגמה לבקשה.
GET https://api.securitycenter.microsoft.com/api/alerts?$top=10&$expand=evidence
תגובה
להלן דוגמה לתגובה.
הערה
רשימת התגובות המוצגת כאן עשויה להיחתך לתדירות. כל ההתראות יוחזרו משיחה בפועל.
{
"@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"
}
]
},
...
]
}
למידע נוסף
שאילתות OData עם Microsoft Defender עבור נקודת קצה
עצה
האם ברצונך לקבל מידע נוסף? Engage עם קהילת האבטחה של Microsoft בקהילת הטכנולוגיה שלנו: Microsoft Defender עבור נקודת קצה Tech Community.
משוב
https://aka.ms/ContentUserFeedback.
בקרוב: במהלך 2024, נפתור בעיות GitHub כמנגנון המשוב לתוכן ונחליף אותו במערכת משוב חדשה. לקבלת מידע נוסף, ראה:שלח והצג משוב עבור