Mettre à jour detectionRule

Espace de noms : microsoft.graph.security

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

Mettez à jour les propriétés d’un objet detectionRule .

Cette API est disponible dans les déploiements cloud nationaux suivants.

Service global Gouvernement américain L4 Gouvernement américain L5 (DOD) Chine exploitée par 21Vianet
✅ ❌ ❌ ❌

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme étant les moins privilégiées pour cette API. Utilisez une ou plusieurs autorisations privilégiées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, voir Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez la référence des autorisations.

Type d’autorisation Autorisations les moins privilégiées Autorisations à privilèges plus élevés
Déléguée (compte professionnel ou scolaire) CustomDetection.ReadWrite.All Non disponible.
Déléguée (compte Microsoft personnel) Non prise en charge. Non prise en charge.
Application CustomDetection.ReadWrite.All Non disponible.

Importante

Pour l’accès délégué à l’aide de comptes professionnels ou scolaires, l’utilisateur connecté doit se voir attribuer un rôle qui accorde les autorisations requises pour cette opération. Les règles de détection personnalisées utilisent le modèle de contrôle d’accès unifié en fonction du rôle (RBAC) de Microsoft Defender XDR. Les rôles suivants sont pris en charge :

  • Réglage de la détection (Gérer) : autorisation RBAC unifiée Microsoft Defender XDR qui accorde l’accès aux détections du portail Microsoft Defender, y compris les détections personnalisées, le réglage des alertes et les indicateurs de menace de compromission.
  • Administrateur de sécurité : rôle Microsoft Entra qui accorde des autorisations de gestion sur les portails et services Microsoft Defender.
  • Opérateur de sécurité : rôle Microsoft Entra. Suffisant pour gérer les règles de détection personnalisées uniquement lorsque le contrôle d’accès en fonction du rôle est désactivé dans Microsoft Defender pour point de terminaison. Si RBAC est configuré, l’autorisation Gérer les paramètres de sécurité pour Defender pour point de terminaison est également requise.

Des autorisations supplémentaires spécifiques aux charges de travail peuvent être nécessaires pour gérer les règles qui ciblent des données de charges de travail Defender spécifiques (par exemple, Defender pour point de terminaison, Defender pour Office 365). Pour plus d’informations, consultez Autorisations requises pour la gestion des détections personnalisées.

Requête HTTP

PATCH /security/rules/detectionRules/{detectionRuleId}

En-têtes de demande

Nom Description
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et les autorisations.
Content-Type application/json. Obligatoire.

Corps de la demande

Dans le corps de la demande, fournissez uniquement les valeurs des propriétés à mettre à jour. Les propriétés existantes qui ne sont pas incluses dans le corps de la demande conservent leurs valeurs précédentes ou sont recalculées en fonction des modifications apportées à d’autres valeurs de propriété.

Le tableau suivant spécifie les propriétés qui peuvent être mises à jour.

Propriété Type Description
description String Description fournie par l’utilisateur de la règle de détection.
detectionAction microsoft.graph.security.detectionAction Les actions effectuées lorsqu’une détection est effectuée par cette règle, y compris l’alerte créée et les actions de réponse automatisées.
displayName String Nom d’affichage de la règle.
isEnabled Boolean Déconseillé. Utilisez plutôt status. La isEnabled propriété sera supprimée de cette ressource le 2026-10-01.
queryCondition microsoft.graph.security.queryCondition Requête de repérage avancé qui définit la logique de détection de cette règle.
planifier microsoft.graph.security.ruleSchedule Calendrier de déclenchement de cette règle.
status microsoft.graph.security.detectionRuleStatus Le status d’exécution actuel de la règle. Les valeurs possibles sont : enabled, disabled, autoDisabled, unknownFutureValue.

Pour mettre à jour le paramètre de corrélation d’incident, spécifiez true ou false pour detectionAction/incidentConfiguration/isExcludedFromIncidentCorrelation. A null ou la valeur omise laisse le paramètre existant inchangé.

Réponse

En cas de réussite, cette méthode renvoie un 200 OK code de réponse et un objet microsoft.graph.security.detectionRule dans le corps de la réponse.

Exemples

Demande

L’exemple suivant illustre une demande.

PATCH https://graph.microsoft.com/beta/security/rules/detectionRules/office-encoded-powershell
Content-Type: application/json

{
  "detectionAction": {
    "incidentConfiguration": {
      "isExcludedFromIncidentCorrelation": true
    }
  }
}

Réponse

L’exemple suivant illustre la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.type": "#microsoft.graph.security.detectionRule",
  "id": "office-encoded-powershell",
  "displayName": "Suspicious encoded PowerShell from Office",
  "description": "Detects encoded PowerShell processes launched by Office applications, a common phishing payload pattern.",
  "status": "enabled",
  "createdBy": "alice@contoso.com",
  "createdDateTime": "2026-05-25T10:15:00Z",
  "lastModifiedBy": "alice@contoso.com",
  "lastModifiedDateTime": "2026-05-28T14:30:00Z",
  "queryCondition": {
    "queryText": "DeviceProcessEvents | where InitiatingProcessFileName in~ ('winword.exe','excel.exe','outlook.exe') | where FileName == 'powershell.exe' | where ProcessCommandLine has '-enc'"
  },
  "schedule": {
    "frequency": "PT1H"
  },
  "detectionAction": {
    "alertTemplate": {
      "title": "Suspicious encoded PowerShell from Office",
      "description": "An Office app launched an encoded PowerShell command, which may indicate phishing-driven code execution.",
      "severity": "high",
      "recommendedActions": "Investigate the parent Office document, isolate the device, and review the user's recent email activity.",
      "entityMappings": {
        "accounts": [
          {
            "nameColumn": "AccountName",
            "sidColumn": "AccountSid"
          }
        ]
      },
      "tactics": [
        {
          "tactic": "Execution",
          "techniques": [
            {
              "technique": "T1059.001"
            }
          ]
        }
      ]
    },
    "automatedActions": {
      "isolateDevices": [
        {
          "deviceIdColumn": "DeviceId",
          "isolationType": "full"
        }
      ],
      "initiateInvestigations": [
        {
          "deviceIdColumn": "DeviceId"
        }
      ]
    },
    "incidentConfiguration": {
      "isExcludedFromIncidentCorrelation": true
    }
  }
}