> ## 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

> Integração bidirecional entre o CaseBender e o Microsoft Defender XDR (Windows Defender) para ingestão de alertas/incidentes e sincronização de disposições.

## Visão geral

A integração do Microsoft Defender XDR (**INT-021**) fornece sincronização **bidirecional**
entre o CaseBender e a plataforma de detecção e resposta estendidas da Microsoft, incluindo o
**Microsoft Defender para Endpoint (MDE)** e o **Microsoft Defender XDR**.

<CardGroup cols={2}>
  <Card title="Ingestão de entrada" icon="arrow-right-to-bracket">
    Alertas e incidentes do Defender são ingeridos no CaseBender, normalizados, enriquecidos com
    observáveis e técnicas MITRE ATT\&CK e transformados em alertas/casos.
  </Card>

  <Card title="Sincronização de saída" icon="arrow-right-from-bracket">
    Quando um caso do CaseBender é fechado, o alerta/incidente vinculado do Defender é atualizado
    com o status, a classificação e um comentário de auditoria via Microsoft Graph.
  </Card>
</CardGroup>

<Note>
  Esta integração usa a **API de Segurança do Microsoft Graph**
  (`https://graph.microsoft.com/v1.0/security`). Ela se autentica com um **aplicativo do
  Azure AD (Entra ID)** usando o fluxo de credenciais de cliente OAuth2.
</Note>

## Recursos

| Recurso                     | Direção      | Descrição                                                                                                    |
| --------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------ |
| Ingestão de alertas         | Entrada      | Alertas do Defender são normalizados em alertas do CaseBender                                                |
| Ingestão de incidentes      | Entrada      | Incidentes do Defender (com alertas filhos) são ingeridos                                                    |
| Extração de observáveis     | Entrada      | IPs, URLs, hashes de arquivos, nomes de arquivos, hostnames e contas de usuário são extraídos das evidências |
| Extração de ativos          | Entrada      | Hostname, IP e plataforma de SO do dispositivo são capturados de `devices[]`                                 |
| Correlação MITRE ATT\&CK    | Entrada      | IDs de técnica são adicionados como tags e TTPs (ex.: `mitre:T1078`)                                         |
| Sincronização de alertas    | Saída        | `status`, `classification`, `determination` e comentários são enviados ao fechar o caso                      |
| Sincronização de incidentes | Saída        | `status`, `classification`, `determination` e comentários são enviados ao fechar o caso                      |
| Teste de conexão            | Bidirecional | Valida as credenciais OAuth2 e o acesso à API de Segurança do Graph                                          |

## Pré-requisitos

<Steps>
  <Step title="Acesso ao Microsoft Defender / Entra ID">
    Um locatário do Microsoft Entra ID (Azure AD) com o Microsoft Defender XDR ou o Microsoft
    Defender para Endpoint licenciado e habilitado. Você precisa de permissão para registrar
    aplicativos e conceder consentimento do administrador.
  </Step>

  <Step title="Saída de rede">
    A implantação do CaseBender deve conseguir alcançar:

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

  <Step title="Função de administrador do CaseBender">
    Você deve conseguir criar e gerenciar integrações em **Configurações → Integrações**.
  </Step>
</Steps>

## Parte A — Registrar um aplicativo do Azure AD

<Steps>
  <Step title="Criar o registro do aplicativo">
    No [centro de administração do Microsoft Entra](https://entra.microsoft.com), vá para
    **Identidade → Aplicativos → Registros de aplicativo → Novo registro**. Dê um nome
    (ex.: `CaseBender Defender Integration`) e registre-o.
  </Step>

  <Step title="Registrar os identificadores">
    Na **Visão geral** do aplicativo, copie o **ID do aplicativo (cliente)** e o **ID do
    diretório (locatário)**. Você os inserirá no CaseBender.
  </Step>

  <Step title="Criar um segredo do cliente">
    Em **Certificados e segredos → Novo segredo do cliente**, crie um segredo e copie o seu
    **Valor** imediatamente (ele é exibido apenas uma vez).
  </Step>

  <Step title="Conceder permissões da API de Segurança do Graph">
    Em **Permissões de API → Adicionar uma permissão → Microsoft Graph → Permissões de
    aplicativo**, adicione o seguinte e clique em **Conceder consentimento do administrador**:

    | Permissão                        | Finalidade                             |
    | -------------------------------- | -------------------------------------- |
    | `SecurityAlert.ReadWrite.All`    | Ler e atualizar alertas do Defender    |
    | `SecurityIncident.ReadWrite.All` | Ler e atualizar incidentes do Defender |

    <Warning>
      Use permissões de **Aplicativo** (não Delegadas). A integração é executada de forma
      headless com o fluxo de credenciais de cliente e requer o consentimento do administrador do locatário.
    </Warning>
  </Step>
</Steps>

## Parte B — Configurar a integração no CaseBender

<Steps>
  <Step title="Abrir o catálogo de integrações">
    Vá para **Configurações → Integrações → Criar** e escolha **Microsoft Defender XDR** na
    categoria **EDR/XDR**.
  </Step>

  <Step title="Inserir as credenciais do Azure AD">
    Forneça os valores capturados na Parte A:

    | Campo          | Descrição                   |
    | -------------- | --------------------------- |
    | `tenantId`     | ID do diretório (locatário) |
    | `clientId`     | ID do aplicativo (cliente)  |
    | `clientSecret` | Valor do segredo do cliente |
  </Step>

  <Step title="Configurar as opções de sincronização">
    Habilite os comportamentos necessários:

    | Opção                       | Efeito                                                                   |
    | --------------------------- | ------------------------------------------------------------------------ |
    | `syncCaseUpdates`           | Enviar atualizações do caso para o Defender                              |
    | `syncCaseClose`             | Enviar o fechamento do caso para o Defender                              |
    | `autoCreateCases`           | Criar casos automaticamente a partir de incidentes do Defender ingeridos |
    | `closeAlertsOnCaseClose`    | Resolver o **alerta** vinculado do Defender ao fechar um caso            |
    | `closeIncidentsOnCaseClose` | Resolver o **incidente** vinculado do Defender ao fechar um caso         |
  </Step>

  <Step title="Testar a conexão">
    Use **Testar conexão** para validar. O CaseBender solicita um token OAuth2 e chama
    `GET /security/alerts_v2?$top=1`.

    <Note>
      Uma resposta `403` durante o teste é tratada como **sucesso** — ela confirma que a
      autenticação funcionou mesmo quando o aplicativo ainda não recebeu o escopo de leitura
      naquele endpoint específico.
    </Note>
  </Step>
</Steps>

## Entrada: Ingestão de alertas e incidentes do Defender

### Endpoint

O Defender (ou um intermediário como Logic Apps, Sentinel ou um encaminhador de webhook) envia
as cargas de alertas/incidentes para o endpoint de ingestão do CaseBender:

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

As solicitações são autenticadas com uma **chave de API** de integração no cabeçalho
`x-api-key` (o cabeçalho `authorization: Bearer <chave>` também é aceito). As chaves de API de
webhook do Defender têm o prefixo `sk_def_`.

### Formatos de carga

Tanto o formato em **lote** (array `value[]` do Graph) quanto um objeto de **alerta único** são
suportados.

<CodeGroup>
  ```bash Lote (value[] do Graph) theme={null}
  curl -X POST "https://<seu-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": "Execução suspeita 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 único theme={null}
  curl -X POST "https://<seu-dominio-casebender>/api/v1/ingest/defender" \
    -H "x-api-key: sk_def_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "da637...",
      "title": "Malware detectado no endpoint",
      "severity": "medium",
      "status": "new",
      "createdDateTime": "2026-07-03T18:20:00Z"
    }'
  ```
</CodeGroup>

Uma solicitação bem-sucedida retorna HTTP `202 Accepted`:

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

### Pipeline de processamento

<Steps>
  <Step title="Proxy de ingestão">
    `/api/v1/ingest/defender` valida a origem e encaminha a solicitação ao serviço de ingestão
    (`POST /v1/sources/defender`).
  </Step>

  <Step title="Publicação na fila">
    O serviço de ingestão autentica a chave de API, valida a carga e publica cada alerta na fila
    de processamento.
  </Step>

  <Step title="Normalização">
    O processador do Defender normaliza cada registro em um alerta do CaseBender: mapeia a
    gravidade, constrói o título/descrição, extrai observáveis e ativos de dispositivo e gera os
    TTPs do MITRE.
  </Step>
</Steps>

### Referência de mapeamento de dados

**Mapeamento de gravidade** (Defender → CaseBender 1–4):

| Gravidade do Defender | Gravidade do CaseBender |
| --------------------- | ----------------------- |
| `high`                | 1                       |
| `medium`              | 2                       |
| `low`                 | 3                       |
| `informational`       | 4                       |
| `unknown`             | 3                       |

**Extração de observáveis** (de `evidence[]`):

| Campo de evidência | Tipo de observável       |
| ------------------ | ------------------------ |
| `ipAddress`        | `ip`                     |
| `url`              | `url`                    |
| `sha256`           | `hash`                   |
| `fileName`         | `filename`               |
| `deviceDnsName`    | `hostname`               |
| `userAccount`      | `user` (`DOMÍNIO\conta`) |

As tags aplicadas na ingestão incluem `defender`, `xdr`, `service:<serviceSource>`,
`category:<category>`, `incident` (para incidentes) e uma tag `mitre:<technique>` por técnica do
MITRE. Os registros ingeridos usam por padrão **TLP:2** e **PAP:2**.

## Saída: Sincronizar disposições de casos com o Defender

Quando um caso é fechado no CaseBender, o evento `case_closed` é despachado para o manipulador do
Defender. Se o caso estiver vinculado a um alerta ou incidente do Defender, o CaseBender envia a
resolução por meio da API de Segurança do Graph.

### Como a entidade vinculada do Defender é resolvida

O manipulador procura os identificadores do Defender nesta ordem:

1. `extraData.defenderAlertId` / `extraData.defenderIncidentId`
2. `sourceRef` quando `extraData.source === "defender"`
3. `sourceRef` quando parece uma referência de alerta do Defender (prefixo `da`)

Se nenhum ID de alerta ou incidente for encontrado, o fechamento do caso é ignorado para esta integração.

### Mapeamento de resolução → classificação

| Resolução do CaseBender | Classificação do Defender       |
| ----------------------- | ------------------------------- |
| `TruePositive`          | `truePositive`                  |
| `FalsePositive`         | `falsePositive`                 |
| `Duplicate`             | `informationalExpectedActivity` |
| `NoImpact`              | `informationalExpectedActivity` |
| *(outra / nenhuma)*     | `truePositive` (padrão)         |

Ao fechar, o CaseBender define o `status` do alerta/incidente como `resolved`, aplica a
`classification` mapeada e adiciona um comentário como:

```
Case <id-do-caso> closed in CaseBender with resolution: <resolução>
```

<Note>
  As atualizações de saída de alertas exigem que `closeAlertsOnCaseClose` esteja habilitado; as
  de incidentes exigem `closeIncidentsOnCaseClose`. Se nenhuma estiver habilitada, não ocorre
  sincronização de saída.
</Note>

## Considerações de segurança

* **Tratamento de segredos** — o segredo do cliente é armazenado nas configurações da
  integração; alterne-o conforme o cronograma exigido pela sua organização e atualize a integração.
* **Privilégio mínimo** — conceda apenas `SecurityAlert.ReadWrite.All` e
  `SecurityIncident.ReadWrite.All`. Não adicione escopos mais amplos do Graph.
* **Cache de tokens** — os tokens de acesso são armazenados em cache na memória por integração e
  atualizados um minuto antes da expiração; nenhum token é persistido em disco.
* **Chaves de webhook** — trate a chave de API `sk_def_` como um segredo. Alterne-a se exposta e
  atualize a configuração do remetente.
* **Rede** — restrinja a saída a `login.microsoftonline.com` e `graph.microsoft.com`.

## Solução de problemas

<AccordionGroup>
  <Accordion title="O teste de conexão falha com um erro OAuth2">
    Verifique `tenantId`, `clientId` e `clientSecret`. Confirme que o segredo do cliente não
    expirou e que o consentimento do administrador foi concedido para as permissões do aplicativo do Graph.
  </Accordion>

  <Accordion title="A ingestão retorna 401 Unauthorized">
    O cabeçalho `x-api-key` está ausente ou inválido. Confirme que você está enviando a chave
    `sk_def_` que corresponde à chave de API de webhook configurada da integração.
  </Accordion>

  <Accordion title="A ingestão retorna 400 'No alerts in payload'">
    A carga não tinha nem um array `value[]` nem um `id` de nível superior. Envie um objeto em
    lote do Graph ou um objeto de alerta único.
  </Accordion>

  <Accordion title="O fechamento do caso não atualiza o Defender">
    Certifique-se de que `closeAlertsOnCaseClose` / `closeIncidentsOnCaseClose` esteja habilitado
    e que o caso tenha um ID de alerta/incidente do Defender (via `extraData` ou `sourceRef`).
  </Accordion>

  <Accordion title="A atualização de saída retorna 403">
    O aplicativo do Azure AD não tem permissão de gravação. Confirme que
    `SecurityAlert.ReadWrite.All` e `SecurityIncident.ReadWrite.All` foram concedidos com
    consentimento do administrador.
  </Accordion>
</AccordionGroup>

## Documentação relacionada

* [Visão geral das integrações](./introduction.mdx)
* [API de Segurança do Microsoft Graph](https://learn.microsoft.com/pt-br/graph/api/resources/security-api-overview)
* [Microsoft Defender XDR](https://learn.microsoft.com/pt-br/defender-xdr/)