Microsoft Defender 全面偵測回應 REST API 的 Hello World

  • 發行項

適用於：

  • Microsoft Defender XDR

重要事項

部分資訊與發行前版本產品有關，在正式發行之前可能會實質上進行修改。 Microsoft 對此處提供的資訊，不提供任何明確或隱含的瑕疵擔保。

使用簡單的PowerShell腳本取得事件

完成此專案需要 5 到 10 分鐘的時間。 此時間估計包括註冊應用程式，以及從 PowerShell 範例腳本套用程式代碼。

在 Microsoft Entra ID 中註冊應用程式

  1. 以具有 全域管理員 角色的使用者身分登入 Azure。

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

    Microsoft Defender 入口網站中的 [新增註冊] 區段

  3. 在註冊表單中，選擇應用程式的名稱，然後選取 [ 註冊]。 選取重新導向 URI 是選擇性的。 您不需要一個就能完成此範例。

  4. 在您的應用程式頁面上，選取 [API 許可權>][新增我的組織使用的>許可權 > API]，輸入 Microsoft 威脅防護，然後選取 [Microsoft 威脅防護]。 您的應用程式現在可以存取 Microsoft Defender 全面偵測回應。

    提示

    Microsoft 威脅防護是 Microsoft Defender 全面偵測回應 的先前名稱，不會出現在原始清單中。 您必須開始在文字框中寫入其名稱，才能看到它出現。 Microsoft Defender 入口網站中的 API 使用量區段

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

      Microsoft Defender 入口網站中的應用程式許可權窗格

  5. 選 取 [授與系統管理員同意]。 每次新增許可權時，您都必須選取 [ 授與系統管理員同意 ] 使其生效。

    Microsoft Defender 入口網站中的 [授與管理員同意] 區段

  6. 將秘密新增至應用程式。 選 取 [憑證 & 秘密]，將描述新增至秘密，然後選取 [ 新增]。

    提示

    選取 [ 新增] 之後，選取 [複製產生的秘密] 值。 離開之後，您將無法擷取秘密值。

    Microsoft Defender 入口網站中的 [新增秘密] 區段

  7. 在安全的地方記錄您的應用程式識別碼和租用戶標識碼。 它們會列在應用程式頁面的 [ 概觀 ] 底下。

    Microsoft Defender 入口網站中的 [概觀] 區段

使用應用程式取得令牌，並使用令牌來存取 API

如需 Microsoft Entra 令牌的詳細資訊，請參閱 Microsoft Entra 教學課程。

重要事項

雖然此示範應用程式中的範例鼓勵您貼入秘密值以供測試之用，但您絕對不應該將 秘密硬式編碼 成在生產環境中執行的應用程式。 第三方可以使用您的秘密來存取資源。 您可以使用 Azure 金鑰保存庫 來協助保護應用程式的秘密。 如需如何保護應用程式的實際範例，請參閱使用 Azure 金鑰保存庫 管理伺服器應用程式中的秘密。

  1. 複製下列文本，並將它貼到您最愛的文本編輯器中。 另存為 Get-Token.ps1。 您也可以在PowerShell ISE 中依原樣執行程序代碼，但您應該儲存它，因為我們在下一節中使用事件擷取腳本時，必須再次執行它。

    此文稿會產生權杖，並將它儲存在工作資料夾的名稱下 ，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 Web 令牌。 譯碼的令牌將包含一些 JSON 格式的專案或宣告。 請確定已譯碼令牌內 的角色 宣告包含所需的許可權。

    在下圖中，您可以看到從應用程式取得的已譯碼令牌， Incidents.Read.All以及 、 Incidents.ReadWrite.All和 AdvancedHunting.Read.All 權限：

    Microsoft Defender 入口網站中的 [已譯碼令牌] 區段

取得最近事件的清單

下列腳本會使用 Get-Token.ps1 來存取 API。 然後，它會擷取過去 48 小時內上次更新的事件清單，並將清單儲存為 JSON 檔案。

重要事項

將此文稿儲存在您 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。
  • 使用 PowerShell 腳本來傳回過去 48 小時內更新的事件。

提示

想要深入了解? Engage 技術社群中的 Microsoft 安全性社群：Microsoft Defender 全面偵測回應 技術社群。