API Microsoft Defender pour point de terminaison - Hello World

S’applique à :

• Microsoft Defender pour point de terminaison Plan 1
• Microsoft Defender pour point de terminaison Plan 2

Vous voulez découvrir Microsoft Defender pour point de terminaison ? Inscrivez-vous pour bénéficier d’un essai gratuit.

Remarque

Si vous êtes un client du gouvernement des États-Unis, utilisez les URI répertoriés dans Microsoft Defender pour point de terminaison pour les clients du gouvernement des États-Unis.

Conseil

Pour de meilleures performances, vous pouvez utiliser le serveur plus près de votre emplacement géographique :

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com

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

Combien de temps faut-il pour parcourir cet exemple ?

Cela ne prend que 5 minutes en deux étapes :

• Inscription de l’application
• Utiliser des exemples : nécessite uniquement le copier/coller d’un script PowerShell court

Ai-je besoin d’une autorisation pour me connecter ?

Pour l’étape Inscription de l’application, vous devez disposer d’un rôle Administrateur général dans votre locataire Microsoft Entra.

Étape 1 : Créer une application dans Microsoft Entra ID

1. Connectez-vous à Azure avec votre utilisateur Administrateur général.

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

   

3. Dans le formulaire d’inscription, choisissez un nom pour votre application, puis cliquez sur Inscrire.

4. Autorisez votre application à accéder à Defender pour point de terminaison et attribuez-lui l’autorisation « Lire toutes les alertes » :

   • Dans la page de votre application, cliquez sur Api Autorisations>Ajouter des API d’autorisation>que mon organization utilise> le type WindowsDefenderATP, puis cliquez sur WindowsDefenderATP.

     Remarque

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

     

   • Choisissez Autorisations d’application>Alert.Read.All> Cliquez sur Ajouter des autorisations.

     

     Importante

     Vous devez sélectionner les autorisations appropriées. « Lire toutes les alertes » n’est qu’un exemple !

     Par exemple :

     • Pour exécuter des requêtes avancées, sélectionnez l’autorisation « Exécuter des requêtes avancées ».
     • Pour isoler une machine, sélectionnez l’autorisation « Isoler la machine ».
     • Pour déterminer l’autorisation dont vous avez besoin, consultez la section Autorisations de l’API que vous souhaitez appeler.

5. Cliquez sur Accorder le consentement.

   Remarque

   Chaque fois que vous ajoutez une autorisation, vous devez cliquer sur Accorder le consentement pour que la nouvelle autorisation prenne effet.

   

6. Ajoutez un secret à l’application.

   Cliquez sur Certificats & secrets, ajoutez une description au secret, puis cliquez sur Ajouter.

   Importante

   Après avoir cliqué sur Ajouter, copiez la valeur du secret généré. Vous ne pourrez pas récupérer après votre départ !

   

7. Notez votre ID d’application et votre ID de locataire.

   Dans la page de votre application, accédez à Vue d’ensemble et copiez les éléments suivants :

   

Terminé ! Vous avez correctement inscrit une application !

Étape 2 : obtenir un jeton à l’aide de l’application et utiliser ce jeton pour accéder à l’API.

• Copiez le script ci-dessous dans PowerShell ISE ou dans un éditeur de texte, puis enregistrez-le sousGet-Token.ps1.

• L’exécution de ce script génère un jeton et l’enregistre dans le dossier de travail sous le nom Latest-token.txt.

  # That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
  # Paste below your Tenant ID, App ID and App Secret (App key).
  
  $tenantId = '' ### Paste your tenant ID here
  $appId = '' ### Paste your Application ID here
  $appSecret = '' ### Paste your Application secret here
  
  $resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
  $oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
  $authBody = [Ordered] @{
       resource = "$resourceAppIdUri"
       client_id = "$appId"
       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
  

• Vérification de l’intégrité :

  • Exécutez le script.
  • Dans votre navigateur, accédez à : https://jwt.ms/.
  • Copiez le jeton (le contenu du fichier Latest-token.txt).
  • Collez dans la zone supérieure.
  • Recherchez la section « rôles ». Recherchez le rôle Alert.Read.All .

  

Obtenons les alertes !

• Le script ci-dessous utilisera Get-Token.ps1 pour accéder à l’API et obtiendra les alertes des dernières 48 heures.

• Enregistrez ce script dans le dossier où vous avez enregistré le script précédent Get-Token.ps1.

• Le script crée deux fichiers (json et csv) avec les données dans le même dossier que les scripts.

  # Returns Alerts created in the past 48 hours.
  
  $token = ./Get-Token.ps1       #run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-Token.ps1
  
  # Get Alert from the last 48 hours. Make sure you have alerts in that time frame.
  $dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")
  
  # The URL contains the type of query and the time filter we create above
  # Read more about [other query options and filters](get-alerts.md).
  $url = "https://api.securitycenter.microsoft.com/api/alerts?`$filter=alertCreationTime ge $dateTime"
  
  # Set the WebRequest headers
  $headers = @{
      'Content-Type' = 'application/json'
      Accept = 'application/json'
      Authorization = "Bearer $token"
  }
  
  # Send the webrequest and get the results.
  $response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop
  
  # Extract the alerts from the results.
  $alerts =  ($response | ConvertFrom-Json).value | ConvertTo-Json
  
  # Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file
  $dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}
  
  # Save the result as json and as csv
  $outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"
  $outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"
  
  Out-File -FilePath $outputJsonPath -InputObject $alerts
  ($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation
  

C’est fini ! Vous venez de réussir :

• Créé et inscrit et application
• Autorisation accordée à cette application de lire les alertes
• Connexion de l’API
• Utilisation d’un script PowerShell pour retourner des alertes créées au cours des dernières 48 heures

Rubrique connexe

• API Microsoft Defender pour point de terminaison
• Accéder Microsoft Defender pour point de terminaison avec le contexte de l’application
• Accéder Microsoft Defender pour point de terminaison avec le contexte utilisateur

Conseil

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