Exécuter des commandes de réponse en direct sur un appareil

  • Article

S’applique à :

Importante

Certaines informations contenues dans cet article concernent le produit en préversion, qui peut être considérablement modifié avant sa publication commerciale. Microsoft n’offre aucune garantie, explicite ou implicite, concernant les informations fournies ici.

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

Description de l’API

Exécute une séquence de commandes de réponse en direct sur un appareil

Limitations

  1. Les limitations de débit pour cette API sont de 10 appels par minute (les requêtes supplémentaires sont traitées avec HTTP 429).

  2. 25 sessions en cours d’exécution simultanée (les demandes dépassant la limite de limitation reçoivent une réponse « 429 - Trop de requêtes »).

  3. Si l’ordinateur n’est pas disponible, la session est mise en file d’attente pendant trois jours maximum.

  4. Délai d’expiration de la commande RunScript après 10 minutes.

  5. Les commandes de réponse en direct ne peuvent pas être mises en file d’attente et ne peuvent être exécutées qu’une par une.

  6. Si l’ordinateur sur lequel vous essayez d’exécuter cet appel d’API se trouve dans un groupe d’appareils RBAC auquel aucun niveau de correction automatique n’est affecté, vous devez au moins activer le niveau de correction minimal pour un groupe d’appareils donné.

    Remarque

    La création de groupes d’appareils est prise en charge dans Defender pour point de terminaison Plan 1 et Plan 2.

  7. Plusieurs commandes de réponse en direct peuvent être exécutées sur un seul appel d’API. Toutefois, lorsqu’une commande de réponse dynamique échoue, toutes les actions suivantes ne sont pas exécutées.

  8. Plusieurs sessions de réponse en direct ne peuvent pas être exécutées sur le même ordinateur (si l’action de réponse en direct est déjà en cours d’exécution, les requêtes suivantes sont traitées avec HTTP 400 - ActiveRequestAlreadyExists).

Remarque

Les actions de réponse en direct lancées à partir de la page Appareil ne sont pas disponibles dans l’API machineactions.

Configuration minimale requise

Avant de pouvoir lancer une session sur un appareil, vérifiez que vous remplissez les conditions suivantes :

Autorisations

L’une des autorisations suivantes est nécessaire pour appeler cette API. Pour en savoir plus, notamment sur le choix des autorisations, consultez Prise en main.

Type d’autorisation Autorisation Nom complet de l’autorisation
Application Machine.LiveResponse Exécuter la réponse en direct sur un ordinateur spécifique
Déléguée (compte professionnel ou scolaire) Machine.LiveResponse Exécuter la réponse en direct sur un ordinateur spécifique

Requête HTTP

POST https://api.securitycenter.microsoft.com/API/machines/{machine_id}/runliveresponse

En-têtes de demande

Nom Type Description
Autorisation Chaîne Jeton du porteur<>. Obligatoire.
Content-Type string application/json. Obligatoire.

Corps de la demande

Paramètre Type Description
Commentaire Chaîne Commentaire à associer à l’action.
Commandes Tableau Commandes à exécuter. Les valeurs autorisées sont PutFile, RunScript, GetFile (doivent être dans cet ordre sans limite de répétitions).

Commandes

Type de commande Paramètres Description
Putfile Clé : FileName

Valeur : <nom de fichier>

 Place un fichier de la bibliothèque sur l’appareil. Les fichiers sont enregistrés dans un dossier de travail et sont supprimés lorsque l’appareil redémarre par défaut. REMARQUE : n’a pas de résultat de réponse.
RunScript Clé : ScriptName
Valeur : <Script à partir de la bibliothèque>

Clé : Args
Valeur : <Arguments de script>

 Exécute un script à partir de la bibliothèque sur un appareil.

Le paramètre Args est passé à votre script.

Délai d’expiration après 10 minutes.
GetFile Clé : Chemin d’accès
Valeur : <chemin d’accès au fichier>		 Collecter un fichier à partir d’un appareil. REMARQUE : Les barres obliques inverses dans le chemin d’accès doivent être placées dans une séquence d’échappement.

Réponse

  • Si elle réussit, cette méthode retourne 201 Created.

    Entité d’action. Si l’ordinateur avec l’ID spécifié est introuvable, 404 Est introuvable.

Exemple

Exemple de requête

Voici un exemple de demande.

POST https://api.securitycenter.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/runliveresponse

```JSON
{
   "Commands":[
      {
         "type":"RunScript",
         "params":[
            {
               "key":"ScriptName",
               "value":"minidump.ps1"
            },
            {
               "key":"Args",
               "value":"OfficeClickToRun"
            }

         ]
      },
      {
         "type":"GetFile",
         "params":[
            {
               "key":"Path",
               "value":"C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
            }
         ]
      }
   ],
   "Comment":"Testing Live Response API"
}

Exemple de réponse

Voici un exemple de réponse.

Les valeurs possibles pour chaque commande status sont « Created », « Completed » et « Failed ».

HTTP/1.1 200 Ok

Content-type : application/json

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#MachineActions/$entity",
    "id": "{machine_action_id}",
    "type": "LiveResponse",
    "requestor": "analyst@microsoft.com",
    "requestorComment": "Testing Live Response API",
    "status": "Pending",
    "machineId": "{machine_id}",
    "computerDnsName": "hostname",
    "creationDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
    "lastUpdateDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
    "errorHResult": 0,
    "commands": [
        {
            "index": 0,
            "startTime": null,
            "endTime": null,
            "commandStatus": "Created",
            "errors": [],
            "command": {
                "type": "RunScript",
                "params": [
                    {
                        "key": "ScriptName",
                        "value": "minidump.ps1"
                    },{
                        "key": "Args",
                        "value": "OfficeClickToRun"
                    }
                ]
            }
        }, {
            "index": 1,
            "startTime": null,
            "endTime": null,
            "commandStatus": "Created",
            "errors": [],
            "command": {
                "type": "GetFile",
                "params": [{
                        "key": "Path", "value": "C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
                    }
                ]
            }
        }
    ]
}

Conseil

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