API de chasse avancée Microsoft Defender XDR

  • Article

S’applique à :

  • Microsoft Defender XDR

Avertissement

Cette API de repérage avancée est une version plus ancienne avec des fonctionnalités limitées. Une version plus complète de l’API de repérage avancée est déjà disponible dans l’API de sécurité Microsoft Graph. Consultez Repérage avancé à l’aide de l’API de sécurité Microsoft Graph

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.

La chasse avancée est un outil de chasse aux menaces qui utilise des requêtes spécialement construites pour examiner les données d’événement des 30 derniers jours dans Microsoft Defender XDR. Vous pouvez utiliser des requêtes de repérage avancées pour inspecter les activités inhabituelles, détecter les menaces possibles et même répondre aux attaques. L’API de repérage avancée vous permet d’interroger par programmation les données d’événement.

Quotas et allocation de ressources

Les conditions suivantes concernent toutes les requêtes.

  1. Les requêtes explorent et retournent des données des 30 derniers jours.
  2. Les résultats peuvent retourner jusqu’à 100 000 lignes.
  3. Vous pouvez effectuer jusqu’à au moins 45 appels par minute et par locataire. Le nombre d’appels varie selon le locataire en fonction de sa taille.
  4. Des ressources processeur sont allouées à chaque locataire, en fonction de la taille du locataire. Les requêtes sont bloquées si le locataire a atteint 100 % des ressources allouées jusqu’au terme du cycle de 15 minutes suivant. Pour éviter les requêtes bloquées en raison d’une consommation excessive, suivez les instructions fournies dans Optimiser vos requêtes pour éviter d’atteindre les quotas de processeur.
  5. Si une seule requête s’exécute pendant plus de trois minutes, elle expire et retourne une erreur.
  6. Un 429 code de réponse HTTP indique que vous avez atteint les ressources processeur allouées, soit par nombre de requêtes envoyées, soit par temps d’exécution alloué. Lisez le corps de la réponse pour comprendre la limite que vous avez atteinte.

Autorisations

L’une des autorisations suivantes est requise pour appeler l’API de repérage avancée. Pour en savoir plus, notamment sur le choix des autorisations, consultez Accéder aux API Microsoft Defender XDR Protection.

Type d’autorisation Autorisation Nom complet de l’autorisation
Application AdvancedHunting.Read.All Exécuter des requêtes avancées
Déléguée (compte professionnel ou scolaire) AdvancedHunting.Read Exécuter des requêtes avancées

Remarque

Lors de l’obtention d’un jeton à l’aide des informations d’identification de l’utilisateur :

  • L’utilisateur doit avoir le rôle « Afficher les données ».
  • L’utilisateur doit avoir accès à l’appareil, en fonction des paramètres du groupe d’appareils.

Requête HTTP

POST https://api.security.microsoft.com/api/advancedhunting/run

En-têtes de demande

En-tête Valeur
Autorisation Porteur {token} Remarque : obligatoire
Content-Type application/json

Corps de la demande

Dans le corps de la demande, fournissez un objet JSON avec les paramètres suivants :

Paramètre Type Description
Requête Texte Requête à exécuter. (obligatoire)

Réponse

Si elle réussit, cette méthode retourne 200 OKun objet QueryResponse dans le corps de la réponse.

L’objet response contient trois propriétés de niveau supérieur :

  1. Statistiques : dictionnaire des statistiques de performances des requêtes.
  2. Schéma : schéma de la réponse, liste de paires Name-Type pour chaque colonne.
  3. Résultats : liste des événements de chasse avancés.

Exemple

Dans l’exemple suivant, un utilisateur envoie la requête ci-dessous et reçoit un objet de réponse d’API contenant Stats, Schemaet Results.

Requête

{
    "Query":"DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}

Objet Response

{
    "Stats": {
        "ExecutionTime": 4.621215,
        "resource_usage": {
            "cache": {
                "memory": {
                    "hits": 773461,
                    "misses": 4481,
                    "total": 777942
                },
                "disk": {
                    "hits": 994,
                    "misses": 197,
                    "total": 1191
                }
            },
            "cpu": {
                "user": "00:00:19.0468750",
                "kernel": "00:00:00.0156250",
                "total cpu": "00:00:19.0625000"
            },
            "memory": {
                "peak_per_node": 236822432
            }
        },
        "dataset_statistics": [
            {
                "table_row_count": 2,
                "table_size": 102
            }
        ]
    },
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-08-30T06:38:35.7664356Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        },
        {
            "Timestamp": "2020-08-30T06:38:30.5163363Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        }
    ]
}

Conseil

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