適用於端點的 Microsoft Defender API - Hello World

適用於：

• 適用於端點的 Microsoft Defender 方案 1
• 適用於端點的 Microsoft Defender 方案 2

想要體驗適用於端點的 Microsoft Defender 嗎？ 注册免費試用版。

使用簡單的PowerShell腳本取得警示

完成此範例需要多久時間？

只需要 5 分鐘的時間，即可完成兩個步驟：

• 應用程式註冊
• 使用範例：只需要複製/貼上簡短的 PowerShell 腳本

我需要連線的許可權嗎？

針對應用程式註冊階段，您必須在 Microsoft Entra 租使用者中指派適當的角色。 如需角色的詳細資訊，請參閱 許可權選項。

步驟 1 - 在 Microsoft Entra ID 中建立應用程式

1. 登入 Azure 入口網站。

2. 流覽至 Microsoft Entra ID>應用程式註冊>新增註冊。

   

3. 在註冊表單中，選擇應用程式的名稱，然後選取 [ 註冊]。

4. 允許您的應用程式存取適用於端點的Defender，並指派「 讀取所有警示」 許可權：

   • 在您的應用程式頁面上，選取 [API 許可權>][新增許可權>API 我的組織使用> 類型 WindowsDefenderATP ]，然後選取 [WindowsDefenderATP]。

     注意事項

     WindowsDefenderATP 不會出現在原始清單中。 您必須開始在文字框中寫入其名稱，才能看到它出現。

     

   • 選擇 [應用程式許可權>Alert.Read.All]，然後選取 [ 新增許可權]。

     

     重要事項

     您必須選取相關的許可權。 唯讀取所有警示是一個範例。

     例如：

     • 若 要執行進階查詢，請選取 [執行進階查詢] 許可權。
     • 若 要隔離計算機，請選取 [隔離機器] 許可權。
     • 若要判斷您需要的許可權， 請參閱 您想要呼叫之 API 中的許可權一節。

5. 選 取 [授與同意]。

   注意事項

   每次新增許可權時，都必須按兩下 [ 授與同意 ]，新許可權才會生效。

   

6. 將秘密新增至應用程式。

   選 取 [憑證 & 秘密]，將描述新增至秘密，然後選取 [ 新增]。

   重要事項

   按兩下 [新增] 之後， 複製產生的秘密值。 離開之後就無法擷取！

   

7. 記下您的應用程式識別碼和租用戶標識碼。

   在您的應用程式頁面上，移至 [ 概觀 ] 並複製下列內容：

   

完成！ 您已成功註冊應用程式！

步驟 2 - 使用應用程式取得令牌，並使用此令牌來存取 API。

• 將下列文稿複製到 PowerShell ISE 或文字編輯器，並將它儲存為 Get-Token.ps1。

• 執行此文稿會產生令牌，並以 名稱 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
  

• 例行性檢查：

  • 執行指令碼。
  • 在瀏覽器中移至： https://jwt.ms/。
  • 將令牌複製 (Latest-token.txt 檔案) 的內容。
  • 貼到頂端方塊中。
  • 尋找 [角色] 區段。 尋找 Alert.Read.All 角色。

  

讓我們來取得警示！

• 下列腳本會使用 Get-Token.ps1 來存取 API，並取得過去 48 小時的警示。

• 將此文稿儲存在您儲存先前文稿 Get-Token.ps1的相同資料夾中。

• 腳本會建立兩個檔案， (json 和 csv) ，並將數據與腳本位於相同的資料夾中。

  # 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
• 使用 PowerShell 腳本傳回過去 48 小時內建立的警示

相關文章

• 適用於端點的 Microsoft Defender API
• 使用應用程式內容存取 適用於端點的 Microsoft Defender
• 使用用戶內容存取 適用於端點的 Microsoft Defender