Hello World pro rozhraní REST API Microsoft Defender XDR

  • Článek

Platí pro:

  • Microsoft Defender XDR

Důležité

Některé informace se týkají předprodeje produktu, který může být před komerčním vydáním podstatně změněn. Společnost Microsoft neposkytuje v souvislosti se zde uvedenými informacemi žádné výslovné ani předpokládané záruky.

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.

    Oddíl Nová registrace na portálu Microsoft Defender

  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. Část využití rozhraní API na portálu Microsoft Defender

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

      Podokno oprávnění aplikace na portálu Microsoft Defender

  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.

    Část Udělení souhlasu správce na portálu Microsoft Defender

  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.

    Oddíl přidání tajného kódu na portálu Microsoft Defender

  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.

    Část Přehled na portálu Microsoft Defender

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.

Důležité

I když příklad v této ukázkové aplikaci doporučuje vložit hodnotu tajného kódu pro účely testování, nikdy byste tajné kódy neměli pevně zakódovat do aplikace spuštěné v produkčním prostředí. Třetí strana může použít váš tajný kód pro přístup k prostředkům. Tajné kódy aplikace můžete zabezpečit pomocí Azure Key Vault. Praktický příklad ochrany aplikace najdete v tématu Správa tajných kódů v serverových aplikacích pomocí Azure Key Vault.

  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 :

    Oddíl Dekódovaný token na portálu Microsoft Defender

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.

Důležité

Uložte tento skript do stejné složky, kterou jste uložiliGet-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

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.

Tip

Chcete se dozvědět více? Spojte se s komunitou zabezpečení společnosti Microsoft v naší technické komunitě: Technická komunita Microsoft Defender XDR.