Hello World pour Microsoft Defender XDR API REST
S’applique à :
- Microsoft Defender XDR
Important
Certaines informations ont trait à un produit préalablement publié, qui peut être modifié de manière significative avant sa publication commerciale. Microsoft n’offre aucune garantie, explicite ou implicite, concernant les informations fournies ici.
Ce projet doit prendre de 5 à 10 minutes. Cette estimation de temps inclut l’inscription de l’application et l’application du code à partir de l’exemple de script PowerShell.
Connectez-vous à Azure.
Accédez à Microsoft Entra ID>inscriptions d'applications>Nouvelle inscription.
Dans le formulaire d’inscription, choisissez un nom pour votre application, puis sélectionnez Inscrire. La sélection d’un URI de redirection est facultative. Vous n’en aurez pas besoin pour suivre cet exemple.
Dans la page de votre application, sélectionnez Api Autorisations> Ajouter des APId’autorisation>que mon organization utilise>, tapez Protection Microsoft contre les menaces, puis sélectionnez Protection Microsoft contre les menaces. Votre application peut désormais accéder à Microsoft Defender XDR.
Sélectionnez Accorder le consentement de l’administrateur. Chaque fois que vous ajoutez une autorisation, vous devez sélectionner Accorder le consentement administrateur pour qu’elle prenne effet.
Ajoutez un secret à l’application. Sélectionnez Certificats & secrets, ajoutez une description au secret, puis sélectionnez Ajouter.
Conseil
Après avoir sélectionné Ajouter, sélectionnez Copier la valeur du secret généré. Vous ne pourrez plus récupérer la valeur du secret après votre départ.
Enregistrez votre ID d’application et votre ID de locataire dans un endroit sûr. Ils sont répertoriés sous Vue d’ensemble sur la page de votre application.
Pour plus d’informations sur les jetons Microsoft Entra, consultez le tutoriel Microsoft Entra.
Important
Bien que l’exemple de cette application de démonstration vous encourage à coller votre valeur secrète à des fins de test, vous ne devez jamais coder en dur les secrets dans une application s’exécutant en production. Un tiers peut utiliser votre secret pour accéder aux ressources. Vous pouvez aider à sécuriser les secrets de votre application à l’aide d’Azure Key Vault. Pour obtenir un exemple pratique de la façon dont vous pouvez protéger votre application, consultez Gérer les secrets dans vos applications serveur avec Azure Key Vault.
Copiez le script ci-dessous et collez-le dans votre éditeur de texte favori. Enregistrez en tant que Get-Token.ps1. Vous pouvez également exécuter le code tel quel dans PowerShell ISE, mais vous devez l’enregistrer, car nous devrons l’exécuter à nouveau lorsque nous utiliserons le script de récupération des incidents dans la section suivante.
Ce script génère un jeton et l’enregistre dans le dossier de travail sous le nom ,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
Copiez et collez le jeton que vous avez reçu dans JWT pour le décoder.
JWT signifie JSON Web Token. Le jeton décodé contient un certain nombre d’éléments ou de revendications au format JSON. Vérifiez que la revendication de rôles dans le jeton décodé contient les autorisations souhaitées.
Dans l’image suivante, vous pouvez voir un jeton décodé acquis à partir d’une application, avec
Incidents.Read.All
les autorisations ,Incidents.ReadWrite.All
etAdvancedHunting.Read.All
:
Le script ci-dessous utilise Get-Token.ps1 pour accéder à l’API. Il récupère ensuite la liste des incidents qui ont été mis à jour pour la dernière fois au cours des dernières 48 heures et enregistre la liste sous forme de fichier JSON.
Important
Enregistrez ce script dans le même dossier que celui que vous avez enregistré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
C’est fini ! Vous avez réussi à :
- Création et inscription d’une application.
- Autorisation accordée à cette application de lire les alertes.
- Connecté à l’API.
- Vous avez utilisé un script PowerShell pour retourner les incidents mis à jour au cours des dernières 48 heures.
- Vue d’ensemble des API Microsoft Defender XDR
- Accéder aux API Microsoft Defender XDR
- Créer une application pour accéder à Microsoft Defender XDR sans utilisateur
- Créer une application pour accéder aux API Microsoft Defender XDR pour le compte d’un utilisateur
- Créer une application avec un accès partenaire multilocataire aux API Microsoft Defender XDR
- Gérer les secrets dans vos applications serveur avec Azure Key Vault
- Autorisation OAuth 2.0 pour la connexion utilisateur et l’accès à l’API
Conseil
Voulez-vous en savoir plus ? Collaborez avec la communauté Sécurité Microsoft dans notre communauté technique : Communauté technique Microsoft Defender XDR.