Hello World עבור REST API של Microsoft Defender XDR REST

  • חל על: Microsoft Defender XDR

חשוב

חלק מהמידע מתייחס למוצר שהותקן מראש וייתכן שהוא השתנה באופן משמעותי לפני הזמינות הכללית שלו. Microsoft אינה מבטיחה דבר, באופן מפורש או משתמע, באשר למידע המסופק כאן.

קבלת אירועים באמצעות קובץ Script פשוט של PowerShell

השלמת פרוייקט זה אמורה להימשך 5 עד 10 דקות. הערכת זמן זו כוללת רישום של היישום והחלת הקוד מקובץ ה- Script לדוגמה של PowerShell.

רשום יישום ב- Microsoft Entra ID

  1. היכנס אל Azure.

  2. נווט אל רישום Microsoft Entra ID>App>רישום חדש.

    מקטע הרישום החדש בפורטל Microsoft Defender החדש

  3. בטופס הרישום, בחר שם עבור האפליקציה שלך ולאחר מכן בחר הירשם. בחירת URI של ניתוב מחדש היא אופציונלית. אין צורך בדוגמה זו כדי להשלים דוגמה זו.

  4. בדף היישום שלך, בחר הרשאות API>> הוסף ממשקי API של הרשאות שהארגון שלי משתמשבהם>, הקלד Microsoft Threat Protection ובחר Microsoft Threat Protection. האפליקציה שלך יכולה כעת לגשת Microsoft Defender XDR.

    עצה

    Microsoft Threat Protection הוא שם Microsoft Defender XDR עבור משתמשים, ואינו מופיע ברשימה המקורית. עליך להתחיל לכתוב את שמו בתיבת הטקסט כדי לראות אותו מופיע. מקטע השימוש בממשקי API בפורטל Microsoft Defender הבא

    • בחר הרשאות יישום>Incident.Read.All ובחר הוסף הרשאות.

      חלונית הרשאות של יישום בפורטל Microsoft Defender שלך

  5. בחר הענק הסכמת מנהל מערכת. בכל פעם שאתה מוסיף הרשאה, עליך לבחור הענק הסכמת מנהל מערכת כדי שהיא תוכל להיכנס לתוקף.

    המקטע 'הענק הסכמת מנהל מערכת' בפורטל Microsoft Defender הניהול

  6. הוסף סוד ליישום. בחר אישורים &, הוסף תיאור לסוד ולאחר מכן בחר הוסף.

    עצה

    לאחר שתבחר הוסף, בחר העתק את הערך הסודי שנוצר. לא תוכל לאחזר את הערך הסודי לאחר שתצא.

    המקטע 'הוספת סוד' בפורטל Microsoft Defender שלך

  7. הקלט את מזהה היישום ואת מזהה הדייר שלך במקום בטוח. הן מופיעות תחת מבט כולל בדף היישום שלך.

    המקטע 'מבט כולל' בפורטל Microsoft Defender'

קבל אסימון באמצעות היישום והשתמש לאסימון כדי לגשת ל- API

לקבלת מידע נוסף על Microsoft Entra, עיין בערכת Microsoft Entra שלך.

חשוב

על אף שהדוגמה באפליקציית הדגמה זו מעודדת אותך להדביק את הערך הסודי שלך למטרות בדיקה, לעולם אל תקוד באופן קשיח סודות ליישום שפועל בייצור. ספק חיצוני יכול להשתמש בסוד שלך כדי לגשת למשאבים. באפשרותך לעזור לשמור על סודות האפליקציה שלך מאובטחים באמצעות Azure Key Vault. לקבלת דוגמה מעשית לאופן שבו תוכל להגן על האפליקציה שלך, ראה ניהול סודות באפליקציות השרת שלך באמצעות Azure Key Vault.

  1. העתק את קובץ ה- Script הבא והדבק אותו בעורך הטקסט המועדף עליך. שמור בשם Get-Token.ps1. באפשרותך גם להפעיל את הקוד כפי שהוא ב- PowerShell ISE, אך עליך לשמור אותו מכיוון שאנו צריכים להפעיל אותו שוב כאשר אנו משתמשים בקובץ Script של הבאת מקרים בסעיף הבא.

    קובץ Script זה יוצר אסימון ושמור אותו בתיקיה העבודה תחת השם, ולאחרLatest-token.txt.

    # This script gets the app context token and saves it to a file named "Latest-token.txt" under the current directory.
# Paste in your tenant ID, client ID and app secret (App key).

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"
$authBody = [Ordered] @{
  resource = $resourceAppIdUri
  client_id = $clientId
  client_secret = $appSecret
  grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

אימות האסימון

  1. העתק והדבק את האסימון שקיבלת ל- JWT כדי לפענח אותו.

  2. JWT פירושואסימון אינטרנט של JSON. האסימון המפענח מכיל כמה פריטים או דרישות בתבנית JSON. ודא שתביעת התפקידים בתוך האסימון המפענח מכילה את ההרשאות הרצויות.

    בתמונה הבאה, באפשרותך לראות אסימון פענוח שנרכש מיישום, עם Incidents.Read.All, Incidents.ReadWrite.Allוהרשאות AdvancedHunting.Read.All :

    המקטע 'אסימון פענוח' בפורטל Microsoft Defender'

קבל רשימה של אירועים אחרונים

קובץ ה- Script הבא משתמשGet-Token.ps1כדי לגשת ל- API. לאחר מכן, הוא מאחזר רשימה של אירועים עודכנו לאחרונה ב- 48 השעות האחרונות, ו שומר את הרשימה כקובץ JSON.

חשוב

שמור קובץ Script זה באותה תיקיה ששמרת Get-Token.ps1.

# This script returns incidents last updated within the past 48 hours.

$token = ./Get-Token.ps1

# Get incidents from the past 48 hours.
# The script may appear to fail if you don't have any incidents in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# This URL contains the type of query and the time filter we created above.
# Note that `$filter` does not refer to a local variable in our script --
# it's actually an OData operator and part of the API's syntax.
$url = "https://api.security.microsoft.com/api/incidents`?`$filter=lastUpdateTime+ge+$dateTime"

# Set the webrequest headers
$headers = @{
    'Content-Type' = 'application/json'
    'Accept' = 'application/json'
    'Authorization' = "Bearer $token"
}

# Send the request and get the results.
$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop

# Extract the incidents from the results.
$incidents =  ($response | ConvertFrom-Json).value | ConvertTo-Json -Depth 99

# Get a string containing the execution time. We concatenate that string to the name 
# of the output file to avoid overwriting the file on consecutive runs of the script.
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json
$outputJsonPath = "./Latest Incidents $dateTimeForFileName.json"

Out-File -FilePath $outputJsonPath -InputObject $incidents

סיימת! בהצלחה:

  • יצר ורשם יישום.
  • הוענקה הרשאה עבור יישום זה לקרוא התראות.
  • מחובר ל- API.
  • השתמש בקובץ Script של PowerShell כדי להחזיר אירועים המעודכנים ב- 48 השעות האחרונות.

עצה

האם ברצונך לקבל מידע נוסף? צור קשר עם קהילת האבטחה של Microsoft בקהילת הטכנולוגיה שלנו: קהילת האבטחה של Microsoft Defender XDR.

  • Last updated on