Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Espacio de nombres: microsoft.graph.security
Importante
Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.
Actualice las propiedades de un objeto detectionRule .
Esta API está disponible en las siguientes implementaciones nacionales de nube.
| Servicio global | Gobierno de EE. UU. L4 | Us Government L5 (DOD) | China operada por 21Vianet |
|---|---|---|---|
| ✅ | ❌ | ❌ | ❌ |
Permissions
Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.
| Tipo de permiso | Permisos con privilegios mínimos | Permisos con privilegios más altos |
|---|---|---|
| Delegado (cuenta profesional o educativa) | CustomDetection.ReadWrite.All | No disponible. |
| Delegado (cuenta personal de Microsoft) | No admitida. | No admitida. |
| Aplicación | CustomDetection.ReadWrite.All | No disponible. |
Importante
Para el acceso delegado mediante cuentas profesionales o educativas, al usuario que ha iniciado sesión se le debe asignar un rol que conceda los permisos necesarios para esta operación. Las reglas de detección personalizadas usan el modelo de control de acceso basado en rol unificado (RBAC) de Microsoft Defender XDR. Se admiten los siguientes roles:
- Optimización de detección (administrar):un permiso de RBAC unificado de Microsoft Defender XDR que concede acceso de administración a las detecciones en el portal de Microsoft Defender, incluidas las detecciones personalizadas, el ajuste de alertas y los indicadores de amenazas de riesgo.
- Administrador de seguridad: un rol de Microsoft Entra que concede permisos de administración en Microsoft Defender portales y servicios.
- Operador de seguridad: un rol de Microsoft Entra. Suficiente para administrar reglas de detección personalizadas solo cuando el control de acceso basado en rol está desactivado en Microsoft Defender para punto de conexión. Si se configura RBAC, también se requiere el permiso Administrar configuración de seguridad para Defender para punto de conexión.
Es posible que se necesiten permisos adicionales específicos de la carga de trabajo para administrar reglas destinadas a datos de cargas de trabajo específicas de Defender (por ejemplo, Defender para punto de conexión, Defender para Office 365). Para obtener más información, consulte Permisos necesarios para administrar detecciones personalizadas.
Solicitud HTTP
PATCH /security/rules/detectionRules/{detectionRuleId}
Encabezados de solicitud
| Nombre | Descripción |
|---|---|
| Authorization | {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización. |
| Content-Type | application/json. Obligatorio. |
Cuerpo de la solicitud
En el cuerpo de la solicitud, proporcione solo los valores de las propiedades que se van a actualizar. Las propiedades existentes que no se incluyen en el cuerpo de la solicitud mantienen sus valores anteriores o se recalculan en función de los cambios realizados en otros valores de propiedad.
En la tabla siguiente se especifican las propiedades que se pueden actualizar.
| Propiedad | Tipo | Descripción |
|---|---|---|
| description | Cadena | Descripción proporcionada por el usuario de la regla de detección. |
| detectionAction | microsoft.graph.security.detectionAction | Las acciones realizadas cuando esta regla realiza una detección, incluida la alerta que se crea y las acciones de respuesta automatizadas. |
| displayName | String | Nombre para mostrar de la regla. |
| isEnabled | Boolean | Obsoleto. Use el estado en su lugar. La isEnabled propiedad se quitará de este recurso el 2026-10-01. |
| queryCondition | microsoft.graph.security.queryCondition | Consulta de búsqueda avanzada que define la lógica de detección de esta regla. |
| schedule | microsoft.graph.security.ruleSchedule | Programación desencadenante de esta regla. |
| status | microsoft.graph.security.detectionRuleStatus | Estado de ejecución actual de la regla. Los valores posibles son: enabled, disabled, autoDisabled y unknownFutureValue |
Respuesta
Si se ejecuta correctamente, este método devuelve un 200 OK código de respuesta y un objeto microsoft.graph.security.detectionRule en el cuerpo de la respuesta.
Ejemplos
Solicitud
En el ejemplo siguiente se muestra la solicitud.
PATCH https://graph.microsoft.com/beta/security/rules/detectionRules/office-encoded-powershell
Content-Type: application/json
{
"status": "disabled",
"queryCondition": {
"queryText": "DeviceProcessEvents | where InitiatingProcessFileName in~ ('winword.exe','excel.exe','outlook.exe') | where FileName == 'powershell.exe' | where ProcessCommandLine has '-enc'"
}
}
Respuesta
En el ejemplo siguiente se muestra la respuesta.
Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.
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": "disabled",
"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"
}
]
}
}
}