Hallo Welt für Microsoft Defender XDR REST-API
Gilt für:
- Microsoft Defender XDR
Wichtig
Einige Informationen beziehen sich auf Vorabversionen von Produkten, die vor der kommerziellen Veröffentlichung noch erheblich geändert werden können. Microsoft übernimmt mit diesen Informationen keinerlei Gewährleistung, sei sie ausdrücklich oder konkludent.
Es sollte 5 bis 10 Minuten dauern, bis dieses Projekt abgeschlossen ist. Diese Zeitschätzung umfasst das Registrieren der Anwendung und das Anwenden des Codes aus dem PowerShell-Beispielskript.
Melden Sie sich bei Azure an.
Navigieren Sie zu Microsoft Entra ID>App-Registrierungen>Neue Registrierung.
Wählen Sie im Registrierungsformular einen Namen für Ihre Anwendung und dann Registrieren aus. Die Auswahl eines Umleitungs-URI ist optional. Sie benötigen keines, um dieses Beispiel abzuschließen.
Wählen Sie auf der Anwendungsseite API-Berechtigungen> Berechtigungs-APIs >hinzufügenaus,die meine organization verwendet>, geben Sie Microsoft Threat Protection ein, und wählen Sie Microsoft Threat Protection aus. Ihre App kann jetzt auf Microsoft Defender XDR zugreifen.
Wählen Sie Administratoreinwilligung erteilen aus. Jedes Mal, wenn Sie eine Berechtigung hinzufügen, müssen Sie Administratoreinwilligung erteilen auswählen, damit sie wirksam wird.
Fügen Sie der Anwendung ein Geheimnis hinzu. Wählen Sie Zertifikate & Geheimnisse aus, fügen Sie dem Geheimnis eine Beschreibung hinzu, und wählen Sie dann Hinzufügen aus.
Tipp
Nachdem Sie Hinzufügen ausgewählt haben, wählen Sie den generierten Geheimniswert kopieren aus. Sie können den Geheimniswert nach dem Verlassen nicht mehr abrufen.
Notieren Sie ihre Anwendungs-ID und Ihre Mandanten-ID an einem sicheren Ort. Sie werden auf der Anwendungsseite unter Übersicht aufgeführt.
Weitere Informationen zu Microsoft Entra Token finden Sie im tutorial Microsoft Entra.
Wichtig
Das Beispiel in dieser Demo-App empfiehlt Ihnen zwar, Ihren Geheimniswert zu Testzwecken einzufügen, aber Sie sollten Geheimnisse niemals in eine Anwendung hartcodieren , die in der Produktion ausgeführt wird. Ein Drittanbieter könnte Ihr Geheimnis für den Zugriff auf Ressourcen verwenden. Mithilfe von Azure Key Vault können Sie dazu beitragen, die Geheimnisse Ihrer App zu schützen. Ein praktisches Beispiel für den Schutz Ihrer App finden Sie unter Verwalten von Geheimnissen in Ihren Server-Apps mit Azure Key Vault.
Kopieren Sie das folgende Skript, und fügen Sie es in Ihren bevorzugten Text-Editor ein. Speichern Sie alsGet-Token.ps1. Sie können den Code auch unverändert in PowerShell ISE ausführen, aber Sie sollten ihn speichern, da wir ihn erneut ausführen müssen, wenn wir das Skript zum Abrufen von Vorfällen im nächsten Abschnitt verwenden.
Dieses Skript generiert ein Token und speichert es im Arbeitsordner unter dem Namen 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
Kopieren Sie das Token, das Sie erhalten haben, und fügen Sie es in JWT ein, um es zu decodieren.
JWT steht für JSON Web Token. Das decodierte Token enthält eine Reihe von Elementen oder Ansprüchen im JSON-Format. Stellen Sie sicher, dass der Rollenanspruch innerhalb des decodierten Tokens die gewünschten Berechtigungen enthält.
In der folgenden Abbildung sehen Sie ein decodiertes Token, das von einer App mit
Incidents.Read.All
den Berechtigungen ,Incidents.ReadWrite.All
undAdvancedHunting.Read.All
abgerufen wurde:
Das folgende Skript verwendet Get-Token.ps1 für den Zugriff auf die API. Anschließend wird eine Liste der Vorfälle abgerufen, die innerhalb der letzten 48 Stunden zuletzt aktualisiert wurden, und die Liste wird als JSON-Datei gespeichert.
Wichtig
Speichern Sie dieses Skript im gleichen Ordner, den Sie Get-Token.ps1gespeichert haben.
# 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
Fertig! Sie haben folgendes erfolgreich ausgeführt:
- Erstellt und registriert eine Anwendung.
- Dieser Anwendung wurde die Berechtigung zum Lesen von Warnungen erteilt.
- Mit der API verbunden.
- Es wurde ein PowerShell-Skript verwendet, um Vorfälle zurückzugeben, die in den letzten 48 Stunden aktualisiert wurden.
- Übersicht über Microsoft Defender XDR-APIs
- Zugreifen auf die Microsoft Defender XDR-APIs
- Erstellen einer App für den Zugriff auf Microsoft Defender XDR ohne Benutzer
- Erstellen einer App für den Zugriff auf Microsoft Defender XDR APIs im Namen eines Benutzers
- Erstellen einer App mit mehrinstanzenfähigem Partnerzugriff auf Microsoft Defender XDR-APIs
- Verwalten von Geheimnissen in Ihren Server-Apps mit Azure Key Vault
- OAuth 2.0-Autorisierung für Benutzeranmeldung und API-Zugriff
Tipp
Möchten Sie mehr erfahren? Wenden Sie sich an die Microsoft Security-Community in unserer Tech Community: Microsoft Defender XDR Tech Community.