Partager via

Hello World pour Microsoft Defender XDR API REST

  • Article

S’applique à :

  • Microsoft Defender XDR

Importante

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.

Obtenir des incidents à l’aide d’un script PowerShell simple

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.

Inscrire une application dans Microsoft Entra ID

  1. Connectez-vous à Azure en tant qu’utilisateur avec le rôle Administrateur général.

  2. Accédez à Microsoft Entra ID>inscriptions d'applications>Nouvelle inscription.

    Section Nouvelle inscription dans le portail Microsoft Defender

  3. 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.

  4. 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.

    Conseil

    Microsoft Threat Protection est un ancien nom pour Microsoft Defender XDR et n’apparaît pas dans la liste d’origine. Vous devez commencer à écrire son nom dans la zone de texte pour le voir apparaître. Section d’utilisation des API dans le portail Microsoft Defender

    • Choisissez Autorisations>d’application Incident.Read.All et sélectionnez Ajouter des autorisations.

      Volet Autorisations d’une application dans le portail Microsoft Defender

  5. 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.

    Section Accorder un consentement administrateur dans le portail Microsoft Defender

  6. 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.

    Section Ajouter un secret dans le portail Microsoft Defender

  7. 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.

    Section Vue d’ensemble du portail Microsoft Defender

Obtenir un jeton à l’aide de l’application et utiliser le jeton pour accéder à l’API

Pour plus d’informations sur les jetons Microsoft Entra, consultez le tutoriel Microsoft Entra.

Importante

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.

  1. 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

Valider le jeton

  1. Copiez et collez le jeton que vous avez reçu dans JWT pour le décoder.

  2. 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.Allles autorisations , Incidents.ReadWrite.Allet AdvancedHunting.Read.All :

    Section Jeton décodé dans le portail Microsoft Defender

Obtenir la liste des incidents récents

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.

Importante

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.

Conseil

Voulez-vous en savoir plus ? Engage avec la communauté Microsoft Security dans notre communauté technique : Microsoft Defender XDR Tech Community.