API Microsoft Defender pour point de terminaison - Hello World

S’applique à :

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.

Pointe

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

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com

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

Combien de temps faut-il pour suivre 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 d’inscription de l’application, vous devez avoir un rôle Administrateur général dans votre locataire Azure Active Directory (Azure AD).

Étape 1 : créer une application dans Azure Active Directory

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

  2. Accédez à l’inscriptionAzure Active Directory> inscriptions d'applications >New.

    Option inscriptions d'applications sous le volet Gérer dans le portail Azure Active Directory

  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 Autorisations d’API Ajouter des> APId’autorisation>que mon organisation utilise> de 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 l’afficher.

      Option d’autorisations d’API sous le volet Gérer dans le portail Azure Active Directory

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

      Le type d’autorisation et les volets de paramètres dans la page Demander des autorisations d’API

      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 un ordinateur, sélectionnez l’autorisation « Isoler l’ordinateur ».
      • 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.

    Option d’octroi de consentement d’autorisation dans le portail Azure Active Directory

  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 de secret générée. Vous ne pourrez pas récupérer après votre départ !

    Élément de & menu Certificats secrets dans le volet Gérer dans le portail Azure Active Directory

  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 :

    Volet Détails de l’application sous l’élément de menu Vue d’ensemble dans le portail Azure Active Directory

Terminé ! Vous avez inscrit une application avec succès !

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

  • Copiez le script ci-dessous dans PowerShell ISE ou dans un éditeur de texte, puis enregistrez-le en tant queGet-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 (contenu du fichier Latest-token.txt).
    • Collez dans la zone supérieure.
    • Recherchez la section « rôles ». Recherchez le rôle Alert.Read.All .

    Volet Jeton décodé pour jwt.ms

Permet d’obtenir les alertes!

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

  • Enregistrez ce script dans le dossier que 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
    

Vous avez terminé ! Vous venez de réussir :

  • Créé et inscrit et application
  • Autorisation accordée à cette application pour 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