Exécuter des commandes de réponse en direct sur un appareil
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
- ina.api.security.microsoft.com
Description de l’API
Exécute une séquence de commandes de réponse en direct sur un appareil
Limitations
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).
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 »).
Si l’ordinateur n’est pas disponible, la session est mise en file d’attente pendant trois jours maximum.
Délai d’expiration de la commande RunScript après 10 minutes.
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.
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.
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.
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 :
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
Windows Server 2022
macOS(nécessite des profils de configuration supplémentaires)
- 13 (Ventura)
- 12 (Monterey)
- 11 (Big Sur)
Linux
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 |
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 é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
Conseil
Voulez-vous en savoir plus ? Collaborez avec la communauté Microsoft Security dans notre communauté technique : Microsoft Defender pour point de terminaison Tech Community.