Hello World pro rozhraní REST API Microsoft Defender XDR
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.
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.
Přihlaste se k Azure.
Přejděte na Microsoft Entra ID>Registrace aplikací>Nová registrace.
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.
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.
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.
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.
Poznamenejte si ID aplikace a ID tenanta na bezpečném místu. Jsou uvedené v části Přehled na stránce vaší aplikace.
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.
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
Zkopírujte a vložte token, který jste obdrželi, do JWT a dekódujte ho.
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.All
aAdvancedHunting.Read.All
:
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.
- přehled rozhraní API Microsoft Defender XDR
- Přístup k rozhraním API Microsoft Defender XDR
- Vytvoření aplikace pro přístup k Microsoft Defender XDR bez uživatele
- Vytvoření aplikace pro přístup k rozhraním API Microsoft Defender XDR jménem uživatele
- Vytvoření 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
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.