לקריאה באנגלית

שתף באמצעות


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

חל על:

  • Microsoft Defender XDR

חשוב

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

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

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

רשום יישום ב- Microsoft Entra מזהה

  1. היכנס ל- Azure.

  2. נווט אל Microsoft Entra מזהה>רישום חדש של>האפליקציה.

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

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

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

    טיפ

    Microsoft Threat Protection הוא שם Microsoft Defender XDR עבור Microsoft, והוא לא יופיע ברשימה המקורית. עליך להתחיל לכתוב את שמו בתיבת הטקסט כדי לראות אותו מופיע. מקטע השימוש בממשקי 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.