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.

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 approprié attribué dans votre locataire Microsoft Entra. Pour plus d’informations sur les rôles, consultez Options d’autorisation.

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

1. Connectez-vous au Portail Azure.

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

   

3. Dans le formulaire d’inscription, choisissez un nom pour votre application, puis sélectionnez 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, sélectionnez Autorisations d’API>Ajouter des API d’autorisation>que mon organization utilise> le type WindowsDefenderATP, puis sélectionnez 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’applicationAlert.Read.All, puis sélectionnez 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 dans l’API que vous souhaitez appeler.

5. Sélectionnez 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.

   Sélectionnez Certificats & secrets, ajoutez une description au secret, puis sélectionnez 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 suivant dans PowerShell ISE ou dans un éditeur de texte, puis enregistrez-le sous Get-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 suivant utilise Get-Token.ps1 pour accéder à l’API et obtient des alertes pour les dernières 48 heures.

• Enregistrez ce script dans le même dossier que celui où vous avez enregistré le script Get-Token.ps1précédent.

• 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 avez réussi à :

• 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

Articles connexes

• 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