> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casebender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Defender XDR

> Integración bidireccional entre CaseBender y Microsoft Defender XDR (Windows Defender) para la ingesta de alertas/incidentes y la sincronización de disposiciones.

## Descripción general

La integración de Microsoft Defender XDR (**INT-021**) proporciona sincronización
**bidireccional** entre CaseBender y la plataforma de detección y respuesta extendida de
Microsoft, incluidos **Microsoft Defender para Endpoint (MDE)** y **Microsoft Defender XDR**.

<CardGroup cols={2}>
  <Card title="Ingesta entrante" icon="arrow-right-to-bracket">
    Las alertas e incidentes de Defender se ingieren en CaseBender, se normalizan, se enriquecen
    con observables y técnicas MITRE ATT\&CK, y se convierten en alertas/casos.
  </Card>

  <Card title="Sincronización saliente" icon="arrow-right-from-bracket">
    Cuando se cierra un caso en CaseBender, la alerta/incidente vinculado de Defender se
    actualiza con el estado, la clasificación y un comentario de auditoría mediante Microsoft Graph.
  </Card>
</CardGroup>

<Note>
  Esta integración utiliza la **API de seguridad de Microsoft Graph**
  (`https://graph.microsoft.com/v1.0/security`). Se autentica con una **aplicación de Azure AD
  (Entra ID)** mediante el flujo de credenciales de cliente OAuth2.
</Note>

## Capacidades

| Capacidad                    | Dirección     | Descripción                                                                                                |
| ---------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
| Ingesta de alertas           | Entrante      | Las alertas de Defender se normalizan en alertas de CaseBender                                             |
| Ingesta de incidentes        | Entrante      | Se ingieren incidentes de Defender (con alertas secundarias)                                               |
| Extracción de observables    | Entrante      | Se extraen IP, URL, hashes de archivos, nombres de archivo, hostnames y cuentas de usuario de la evidencia |
| Extracción de activos        | Entrante      | Se capturan hostname, IP y plataforma del SO del dispositivo desde `devices[]`                             |
| Correlación MITRE ATT\&CK    | Entrante      | Los ID de técnica se agregan como etiquetas y TTP (p. ej. `mitre:T1078`)                                   |
| Sincronización de alertas    | Saliente      | Se envían `status`, `classification`, `determination` y comentarios al cerrar el caso                      |
| Sincronización de incidentes | Saliente      | Se envían `status`, `classification`, `determination` y comentarios al cerrar el caso                      |
| Prueba de conexión           | Bidireccional | Valida las credenciales OAuth2 y el acceso a la API de seguridad de Graph                                  |

## Requisitos previos

<Steps>
  <Step title="Acceso a Microsoft Defender / Entra ID">
    Un inquilino de Microsoft Entra ID (Azure AD) con Microsoft Defender XDR o Microsoft Defender
    para Endpoint con licencia y habilitado. Necesita permiso para registrar aplicaciones y
    conceder el consentimiento del administrador.
  </Step>

  <Step title="Salida de red">
    El despliegue de CaseBender debe poder alcanzar:

    * `https://login.microsoftonline.com` (endpoint de token OAuth2)
    * `https://graph.microsoft.com` (API de seguridad de Graph)
  </Step>

  <Step title="Rol de administrador de CaseBender">
    Debe poder crear y gestionar integraciones en **Configuración → Integraciones**.
  </Step>
</Steps>

## Parte A — Registrar una aplicación de Azure AD

<Steps>
  <Step title="Crear el registro de la aplicación">
    En el [centro de administración de Microsoft Entra](https://entra.microsoft.com), vaya a
    **Identidad → Aplicaciones → Registros de aplicaciones → Nuevo registro**. Asígnele un nombre
    (p. ej. `CaseBender Defender Integration`) y regístrela.
  </Step>

  <Step title="Registrar los identificadores">
    Desde **Información general** de la aplicación, copie el **ID de aplicación (cliente)** y el
    **ID de directorio (inquilino)**. Los introducirá en CaseBender.
  </Step>

  <Step title="Crear un secreto de cliente">
    En **Certificados y secretos → Nuevo secreto de cliente**, cree un secreto y copie su
    **Valor** de inmediato (solo se muestra una vez).
  </Step>

  <Step title="Conceder permisos de la API de seguridad de Graph">
    En **Permisos de API → Agregar un permiso → Microsoft Graph → Permisos de aplicación**,
    agregue lo siguiente y luego haga clic en **Conceder consentimiento de administrador**:

    | Permiso                          | Propósito                                |
    | -------------------------------- | ---------------------------------------- |
    | `SecurityAlert.ReadWrite.All`    | Leer y actualizar alertas de Defender    |
    | `SecurityIncident.ReadWrite.All` | Leer y actualizar incidentes de Defender |

    <Warning>
      Use permisos de **Aplicación** (no Delegados). La integración se ejecuta sin interacción
      con el flujo de credenciales de cliente y requiere el consentimiento del administrador del inquilino.
    </Warning>
  </Step>
</Steps>

## Parte B — Configurar la integración en CaseBender

<Steps>
  <Step title="Abrir el catálogo de integraciones">
    Vaya a **Configuración → Integraciones → Crear** y elija **Microsoft Defender XDR** en la
    categoría **EDR/XDR**.
  </Step>

  <Step title="Introducir las credenciales de Azure AD">
    Proporcione los valores obtenidos en la Parte A:

    | Campo          | Descripción                  |
    | -------------- | ---------------------------- |
    | `tenantId`     | ID de directorio (inquilino) |
    | `clientId`     | ID de aplicación (cliente)   |
    | `clientSecret` | Valor del secreto de cliente |
  </Step>

  <Step title="Configurar las opciones de sincronización">
    Habilite los comportamientos que necesite:

    | Opción                      | Efecto                                                                   |
    | --------------------------- | ------------------------------------------------------------------------ |
    | `syncCaseUpdates`           | Enviar actualizaciones del caso a Defender                               |
    | `syncCaseClose`             | Enviar el cierre del caso a Defender                                     |
    | `autoCreateCases`           | Crear casos automáticamente a partir de incidentes de Defender ingeridos |
    | `closeAlertsOnCaseClose`    | Resolver la **alerta** vinculada de Defender al cerrar un caso           |
    | `closeIncidentsOnCaseClose` | Resolver el **incidente** vinculado de Defender al cerrar un caso        |
  </Step>

  <Step title="Probar la conexión">
    Use **Probar conexión** para validar. CaseBender solicita un token OAuth2 y llama a
    `GET /security/alerts_v2?$top=1`.

    <Note>
      Una respuesta `403` durante la prueba se considera **correcta**: confirma que la
      autenticación funcionó incluso cuando la aplicación aún no tiene permiso de lectura en ese endpoint específico.
    </Note>
  </Step>
</Steps>

## Entrante: Ingesta de alertas e incidentes de Defender

### Endpoint

Defender (o un intermediario como Logic Apps, Sentinel o un reenviador de webhooks) envía
las cargas de alertas/incidentes al endpoint de ingesta de CaseBender:

```
POST https://<su-dominio-casebender>/api/v1/ingest/defender
```

Las solicitudes se autentican con una **clave de API** de integración en el encabezado
`x-api-key` (también se acepta el encabezado `authorization: Bearer <clave>`). Las claves de
API de webhook de Defender llevan el prefijo `sk_def_`.

### Formatos de carga

Se admiten tanto el formato **por lotes** (array `value[]` de Graph) como un objeto de
**alerta única**.

<CodeGroup>
  ```bash Lote (value[] de Graph) theme={null}
  curl -X POST "https://<su-dominio-casebender>/api/v1/ingest/defender" \
    -H "x-api-key: sk_def_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "value": [
        {
          "id": "da637...",
          "incidentId": "12345",
          "title": "Ejecución sospechosa de PowerShell",
          "severity": "high",
          "status": "new",
          "classification": "unknown",
          "createdDateTime": "2026-07-03T18:20:00Z",
          "mitreTechniques": ["T1059.001"],
          "evidence": [
            { "@odata.type": "#microsoft.graph.security.fileEvidence",
              "sha256": "9f2b...", "fileName": "payload.ps1" }
          ]
        }
      ]
    }'
  ```

  ```bash Alerta única theme={null}
  curl -X POST "https://<su-dominio-casebender>/api/v1/ingest/defender" \
    -H "x-api-key: sk_def_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "da637...",
      "title": "Malware detectado en el endpoint",
      "severity": "medium",
      "status": "new",
      "createdDateTime": "2026-07-03T18:20:00Z"
    }'
  ```
</CodeGroup>

Una solicitud correcta devuelve HTTP `202 Accepted`:

```json theme={null}
{ "success": true, "processed": 1, "failed": 0 }
```

### Flujo de procesamiento

<Steps>
  <Step title="Proxy de ingesta">
    `/api/v1/ingest/defender` valida el origen y reenvía la solicitud al servicio de ingesta
    (`POST /v1/sources/defender`).
  </Step>

  <Step title="Publicación en cola">
    El servicio de ingesta autentica la clave de API, valida la carga y publica cada alerta en
    la cola de procesamiento.
  </Step>

  <Step title="Normalización">
    El procesador de Defender normaliza cada registro en una alerta de CaseBender: asigna la
    severidad, construye el título/descripción, extrae observables y activos de dispositivo y
    genera TTP de MITRE.
  </Step>
</Steps>

### Referencia de mapeo de datos

**Mapeo de severidad** (Defender → CaseBender 1–4):

| Severidad de Defender | Severidad de CaseBender |
| --------------------- | ----------------------- |
| `high`                | 1                       |
| `medium`              | 2                       |
| `low`                 | 3                       |
| `informational`       | 4                       |
| `unknown`             | 3                       |

**Extracción de observables** (desde `evidence[]`):

| Campo de evidencia | Tipo de observable        |
| ------------------ | ------------------------- |
| `ipAddress`        | `ip`                      |
| `url`              | `url`                     |
| `sha256`           | `hash`                    |
| `fileName`         | `filename`                |
| `deviceDnsName`    | `hostname`                |
| `userAccount`      | `user` (`DOMINIO\cuenta`) |

Las etiquetas aplicadas en la ingesta incluyen `defender`, `xdr`, `service:<serviceSource>`,
`category:<category>`, `incident` (para incidentes) y una etiqueta `mitre:<technique>` por cada
técnica de MITRE. Los registros ingeridos usan por defecto **TLP:2** y **PAP:2**.

## Saliente: Sincronizar disposiciones de casos con Defender

Cuando se cierra un caso en CaseBender, el evento `case_closed` se despacha al controlador de
Defender. Si el caso está vinculado a una alerta o incidente de Defender, CaseBender envía la
resolución a través de la API de seguridad de Graph.

### Cómo se resuelve la entidad vinculada de Defender

El controlador busca los identificadores de Defender en este orden:

1. `extraData.defenderAlertId` / `extraData.defenderIncidentId`
2. `sourceRef` cuando `extraData.source === "defender"`
3. `sourceRef` cuando parece una referencia de alerta de Defender (prefijo `da`)

Si no se encuentra ningún ID de alerta o incidente, se omite el cierre del caso para esta integración.

### Mapeo de resolución → clasificación

| Resolución de CaseBender | Clasificación de Defender       |
| ------------------------ | ------------------------------- |
| `TruePositive`           | `truePositive`                  |
| `FalsePositive`          | `falsePositive`                 |
| `Duplicate`              | `informationalExpectedActivity` |
| `NoImpact`               | `informationalExpectedActivity` |
| *(otra / ninguna)*       | `truePositive` (predeterminado) |

Al cerrar, CaseBender establece el `status` de la alerta/incidente en `resolved`, aplica la
`classification` mapeada y agrega un comentario como:

```
Case <id-caso> closed in CaseBender with resolution: <resolución>
```

<Note>
  Las actualizaciones salientes de alertas requieren habilitar `closeAlertsOnCaseClose`; las
  de incidentes requieren `closeIncidentsOnCaseClose`. Si ninguna está habilitada, no se
  produce sincronización saliente.
</Note>

## Consideraciones de seguridad

* **Manejo de secretos** — el secreto de cliente se almacena en la configuración de la
  integración; rótelo según lo requiera su organización y actualice la integración al hacerlo.
* **Privilegio mínimo** — conceda solo `SecurityAlert.ReadWrite.All` y
  `SecurityIncident.ReadWrite.All`. No agregue otros permisos de Graph.
* **Almacenamiento en caché de tokens** — los tokens de acceso se almacenan en memoria por
  integración y se actualizan un minuto antes de expirar; no se guardan en disco.
* **Claves de webhook** — trate la clave de API `sk_def_` como un secreto. Rótela si se expone
  y actualice la configuración del remitente.
* **Red** — restrinja la salida a `login.microsoftonline.com` y `graph.microsoft.com`.

## Solución de problemas

<AccordionGroup>
  <Accordion title="La prueba de conexión falla con un error de OAuth2">
    Verifique `tenantId`, `clientId` y `clientSecret`. Confirme que el secreto de cliente no ha
    expirado y que se concedió el consentimiento del administrador para los permisos de la aplicación de Graph.
  </Accordion>

  <Accordion title="La ingesta devuelve 401 Unauthorized">
    Falta el encabezado `x-api-key` o no es válido. Confirme que envía la clave `sk_def_` que
    coincide con la clave de API de webhook configurada de la integración.
  </Accordion>

  <Accordion title="La ingesta devuelve 400 'No alerts in payload'">
    La carga no tenía ni un array `value[]` ni un `id` de nivel superior. Envíe un objeto por
    lotes de Graph o un objeto de alerta única.
  </Accordion>

  <Accordion title="El cierre del caso no actualiza Defender">
    Asegúrese de que `closeAlertsOnCaseClose` / `closeIncidentsOnCaseClose` esté habilitado y de
    que el caso lleve un ID de alerta/incidente de Defender (mediante `extraData` o `sourceRef`).
  </Accordion>

  <Accordion title="La actualización saliente devuelve 403">
    La aplicación de Azure AD carece de permiso de escritura. Confirme que
    `SecurityAlert.ReadWrite.All` y `SecurityIncident.ReadWrite.All` estén concedidos con
    consentimiento del administrador.
  </Accordion>
</AccordionGroup>

## Documentación relacionada

* [Descripción general de integraciones](./introduction.mdx)
* [API de seguridad de Microsoft Graph](https://learn.microsoft.com/es-es/graph/api/resources/security-api-overview)
* [Microsoft Defender XDR](https://learn.microsoft.com/es-es/defender-xdr/)