Partager via

API Microsoft Defender pour point de terminaison - Hello World

  • Article

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.

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
  • ina.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 d’inscription de l’application, le rôle Administrateur général doit être attribué dans votre locataire Microsoft Entra.

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

  1. Connectez-vous au Portail Azure.

  2. Accédez à Microsoft Entra ID> Inscriptions >d’applicationsNouvelle inscription.

    L’option Inscriptions d’applications sous le volet Gérer du Centre d’administration Microsoft Entra

  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 Api Autorisations>Ajouter des API d’autorisation>que mon organisation utilise> , tapez 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.

      L’option Autorisations d’API sous le volet Gérer dans le Centre d’administration Microsoft Entra

    • Choisissez Autorisations >d’applicationAlert.Read.All, puis sélectionnez Ajouter des autorisations.

      Le type d’autorisation et les volets 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 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.

    L’option Accorder le consentement d’autorisation dans le Centre d’administration Microsoft Entra

  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 !

    L’élément de menu Certificats & secrets dans le volet Gérer du Centre d’administration Microsoft Entra

  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 Centre d’administration Microsoft Entra

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 .

    Volet Jeton décodé pour jwt.ms

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

Conseil

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