API de chasse avancée Microsoft 365 Defender

  • Article
  • 3 minutes de lecture

Remarque

Vous voulez essayer Microsoft 365 Defender ? En savoir plus sur la façon dont vous pouvez évaluer et piloter Microsoft 365 Defender.

S’applique à :

  • Microsoft 365 Defender

Remarque

Essayez nos nouvelles API à l’aide de l’API de sécurité MS Graph. Pour plus d’informations, consultez : Utiliser l’API de sécurité Microsoft Graph - Microsoft graph bêta | Microsoft Learn.

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 365 Defender. 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’à 45 appels par minute et par locataire.
  4. Les requêtes sont bloquées si le client a atteint 100 % jusqu’au terme du cycle de 15 minutes suivant.
  5. Si une seule requête s’exécute pendant plus de 10 minutes, elle expire et retourne une erreur.
  6. Un 429 code de réponse HTTP indique que vous avez atteint un quota, 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.

Remarque

Tous les quotas répertoriés ci-dessus (par exemple, 15 appels par min) sont à l’échelle du locataire. Ces quotas sont le minimum.

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 365 Defender 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 Text 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"
        }
    ]
}