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

注意事項

如果你是美國政府客戶，請使用 適用於端點的 Microsoft Defender for US Government 客戶中列出的 URI。

提示

為了提升效能，建議不要用 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

使用 PowerShell 腳本接收警報

看完這個範例需要多久？

只需5分鐘，分兩步完成：

• 申請註冊
• 舉例說明：只需要複製/貼上一個簡短的 PowerShell 腳本

我需要取得連線許可嗎？

在應用程式註冊階段，您必須在您的 Microsoft Entra 租戶中指定適當的角色。 欲了解更多職務細節，請參閱 權限選項。

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

1. 登入 Azure 入口網站。

2. 導航至 Microsoft Entra ID>應用程式註冊>新註冊。

   

3. 在報名表單中，選擇申請名稱，然後選擇 註冊。

4. 允許你的應用程式存取 Defender for Endpoint，並賦予 它「Read all alerts」 權限：

   • 在你的應用程式頁面，選擇 API 權限>新增我組織使用的>權限 > API，輸入 WindowsDefenderATP，然後選擇 WindowsDefenderATP。

     注意事項

     WindowsDefenderATP 不會出現在原始清單中。 你需要先在文字框裡寫下它的名字，這樣它才會出現。

     

   • 選擇 應用程式權限>Alert.Read.All，然後選擇 「新增權限」。

     

     重要事項

     你需要選擇相關的權限。 Read All Alerts 只是一個例子。

     例如：

     • 要 執行進階查詢，請選擇「執行進階查詢」權限。
     • 要 隔離機器，請選擇「隔離機器」權限。
     • 要判斷你需要哪個權限，請參考你想呼叫的 API 中的 權限 部分。

5. 選擇 授權同意。

   注意事項

   每次新增權限時，你必須點擊 「授予同意 」，新權限才會生效。

   

6. 在應用程式中加入一個秘密。

   選擇 「憑證 & 秘密」，為秘密新增描述，然後選擇 「新增」。

   重要事項

   點擊新增後， 複製產生的秘密值。 你離開後就拿不回來了！

   

7. 寫下你的申請編號和租戶編號。

   在申請頁面上，請前往 「概覽 」並複製以下內容：

   

完成！ 您已成功註冊申請！

步驟 2 - 透過應用程式取得令牌，並用這個令牌存取 API

提示

部分 適用於端點的 Microsoft Defender API 仍要求為舊有資源https://api.securitycenter.microsoft.com發放存取權杖。 如果令牌受眾與 API 預期的資源不符，請求也會失敗， 403 Forbidden即使 API 端點使用 https://api.security.microsoft.com。 在取得代幣時，請將其 https://api.securitycenter.microsoft.com 作為資源或範圍。

將以下腳本複製到 PowerShell ISE 或文字編輯器，並儲存為 Get-Token.ps1。 執行此腳本會產生一個權杖，並將其存於工作 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. 執行腳本來產生檔案 Latest-token.txt 。
2. 在網頁瀏覽器中，打開 https://jwt.ms/，然後將令牌複製 (下方 Enter 令牌中) 的內容Latest-token.txt。
3. 在 Decoded token 標籤中，找到 角色 區塊，並確認其中包含 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 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。
• 使用 PowerShell 腳本回傳過去 48 小時內產生的警示。

相關文章

• 適用於端點的 Microsoft Defender APIS
• Access 適用於端點的 Microsoft Defender 與應用程式上下文
• 適用於端點的 Microsoft Defender 與使用者情境

提示

想要深入了解? Engage 與 Microsoft Security 社群互動，加入我們的技術社群：適用於端點的 Microsoft Defender Defender 技術社群。