API של Microsoft Defender עבור נקודת קצה - Hello World

חל על:

• Microsoft Defender עבור תוכנית 1 של נקודת קצה
• Microsoft Defender עבור תוכנית 2 של נקודת קצה

רוצה להתנסות ב- Microsoft Defender עבור נקודת קצה? הירשם לקבלת גירסת ניסיון ללא תשלום.

הערה

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

עצה

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

• 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

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

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

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

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

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

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

שלב 1 - יצירת יישום במזהה Entra של Microsoft

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

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

   

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

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

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

     הערה

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

     

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

     

     חשוב

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

     לדוגמה:

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

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

   הערה

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

   

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

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

   חשוב

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

   

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

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

   

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

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

• העתק את קובץ ה- Script הבא ל- POWERShell ISE או לעורך טקסט ושמור אותו כ- Get-Token.ps1.

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

  # That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
  # Paste below your Tenant ID, App ID and App Secret (App key).
  
  $tenantId = '' ### Paste your tenant ID here
  $appId = '' ### Paste your Application ID here
  $appSecret = '' ### Paste your Application secret here
  
  $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
  

• בדיקת אמינות:

  • הפעל את קובץ ה- Script.
  • בדפדפן, עבור אל: https://jwt.ms/.
  • העתק את האסימון (תוכן הקובץ Latest-token.txt).
  • הדבק בתיבה העליונה.
  • חפש את המקטע "תפקידים". חפש את התפקיד 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 create above
  # Read more about [other query options and filters](get-alerts.md).
  $url = "https://api.securitycenter.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 webrequest 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 Defender עבור ממשקי API של נקודת קצה
• גישה אל Microsoft Defender עבור נקודת קצה עם הקשר יישום
• גישה אל Microsoft Defender עבור נקודת קצה עם הקשר משתמש

עצה

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