Criar deteçãoRule

Espaço de nomes: microsoft.graph.security

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Crie um novo objeto detectionRule .

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão Permissões com menos privilégios Permissões com privilégios superiores
Delegado (conta corporativa ou de estudante) CustomDetection.ReadWrite.All Indisponível.
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application CustomDetection.ReadWrite.All Indisponível.

Importante

Para acesso delegado através de contas escolares ou profissionais, tem de ser atribuída ao utilizador com sessão iniciada uma função que conceda as permissões necessárias para esta operação. As regras de deteção personalizadas utilizam o Microsoft Defender XDR modelo de controlo de acesso baseado em funções (RBAC) unificado. As funções a seguir têm suporte:

  • Otimização da deteção (Gerir) – uma permissão RBAC unificada Microsoft Defender XDR que concede a gestão do acesso às deteções no portal do Microsoft Defender, incluindo deteções personalizadas, otimização de alertas e indicadores de ameaças de comprometimento.
  • Administrador de Segurança – uma função de Microsoft Entra que concede permissões de gestão em portais e serviços Microsoft Defender.
  • Operador de Segurança – uma função de Microsoft Entra. Suficiente para gerir regras de deteção personalizadas apenas quando o controlo de acesso baseado em funções é desativado no Microsoft Defender para Ponto de Extremidade. Se o RBAC estiver configurado, também é necessária a permissão Gerir Definições de Segurança do Defender para Endpoint.

Podem ser necessárias permissões adicionais específicas da carga de trabalho para gerir regras que visam dados de cargas de trabalho específicas do Defender (por exemplo, Defender para Endpoint, Defender para Office 365). Para obter mais informações, veja Permissões necessárias para gerir deteções personalizadas.

Solicitação HTTP

POST /security/rules/detectionRules

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type application/json. Obrigatório.

Corpo da solicitação

No corpo do pedido, forneça uma representação JSON do objeto microsoft.graph.security.detectionRule .

Pode especificar as seguintes propriedades e relações ao criar uma deteçãoRule.

Propriedade Tipo Descrição
description Cadeia de caracteres Uma descrição fornecida pelo utilizador da regra de deteção. Opcional.
detectionAction microsoft.graph.security.detectionAction As ações executadas quando uma deteção é efetuada por esta regra, incluindo o alerta que é criado e quaisquer ações de resposta automatizadas. Opcional.
displayName Cadeia de caracteres O nome de exibição da regra. Obrigatório.
id Cadeia de caracteres O identificador exclusivo fornecido pelo cliente da regra. Obrigatório.
isEnabled Booliano Depreciado. Em alternativa, utilize status. A isEnabled propriedade será removida deste recurso em 2026-10-01. Opcional.
queryCondition microsoft.graph.security.queryCondition A consulta de investigação avançada que define a lógica de deteção desta regra. Obrigatório.
Cronograma microsoft.graph.security.ruleSchedule A agenda de acionamento desta regra. Obrigatório.
status microsoft.graph.security.detectionRuleStatus A execução atual status da regra. Os valores possíveis são: enabled, disabled, autoDisabled, unknownFutureValue. Obrigatório.

Resposta

Se for bem-sucedido, este método devolve um 201 Created código de resposta e um objeto microsoft.graph.security.detectionRule no corpo da resposta.

Exemplos

Solicitação

O exemplo a seguir mostra uma solicitação.

POST https://graph.microsoft.com/beta/security/rules/detectionRules
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",
  "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",
            "ntDomainColumn": "AccountDomain",
            "sidColumn": "AccountSid"
          }
        ],
        "hosts": [
          {
            "deviceIdColumn": "DeviceId",
            "nameColumn": "DeviceName"
          }
        ],
        "files": [
          {
            "nameColumn": "FileName",
            "sha1Column": "SHA1",
            "sha256Column": "SHA256"
          }
        ]
      },
      "tactics": [
        {
          "tactic": "Execution",
          "techniques": [
            {
              "technique": "T1059.001"
            }
          ]
        }
      ]
    }
  }
}

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://graph.microsoft.com/beta/security/rules/detectionRules/office-encoded-powershell

{
  "@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-25T10:15: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"
        }
      ]
    }
  }
}
  • Last updated on