MICROSOFT DEFENDER עבור נקודת קצה API - Hello World

  • חל על: Microsoft Defender for Endpoint Plan 1, Microsoft Defender for Endpoint Plan 2, Microsoft Defender for Business

הערה

אם אתה לקוח של ממשלת ארה"ב, השתמש בURI המפורטים ב- Microsoft Defender עבור נקודת קצה עבור לקוחות של ממשלת ארה"ב.

עצה

לקבלת ביצועים טובים יותר, במקום להשתמש api.security.microsoft.com, השתמש בשרת קרוב יותר להמיקום הגיאוגרפי שלך:

  • 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
  • aea.api.security.microsoft.com

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

כמה זמן נדרש כדי לעבור בדוגמה זו?

התהליך נמשך 5 דקות בלבד בשני שלבים:

  • רישום אפליקציות
  • שימוש בדוגמאות: נדרש רק העתקה/הדבקה של קובץ Script קצר של PowerShell

האם דרושה לי הרשאה להתחברות?

עבור שלב רישום היישומים, עליך להקצות תפקיד מתאים בדייר Microsoft Entra שלך. לקבלת פרטים נוספים אודות תפקידים, ראה אפשרויות הרשאה.

שלב 1 - יצירת יישום Microsoft Entra ID

  1. היכנס לפורטל פורטל Microsoft Azure.

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

    האפשרות 'רישומי יישום' תחת החלונית 'ניהול' מרכז הניהול של Microsoft Entra

  3. בטופס הרישום, בחר שם עבור האפליקציה שלך ולאחר מכן בחר הירשם.

  4. אפשר ליישום שלך לגשת אל Defender for Endpoint ולהקצות לו הרשאת 'קרא את כל ההתראות ':

    • בדף היישום שלך, בחר הרשאות API>> הוסף ממשקיAPI> של הרשאות שהארגון שלי משתמש בהם, הקלד WindowsDefenderATP ובחר WindowsDefenderATP.

      הערה

      WindowsDefenderATP אינו מופיע ברשימה המקורית. עליך להתחיל לכתוב את שמו בתיבת הטקסט כדי לראות אותו מופיע.

      האפשרות 'הרשאות API' תחת החלונית 'ניהול' מרכז הניהול של Microsoft Entra

    • בחר הרשאות יישום>התראה.קריאה.הכל ולאחר מכן בחר הוסף הרשאות.

      חלוניות סוג ההרשאה וההגדרות בדף 'בקש הרשאות API'

      חשוב

      עליך לבחור את ההרשאות הרלוונטיות. 'קרא את כל ההתראות ' הוא דוגמה בלבד.

      לדוגמה:

      • כדי להפעיל שאילתות מתקדמות, בחר הרשאת 'הפעל שאילתות מתקדמות'.
      • כדי לבודד מחשב, בחר הרשאת 'בודד מחשב'.
      • כדי לקבוע איזו הרשאה דרושה לך, עיין בסעיף הרשאות ב- API שאליו ברצונך להתקשר.

  5. בחר הענק הסכמה.

    הערה

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

    האפשרות 'הענק הרשאה להסכמה' מרכז הניהול של Microsoft Entra

  6. הוסף סוד ליישום.

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

    חשוב

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

    פריט התפריט & 'אישורים' תחת 'סודות' בחלונית 'ניהול' מרכז הניהול של Microsoft Entra

  7. רשום לעצמך את מזהה היישום ואת מזהה הדייר שלך.

    בדף היישום שלך, עבור אל מבט כולל והעתק את הפריטים הבאים:

    חלונית פרטי היישום תחת פריט התפריט מבט כולל מרכז הניהול של Microsoft Entra

בוצע! נרשמת בהצלחה יישום!

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

עצה

חלק Microsoft Defender עבור נקודת קצה API ממשיכים לדרוש אסימוני גישה שהונפקו עבור המשאב מהדור הקודםhttps://api.securitycenter.microsoft.com. אם קהל האסימון אינו תואם למשאב הצפוי על-ידי ה- API, 403 Forbiddenבקשות נכשלות ב- , גם אם נקודת הקצה של ה- API משתמשת ב- https://api.security.microsoft.com. השתמש https://api.securitycenter.microsoft.com כהמשאבים או הטווח בעת רכישת אסימונים.

העתק את קובץ ה- Script הבא ל- POWERShell ISE או לעורך טקסט ושמור אותו כ- Get-Token.ps1. הפעלת קובץ Script זה יוצרת אסימון ושמירה שלו בתיקיה 'עבודה' תחת השם Latest-token.txt.

# This code gets the application context token and saves it to a file named "Latest-token.txt" in the current directory.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application (client) ID here
$appSecret = '' ### Paste your Application secret (App key) here to test, and then store it in a safe place!

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com/'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
  resource = "$resourceAppIdUri"
  client_id = "$appId"
  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. הפעל את קובץ ה- Script כדי ליצור את Latest-token.txt הקובץ.
  2. בדפדפן אינטרנט, פתח את https://jwt.ms/ולאחר מכן העתק את האסימון (תוכן Latest-token.txt) בתיבה הזן אסימון להלן.
  3. בכרטיסיה אסימון פענוח , אתר את המקטע תפקידים וודא שהוא מכיל את ההרשאות Alert.Read.All , כפי שמוצג בתמונה הבאה:

צילום מסך jwt.ms המציג אסימון שהועתק ואת האסימון הפענוח עם המקטע 'תפקידים' וההרשאות Alert.Read.All מסומנות.

בוא יקבלו את ההתראות!

  • קובץ ה- Script הבא Get-Token.ps1 משתמש בו כדי לגשת ל- API והוא מקבל התראות ב- 48 השעות האחרונות.
  • שמור קובץ Script זה באותה תיקיה ששמרת את קובץ ה- Script הקודם Get-Token.ps1.
  • קובץ ה- Script יוצר שני קבצים (json ו- csv) עם הנתונים באותה תיקיה שבה קיימים קבצי ה- Script.
# Returns Alerts created in the past 48 hours.

$token = ./Get-Token.ps1       #run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-Token.ps1

# Get Alert from the last 48 hours. Make sure you have alerts in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# The URL contains the type of query and the time filter we created previously.
# Learn more about other query options and filters: https://learn.microsoft.com/defender-endpoint/api/get-alerts.
$url = "https://api.security.microsoft.com/api/alerts?`$filter=alertCreationTime ge $dateTime"

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

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

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

# Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file.
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json and as csv.
$outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"
$outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"

Out-File -FilePath $outputJsonPath -InputObject $alerts
($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation

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

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

עצה

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

  • Last updated on