Hello World pro rozhraní REST API Microsoft Defender XDR

Platí pro:

• Microsoft Defender XDR

Získání incidentů pomocí jednoduchého skriptu PowerShellu

Dokončení tohoto projektu by mělo trvat 5 až 10 minut. Tento odhad času zahrnuje registraci aplikace a použití kódu z ukázkového skriptu PowerShellu.

Registrace aplikace v Microsoft Entra ID

1. Přihlaste se k Azure jako uživatel s rolí Globální správce.

2. Přejděte na Microsoft Entra ID>Registrace aplikací>Nová registrace.

   

3. V registračním formuláři zvolte název vaší aplikace a pak vyberte Zaregistrovat. Výběr identifikátoru URI přesměrování je volitelný. K dokončení tohoto příkladu ho nebudete potřebovat.

4. Na stránce aplikace vyberte Oprávnění> rozhraní API Přidat rozhraní APIoprávnění>, kterápoužívá> moje organizace, zadejte Microsoft Threat Protection a vyberte Microsoft Threat Protection. Vaše aplikace teď má přístup k Microsoft Defender XDR.

   Tip

   Microsoft Threat Protection je dřívější název Microsoft Defender XDR a nezobrazí se v původním seznamu. Aby se zobrazilo, musíte začít psát jeho název do textového pole.

   • Zvolte Oprávnění> aplikaceIncident.Read.All a vyberte Přidat oprávnění.

     

5. Vyberte Udělit souhlas správce. Pokaždé, když přidáte oprávnění, musíte vybrat Udělit souhlas správce , aby se toto oprávnění projevilo.

   

6. Přidejte do aplikace tajný kód. Vyberte Certifikáty & tajných kódů, přidejte popis tajného kódu a pak vyberte Přidat.

   Tip

   Po výběru možnosti Přidat vyberte zkopírování vygenerované hodnoty tajného kódu. Jakmile odejdete, nebudete moct načíst hodnotu tajného kódu.

   

7. Poznamenejte si ID aplikace a ID tenanta na bezpečném místu. Jsou uvedené v části Přehled na stránce vaší aplikace.

   

Získání tokenu pomocí aplikace a použití tokenu pro přístup k rozhraní API

Další informace o tokenech Microsoft Entra najdete v kurzu Microsoft Entra.

1. Zkopírujte níže uvedený skript a vložte ho do svého oblíbeného textového editoru. Uložit jako Get-Token.ps1. V prostředí PowerShell ISE můžete kód spustit tak, jak je, ale měli byste ho uložit, protože ho budeme muset znovu spustit, když použijeme skript pro načítání incidentů v další části.

   Tento skript vygeneruje token a uloží ho do pracovní složky pod názvem 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
   

Ověření tokenu

1. Zkopírujte a vložte token, který jste obdrželi, do JWT a dekódujte ho.

2. JWT je zkratka pro JSON Web Token. Dekódovaný token bude obsahovat řadu položek nebo deklarací identity ve formátu JSON. Ujistěte se, že deklarace identity rolí v dekódovaném tokenu obsahuje požadovaná oprávnění.

   Na následujícím obrázku vidíte dekódovaný token získaný z aplikace s oprávněními Incidents.Read.All, Incidents.ReadWrite.Alla AdvancedHunting.Read.All :

   

Získání seznamu nedávných incidentů

Následující skript použije pro přístup k rozhraní API Get-Token.ps1 . Potom načte seznam incidentů, které byly naposledy aktualizovány během posledních 48 hodin, a uloží ho jako soubor JSON.

# 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

Všechno je hotové! Úspěšně jste provedli následující:

• Vytvořili a zaregistrovali aplikaci.
• Dané aplikaci bylo uděleno oprávnění ke čtení upozornění.
• Připojeno k rozhraní API.
• Použil skript PowerShellu k vrácení incidentů aktualizovaných za posledních 48 hodin.

Související články

• přehled rozhraní API Microsoft Defender XDR
• Přístup k rozhraním API Microsoft Defender XDR
• Create aplikace pro přístup k Microsoft Defender XDR bez uživatele
• Create aplikace pro přístup k rozhraním API Microsoft Defender XDR jménem uživatele
• Create aplikace s přístupem partnera s více tenanty k rozhraním API Microsoft Defender XDR
• Správa tajných kódů v serverových aplikacích pomocí Azure Key Vault
• Autorizace OAuth 2.0 pro přihlašování uživatelů a přístup k rozhraní API