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

> Integrazione bidirezionale tra CaseBender e Microsoft Defender XDR (Windows Defender) per l'acquisizione di avvisi/incidenti e la sincronizzazione delle disposizioni.

## Panoramica

L'integrazione Microsoft Defender XDR (**INT-021**) fornisce sincronizzazione
**bidirezionale** tra CaseBender e la piattaforma di rilevamento e risposta estesi di Microsoft,
inclusi **Microsoft Defender per endpoint (MDE)** e **Microsoft Defender XDR**.

<CardGroup cols={2}>
  <Card title="Acquisizione in entrata" icon="arrow-right-to-bracket">
    Gli avvisi e gli incidenti di Defender vengono acquisiti in CaseBender, normalizzati,
    arricchiti con osservabili e tecniche MITRE ATT\&CK e trasformati in avvisi/casi.
  </Card>

  <Card title="Sincronizzazione in uscita" icon="arrow-right-from-bracket">
    Quando un caso di CaseBender viene chiuso, l'avviso/incidente Defender collegato viene
    aggiornato con stato, classificazione e un commento di audit tramite Microsoft Graph.
  </Card>
</CardGroup>

<Note>
  Questa integrazione utilizza l'**API di sicurezza di Microsoft Graph**
  (`https://graph.microsoft.com/v1.0/security`). Si autentica con un'**applicazione Azure AD
  (Entra ID)** tramite il flusso di credenziali client OAuth2.
</Note>

## Funzionalità

| Funzionalità               | Direzione     | Descrizione                                                                                   |
| -------------------------- | ------------- | --------------------------------------------------------------------------------------------- |
| Acquisizione avvisi        | In entrata    | Gli avvisi Defender vengono normalizzati in avvisi CaseBender                                 |
| Acquisizione incidenti     | In entrata    | Vengono acquisiti gli incidenti Defender (con avvisi figli)                                   |
| Estrazione osservabili     | In entrata    | IP, URL, hash di file, nomi file, hostname e account utente vengono estratti dalle prove      |
| Estrazione asset           | In entrata    | Hostname, IP e piattaforma OS del dispositivo vengono acquisiti da `devices[]`                |
| Correlazione MITRE ATT\&CK | In entrata    | Gli ID tecnica vengono aggiunti come tag e TTP (es. `mitre:T1078`)                            |
| Sincronizzazione avvisi    | In uscita     | `status`, `classification`, `determination` e commenti vengono inviati alla chiusura del caso |
| Sincronizzazione incidenti | In uscita     | `status`, `classification`, `determination` e commenti vengono inviati alla chiusura del caso |
| Test di connessione        | Bidirezionale | Convalida le credenziali OAuth2 e l'accesso all'API di sicurezza di Graph                     |

## Prerequisiti

<Steps>
  <Step title="Accesso a Microsoft Defender / Entra ID">
    Un tenant Microsoft Entra ID (Azure AD) con Microsoft Defender XDR o Microsoft Defender per
    endpoint concesso in licenza e abilitato. È necessario il permesso per registrare
    applicazioni e concedere il consenso dell'amministratore.
  </Step>

  <Step title="Uscita di rete">
    Il deployment di CaseBender deve poter raggiungere:

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

  <Step title="Ruolo di amministratore CaseBender">
    Devi poter creare e gestire integrazioni in **Impostazioni → Integrazioni**.
  </Step>
</Steps>

## Parte A — Registrare un'applicazione Azure AD

<Steps>
  <Step title="Creare la registrazione dell'app">
    Nel [centro di amministrazione Microsoft Entra](https://entra.microsoft.com), vai a
    **Identità → Applicazioni → Registrazioni app → Nuova registrazione**. Assegnale un nome
    (es. `CaseBender Defender Integration`) e registrala.
  </Step>

  <Step title="Annotare gli identificatori">
    Dalla **Panoramica** dell'applicazione, copia l'**ID applicazione (client)** e l'**ID
    directory (tenant)**. Li inserirai in CaseBender.
  </Step>

  <Step title="Creare un secret client">
    In **Certificati e segreti → Nuovo secret client**, crea un secret e copia subito il suo
    **Valore** (viene mostrato una sola volta).
  </Step>

  <Step title="Concedere le autorizzazioni dell'API di sicurezza di Graph">
    In **Autorizzazioni API → Aggiungi autorizzazione → Microsoft Graph → Autorizzazioni
    applicazione**, aggiungi quanto segue e poi fai clic su **Concedi consenso amministratore**:

    | Autorizzazione                   | Scopo                                       |
    | -------------------------------- | ------------------------------------------- |
    | `SecurityAlert.ReadWrite.All`    | Leggere e aggiornare gli avvisi Defender    |
    | `SecurityIncident.ReadWrite.All` | Leggere e aggiornare gli incidenti Defender |

    <Warning>
      Usa autorizzazioni di **Applicazione** (non delegate). L'integrazione viene eseguita senza
      interazione con il flusso di credenziali client e richiede il consenso dell'amministratore del tenant.
    </Warning>
  </Step>
</Steps>

## Parte B — Configurare l'integrazione in CaseBender

<Steps>
  <Step title="Aprire il catalogo delle integrazioni">
    Vai a **Impostazioni → Integrazioni → Crea**, quindi scegli **Microsoft Defender XDR** dalla
    categoria **EDR/XDR**.
  </Step>

  <Step title="Inserire le credenziali Azure AD">
    Fornisci i valori acquisiti nella Parte A:

    | Campo          | Descrizione              |
    | -------------- | ------------------------ |
    | `tenantId`     | ID directory (tenant)    |
    | `clientId`     | ID applicazione (client) |
    | `clientSecret` | Valore del secret client |
  </Step>

  <Step title="Configurare le opzioni di sincronizzazione">
    Abilita i comportamenti necessari:

    | Opzione                     | Effetto                                                               |
    | --------------------------- | --------------------------------------------------------------------- |
    | `syncCaseUpdates`           | Inviare gli aggiornamenti del caso a Defender                         |
    | `syncCaseClose`             | Inviare la chiusura del caso a Defender                               |
    | `autoCreateCases`           | Creare automaticamente casi dagli incidenti Defender acquisiti        |
    | `closeAlertsOnCaseClose`    | Risolvere l'**avviso** Defender collegato alla chiusura di un caso    |
    | `closeIncidentsOnCaseClose` | Risolvere l'**incidente** Defender collegato alla chiusura di un caso |
  </Step>

  <Step title="Testare la connessione">
    Usa **Testa connessione** per convalidare. CaseBender richiede un token OAuth2 e chiama
    `GET /security/alerts_v2?$top=1`.

    <Note>
      Una risposta `403` durante il test è considerata un **successo**: conferma che
      l'autenticazione ha funzionato anche quando l'app non dispone ancora dell'ambito di
      lettura su quello specifico endpoint.
    </Note>
  </Step>
</Steps>

## In entrata: Acquisizione di avvisi e incidenti Defender

### Endpoint

Defender (o un intermediario come Logic Apps, Sentinel o un forwarder di webhook) invia i
payload di avvisi/incidenti all'endpoint di acquisizione di CaseBender:

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

Le richieste vengono autenticate con una **chiave API** di integrazione nell'header
`x-api-key` (è accettato anche l'header `authorization: Bearer <chiave>`). Le chiavi API dei
webhook Defender hanno il prefisso `sk_def_`.

### Formati del payload

Sono supportati sia il formato **batch** (array `value[]` di Graph) sia un oggetto di **avviso
singolo**.

<CodeGroup>
  ```bash Batch (value[] di Graph) theme={null}
  curl -X POST "https://<il-tuo-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": "Esecuzione sospetta di 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 Avviso singolo theme={null}
  curl -X POST "https://<il-tuo-dominio-casebender>/api/v1/ingest/defender" \
    -H "x-api-key: sk_def_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "da637...",
      "title": "Malware rilevato su endpoint",
      "severity": "medium",
      "status": "new",
      "createdDateTime": "2026-07-03T18:20:00Z"
    }'
  ```
</CodeGroup>

Una richiesta riuscita restituisce HTTP `202 Accepted`:

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

### Pipeline di elaborazione

<Steps>
  <Step title="Proxy di acquisizione">
    `/api/v1/ingest/defender` convalida la sorgente e inoltra la richiesta al servizio di
    acquisizione (`POST /v1/sources/defender`).
  </Step>

  <Step title="Pubblicazione in coda">
    Il servizio di acquisizione autentica la chiave API, convalida il payload e pubblica ogni
    avviso nella coda di elaborazione.
  </Step>

  <Step title="Normalizzazione">
    Il processore Defender normalizza ogni record in un avviso CaseBender: mappa la gravità,
    costruisce titolo/descrizione, estrae osservabili e asset del dispositivo e genera i TTP MITRE.
  </Step>
</Steps>

### Riferimento di mappatura dei dati

**Mappatura della gravità** (Defender → CaseBender 1–4):

| Gravità Defender | Gravità CaseBender |
| ---------------- | ------------------ |
| `high`           | 1                  |
| `medium`         | 2                  |
| `low`            | 3                  |
| `informational`  | 4                  |
| `unknown`        | 3                  |

**Estrazione degli osservabili** (da `evidence[]`):

| Campo prova     | Tipo di osservabile        |
| --------------- | -------------------------- |
| `ipAddress`     | `ip`                       |
| `url`           | `url`                      |
| `sha256`        | `hash`                     |
| `fileName`      | `filename`                 |
| `deviceDnsName` | `hostname`                 |
| `userAccount`   | `user` (`DOMINIO\account`) |

I tag applicati all'acquisizione includono `defender`, `xdr`, `service:<serviceSource>`,
`category:<category>`, `incident` (per gli incidenti) e un tag `mitre:<technique>` per ogni
tecnica MITRE. I record acquisiti usano per impostazione predefinita **TLP:2** e **PAP:2**.

## In uscita: Sincronizzare le disposizioni dei casi con Defender

Quando un caso viene chiuso in CaseBender, l'evento `case_closed` viene inviato al gestore
Defender. Se il caso è collegato a un avviso o incidente Defender, CaseBender invia la
risoluzione tramite l'API di sicurezza di Graph.

### Come viene risolta l'entità Defender collegata

Il gestore cerca gli identificatori Defender in questo ordine:

1. `extraData.defenderAlertId` / `extraData.defenderIncidentId`
2. `sourceRef` quando `extraData.source === "defender"`
3. `sourceRef` quando sembra un riferimento di avviso Defender (prefisso `da`)

Se non viene trovato alcun ID di avviso o incidente, la chiusura del caso viene ignorata per questa integrazione.

### Mappatura risoluzione → classificazione

| Risoluzione CaseBender | Classificazione Defender        |
| ---------------------- | ------------------------------- |
| `TruePositive`         | `truePositive`                  |
| `FalsePositive`        | `falsePositive`                 |
| `Duplicate`            | `informationalExpectedActivity` |
| `NoImpact`             | `informationalExpectedActivity` |
| *(altra / nessuna)*    | `truePositive` (predefinito)    |

Alla chiusura, CaseBender imposta lo `status` dell'avviso/incidente su `resolved`, applica la
`classification` mappata e aggiunge un commento come:

```
Case <id-caso> closed in CaseBender with resolution: <risoluzione>
```

<Note>
  Gli aggiornamenti in uscita degli avvisi richiedono che `closeAlertsOnCaseClose` sia
  abilitato; quelli degli incidenti richiedono `closeIncidentsOnCaseClose`. Se nessuno dei due
  è abilitato, non avviene alcuna sincronizzazione in uscita.
</Note>

## Considerazioni sulla sicurezza

* **Gestione dei segreti** — il secret client è memorizzato nelle impostazioni
  dell'integrazione; ruotalo secondo le esigenze della tua organizzazione e aggiorna l'integrazione.
* **Privilegio minimo** — concedi solo `SecurityAlert.ReadWrite.All` e
  `SecurityIncident.ReadWrite.All`. Non aggiungere ambiti Graph più ampi.
* **Caching dei token** — i token di accesso sono memorizzati in cache in memoria per
  integrazione e aggiornati un minuto prima della scadenza; nessun token viene persistito su disco.
* **Chiavi webhook** — tratta la chiave API `sk_def_` come un segreto. Ruotala se esposta e
  aggiorna la configurazione del mittente.
* **Rete** — limita l'uscita a `login.microsoftonline.com` e `graph.microsoft.com`.

## Risoluzione dei problemi

<AccordionGroup>
  <Accordion title="Il test di connessione fallisce con un errore OAuth2">
    Verifica `tenantId`, `clientId` e `clientSecret`. Conferma che il secret client non sia
    scaduto e che sia stato concesso il consenso dell'amministratore per le autorizzazioni dell'applicazione Graph.
  </Accordion>

  <Accordion title="L'acquisizione restituisce 401 Unauthorized">
    L'header `x-api-key` è mancante o non valido. Conferma di inviare la chiave `sk_def_` che
    corrisponde alla chiave API webhook configurata dell'integrazione.
  </Accordion>

  <Accordion title="L'acquisizione restituisce 400 'No alerts in payload'">
    Il payload non conteneva né un array `value[]` né un `id` di primo livello. Invia un oggetto
    batch di Graph o un oggetto di avviso singolo.
  </Accordion>

  <Accordion title="La chiusura del caso non aggiorna Defender">
    Assicurati che `closeAlertsOnCaseClose` / `closeIncidentsOnCaseClose` sia abilitato e che il
    caso abbia un ID avviso/incidente Defender (tramite `extraData` o `sourceRef`).
  </Accordion>

  <Accordion title="L'aggiornamento in uscita restituisce 403">
    All'app Azure AD manca l'autorizzazione di scrittura. Conferma che
    `SecurityAlert.ReadWrite.All` e `SecurityIncident.ReadWrite.All` siano concessi con il
    consenso dell'amministratore.
  </Accordion>
</AccordionGroup>

## Documentazione correlata

* [Panoramica delle integrazioni](./introduction.mdx)
* [API di sicurezza di Microsoft Graph](https://learn.microsoft.com/it-it/graph/api/resources/security-api-overview)
* [Microsoft Defender XDR](https://learn.microsoft.com/it-it/defender-xdr/)