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

S’applique à :

• Microsoft Defender pour point de terminaison Plan 2

Vous voulez découvrir Microsoft Defender pour point de terminaison ? Inscrivez-vous pour bénéficier d’un essai gratuit.

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).

Configuration minimale requise

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

• Vérifiez que vous exécutez une version prise en charge de Windows, macOS ou Linux.

  Les appareils doivent exécuter l’une des opérations suivantes :

  • Windows 11

  • Windows 10

    • Version 1909 ou ultérieure
    • Version 1903 avec KB4515384
    • Version 1809 (RS 5) avec KB4537818
    • Version 1803 (RS 4) avec KB4537795
    • Version 1709 (RS 3) avec KB4537816

  • Windows Server 2019 - Applicable uniquement pour la préversion publique

    • Version 1903 ou (avec KB4515384) ultérieure
    • Version 1809 (avec KB4537818)

  • Windows Server 2022

  • macOS(nécessite des profils de configuration supplémentaires)

    • 13 (Ventura)
    • 12 (Monterey)
    • 11 (Big Sur)

  • Linux

    • Distributions de serveur Linux et versions du noyau prises en charge

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.

Requête HTTP

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

En-têtes de demande

Corps de la demande

Commandes

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 état de commande sont « Créé », « Terminé » et « Échec ».

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"
                    }
                ]
            }
        }
    ]
}

Voir aussi

• OBTENIR l’API d’action de l’ordinateur
• Obtenir le résultat de la réponse en direct
• Annuler l’action de l’ordinateur