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

> Intégration bidirectionnelle entre CaseBender et Microsoft Defender XDR (Windows Defender) pour l'ingestion d'alertes/incidents et la synchronisation des dispositions.

## Vue d'ensemble

L'intégration Microsoft Defender XDR (**INT-021**) assure une synchronisation
**bidirectionnelle** entre CaseBender et la plateforme de détection et de réponse étendues de
Microsoft, y compris **Microsoft Defender pour point de terminaison (MDE)** et **Microsoft
Defender XDR**.

<CardGroup cols={2}>
  <Card title="Ingestion entrante" icon="arrow-right-to-bracket">
    Les alertes et incidents Defender sont ingérés dans CaseBender, normalisés, enrichis
    d'observables et de techniques MITRE ATT\&CK, puis transformés en alertes/dossiers.
  </Card>

  <Card title="Synchronisation sortante" icon="arrow-right-from-bracket">
    Lorsqu'un dossier CaseBender est clôturé, l'alerte/incident Defender lié est mis à jour avec
    le statut, la classification et un commentaire d'audit via Microsoft Graph.
  </Card>
</CardGroup>

<Note>
  Cette intégration utilise l'**API de sécurité Microsoft Graph**
  (`https://graph.microsoft.com/v1.0/security`). Elle s'authentifie avec une **application
  Azure AD (Entra ID)** via le flux d'identifiants client OAuth2.
</Note>

## Fonctionnalités

| Fonctionnalité              | Direction      | Description                                                                                                    |
| --------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------- |
| Ingestion d'alertes         | Entrant        | Les alertes Defender sont normalisées en alertes CaseBender                                                    |
| Ingestion d'incidents       | Entrant        | Les incidents Defender (avec alertes enfants) sont ingérés                                                     |
| Extraction d'observables    | Entrant        | IP, URL, empreintes de fichiers, noms de fichiers, hostnames et comptes utilisateurs sont extraits des preuves |
| Extraction d'actifs         | Entrant        | Hostname, IP et plateforme OS de l'appareil sont capturés depuis `devices[]`                                   |
| Corrélation MITRE ATT\&CK   | Entrant        | Les identifiants de technique sont ajoutés comme étiquettes et TTP (p. ex. `mitre:T1078`)                      |
| Synchronisation d'alertes   | Sortant        | `status`, `classification`, `determination` et commentaires sont envoyés à la clôture du dossier               |
| Synchronisation d'incidents | Sortant        | `status`, `classification`, `determination` et commentaires sont envoyés à la clôture du dossier               |
| Test de connexion           | Bidirectionnel | Valide les identifiants OAuth2 et l'accès à l'API de sécurité Graph                                            |

## Prérequis

<Steps>
  <Step title="Accès à Microsoft Defender / Entra ID">
    Un locataire Microsoft Entra ID (Azure AD) avec Microsoft Defender XDR ou Microsoft Defender
    pour point de terminaison sous licence et activé. Vous devez pouvoir enregistrer des
    applications et accorder le consentement administrateur.
  </Step>

  <Step title="Sortie réseau">
    Le déploiement CaseBender doit pouvoir atteindre :

    * `https://login.microsoftonline.com` (endpoint de jeton OAuth2)
    * `https://graph.microsoft.com` (API de sécurité Graph)
  </Step>

  <Step title="Rôle administrateur CaseBender">
    Vous devez pouvoir créer et gérer des intégrations dans **Paramètres → Intégrations**.
  </Step>
</Steps>

## Partie A — Enregistrer une application Azure AD

<Steps>
  <Step title="Créer l'enregistrement d'application">
    Dans le [centre d'administration Microsoft Entra](https://entra.microsoft.com), allez à
    **Identité → Applications → Inscriptions d'applications → Nouvelle inscription**. Donnez-lui
    un nom (p. ex. `CaseBender Defender Integration`) et enregistrez-la.
  </Step>

  <Step title="Noter les identifiants">
    Depuis la **Vue d'ensemble** de l'application, copiez l'**ID d'application (client)** et
    l'**ID de répertoire (locataire)**. Vous les saisirez dans CaseBender.
  </Step>

  <Step title="Créer un secret client">
    Sous **Certificats et secrets → Nouveau secret client**, créez un secret et copiez sa
    **Valeur** immédiatement (elle n'est affichée qu'une fois).
  </Step>

  <Step title="Accorder les autorisations de l'API de sécurité Graph">
    Sous **Autorisations d'API → Ajouter une autorisation → Microsoft Graph → Autorisations
    d'application**, ajoutez les éléments suivants puis cliquez sur **Accorder le consentement administrateur** :

    | Autorisation                     | Objectif                                     |
    | -------------------------------- | -------------------------------------------- |
    | `SecurityAlert.ReadWrite.All`    | Lire et mettre à jour les alertes Defender   |
    | `SecurityIncident.ReadWrite.All` | Lire et mettre à jour les incidents Defender |

    <Warning>
      Utilisez des autorisations d'**Application** (et non déléguées). L'intégration s'exécute
      sans interface avec le flux d'identifiants client et nécessite le consentement de
      l'administrateur du locataire.
    </Warning>
  </Step>
</Steps>

## Partie B — Configurer l'intégration dans CaseBender

<Steps>
  <Step title="Ouvrir le catalogue d'intégrations">
    Allez à **Paramètres → Intégrations → Créer**, puis choisissez **Microsoft Defender XDR**
    dans la catégorie **EDR/XDR**.
  </Step>

  <Step title="Saisir les identifiants Azure AD">
    Fournissez les valeurs obtenues dans la Partie A :

    | Champ          | Description                  |
    | -------------- | ---------------------------- |
    | `tenantId`     | ID de répertoire (locataire) |
    | `clientId`     | ID d'application (client)    |
    | `clientSecret` | Valeur du secret client      |
  </Step>

  <Step title="Configurer les options de synchronisation">
    Activez les comportements nécessaires :

    | Option                      | Effet                                                                      |
    | --------------------------- | -------------------------------------------------------------------------- |
    | `syncCaseUpdates`           | Envoyer les mises à jour du dossier vers Defender                          |
    | `syncCaseClose`             | Envoyer la clôture du dossier vers Defender                                |
    | `autoCreateCases`           | Créer automatiquement des dossiers à partir des incidents Defender ingérés |
    | `closeAlertsOnCaseClose`    | Résoudre l'**alerte** Defender liée à la clôture d'un dossier              |
    | `closeIncidentsOnCaseClose` | Résoudre l'**incident** Defender lié à la clôture d'un dossier             |
  </Step>

  <Step title="Tester la connexion">
    Utilisez **Tester la connexion** pour valider. CaseBender demande un jeton OAuth2 et appelle
    `GET /security/alerts_v2?$top=1`.

    <Note>
      Une réponse `403` pendant le test est considérée comme un **succès** : elle confirme que
      l'authentification a fonctionné même lorsque l'application n'a pas encore obtenu la portée
      de lecture sur cet endpoint précis.
    </Note>
  </Step>
</Steps>

## Entrant : Ingestion des alertes et incidents Defender

### Endpoint

Defender (ou un intermédiaire tel que Logic Apps, Sentinel ou un relais de webhooks) envoie les
charges utiles d'alertes/incidents à l'endpoint d'ingestion CaseBender :

```
POST https://<votre-domaine-casebender>/api/v1/ingest/defender
```

Les requêtes sont authentifiées avec une **clé d'API** d'intégration dans l'en-tête
`x-api-key` (l'en-tête `authorization: Bearer <clé>` est également accepté). Les clés d'API de
webhook Defender ont le préfixe `sk_def_`.

### Formats de charge utile

Le format **par lots** (tableau `value[]` de Graph) et l'objet d'**alerte unique** sont tous
deux pris en charge.

<CodeGroup>
  ```bash Lot (value[] de Graph) theme={null}
  curl -X POST "https://<votre-domaine-casebender>/api/v1/ingest/defender" \
    -H "x-api-key: sk_def_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "value": [
        {
          "id": "da637...",
          "incidentId": "12345",
          "title": "Exécution PowerShell suspecte",
          "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 Alerte unique theme={null}
  curl -X POST "https://<votre-domaine-casebender>/api/v1/ingest/defender" \
    -H "x-api-key: sk_def_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "da637...",
      "title": "Logiciel malveillant détecté sur le point de terminaison",
      "severity": "medium",
      "status": "new",
      "createdDateTime": "2026-07-03T18:20:00Z"
    }'
  ```
</CodeGroup>

Une requête réussie renvoie HTTP `202 Accepted` :

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

### Pipeline de traitement

<Steps>
  <Step title="Proxy d'ingestion">
    `/api/v1/ingest/defender` valide la source et transmet la requête au service d'ingestion
    (`POST /v1/sources/defender`).
  </Step>

  <Step title="Publication en file d'attente">
    Le service d'ingestion authentifie la clé d'API, valide la charge utile et publie chaque
    alerte dans la file de traitement.
  </Step>

  <Step title="Normalisation">
    Le processeur Defender normalise chaque enregistrement en une alerte CaseBender : mappage de
    la gravité, construction du titre/description, extraction des observables et actifs
    d'appareil, et génération des TTP MITRE.
  </Step>
</Steps>

### Référence de mappage des données

**Mappage de la gravité** (Defender → CaseBender 1–4) :

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

**Extraction des observables** (depuis `evidence[]`) :

| Champ de preuve | Type d'observable         |
| --------------- | ------------------------- |
| `ipAddress`     | `ip`                      |
| `url`           | `url`                     |
| `sha256`        | `hash`                    |
| `fileName`      | `filename`                |
| `deviceDnsName` | `hostname`                |
| `userAccount`   | `user` (`DOMAINE\compte`) |

Les étiquettes appliquées à l'ingestion incluent `defender`, `xdr`, `service:<serviceSource>`,
`category:<category>`, `incident` (pour les incidents) et une étiquette `mitre:<technique>` par
technique MITRE. Les enregistrements ingérés utilisent par défaut **TLP:2** et **PAP:2**.

## Sortant : Synchroniser les dispositions de dossiers vers Defender

Lorsqu'un dossier est clôturé dans CaseBender, l'événement `case_closed` est envoyé au
gestionnaire Defender. Si le dossier est lié à une alerte ou un incident Defender, CaseBender
renvoie la résolution via l'API de sécurité Graph.

### Comment l'entité Defender liée est résolue

Le gestionnaire recherche les identifiants Defender dans cet ordre :

1. `extraData.defenderAlertId` / `extraData.defenderIncidentId`
2. `sourceRef` lorsque `extraData.source === "defender"`
3. `sourceRef` lorsqu'il ressemble à une référence d'alerte Defender (préfixe `da`)

Si aucun ID d'alerte ou d'incident n'est trouvé, la clôture du dossier est ignorée pour cette intégration.

### Mappage résolution → classification

| Résolution CaseBender | Classification Defender         |
| --------------------- | ------------------------------- |
| `TruePositive`        | `truePositive`                  |
| `FalsePositive`       | `falsePositive`                 |
| `Duplicate`           | `informationalExpectedActivity` |
| `NoImpact`            | `informationalExpectedActivity` |
| *(autre / aucune)*    | `truePositive` (par défaut)     |

À la clôture, CaseBender définit le `status` de l'alerte/incident sur `resolved`, applique la
`classification` mappée et ajoute un commentaire tel que :

```
Case <id-dossier> closed in CaseBender with resolution: <résolution>
```

<Note>
  Les mises à jour sortantes d'alertes nécessitent l'activation de `closeAlertsOnCaseClose` ;
  celles d'incidents nécessitent `closeIncidentsOnCaseClose`. Si aucune n'est activée, aucune
  synchronisation sortante n'a lieu.
</Note>

## Considérations de sécurité

* **Gestion des secrets** — le secret client est stocké dans les paramètres de l'intégration ;
  faites-le pivoter selon les exigences de votre organisation et mettez à jour l'intégration.
* **Moindre privilège** — accordez uniquement `SecurityAlert.ReadWrite.All` et
  `SecurityIncident.ReadWrite.All`. N'ajoutez pas d'autres portées Graph.
* **Mise en cache des jetons** — les jetons d'accès sont mis en cache en mémoire par intégration
  et actualisés une minute avant expiration ; aucun jeton n'est persisté sur disque.
* **Clés de webhook** — traitez la clé d'API `sk_def_` comme un secret. Faites-la pivoter en cas
  d'exposition et mettez à jour la configuration de l'expéditeur.
* **Réseau** — limitez la sortie à `login.microsoftonline.com` et `graph.microsoft.com`.

## Dépannage

<AccordionGroup>
  <Accordion title="Le test de connexion échoue avec une erreur OAuth2">
    Vérifiez `tenantId`, `clientId` et `clientSecret`. Confirmez que le secret client n'a pas
    expiré et que le consentement administrateur a été accordé pour les autorisations d'application Graph.
  </Accordion>

  <Accordion title="L'ingestion renvoie 401 Unauthorized">
    L'en-tête `x-api-key` est manquant ou invalide. Confirmez que vous envoyez la clé `sk_def_`
    qui correspond à la clé d'API de webhook configurée de l'intégration.
  </Accordion>

  <Accordion title="L'ingestion renvoie 400 'No alerts in payload'">
    La charge utile ne contenait ni tableau `value[]` ni `id` de premier niveau. Envoyez un
    objet par lots Graph ou un objet d'alerte unique.
  </Accordion>

  <Accordion title="La clôture du dossier ne met pas à jour Defender">
    Assurez-vous que `closeAlertsOnCaseClose` / `closeIncidentsOnCaseClose` est activé et que le
    dossier porte un ID d'alerte/incident Defender (via `extraData` ou `sourceRef`).
  </Accordion>

  <Accordion title="La mise à jour sortante renvoie 403">
    L'application Azure AD n'a pas d'autorisation d'écriture. Confirmez que
    `SecurityAlert.ReadWrite.All` et `SecurityIncident.ReadWrite.All` sont accordés avec le
    consentement administrateur.
  </Accordion>
</AccordionGroup>

## Documentation associée

* [Vue d'ensemble des intégrations](./introduction.mdx)
* [API de sécurité Microsoft Graph](https://learn.microsoft.com/fr-fr/graph/api/resources/security-api-overview)
* [Microsoft Defender XDR](https://learn.microsoft.com/fr-fr/defender-xdr/)