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

# AWS GuardDuty

> Ingérez les findings AWS GuardDuty dans CaseBender par interrogation automatique (pull) ou webhook EventBridge (push).

## Présentation

L'intégration AWS GuardDuty (**INT-023**) ingère les findings GuardDuty dans CaseBender, les
enrichit d'un mappage MITRE ATT\&CK et d'une catégorisation d'attaque, et les convertit en alertes
(et éventuellement en cas).

<CardGroup cols={2}>
  <Card title="Interrogation automatique (pull)" icon="arrow-right-to-bracket">
    CaseBender extrait de nouveaux findings directement de votre compte AWS de
    façon planifiée à l'aide d'identifiants IAM — sans règle EventBridge.
  </Card>

  <Card title="Webhook EventBridge (push)" icon="bolt">
    En alternative, une règle EventBridge transfère les findings vers l'endpoint
    d'ingestion de CaseBender.
  </Card>
</CardGroup>

<Tip>
  **Recommandé : activez l'interrogation automatique.** Elle ne nécessite qu'une
  clé IAM en lecture seule et aucun endpoint entrant. Voir
  [Interrogation automatique](#entrant-interrogation-automatique).
</Tip>

<Note>
  L'interrogation utilise le **SDK AWS officiel** contre l'API GuardDuty
  (`ListDetectors`, `ListFindings`, `GetFindings`).
</Note>

## Fonctionnalités

| Fonctionnalité                        | Sens    | Description                                                                             |
| ------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| **Interrogation des findings (pull)** | Entrant | CaseBender interroge l'API GuardDuty de façon planifiée et ingère les nouveaux findings |
| Ingestion des findings (push)         | Entrant | EventBridge transfère les findings vers l'endpoint d'ingestion                          |
| Extraction d'observables              | Entrant | IP, domaines, clés d'accès, buckets S3, IP d'instances                                  |
| Corrélation MITRE ATT\&CK             | Entrant | Les types de findings sont mappés aux tactiques/techniques                              |
| Catégorisation d'attaque              | Entrant | Les findings sont catégorisés et reçoivent des conseils de remédiation                  |

## Prérequis

<Steps>
  <Step title="Activer GuardDuty">
    GuardDuty doit être activé dans la ou les régions AWS que vous souhaitez surveiller.
  </Step>

  <Step title="Créer un utilisateur IAM / une clé d'accès">
    Créez un principal IAM avec une politique autorisant `guardduty:ListDetectors`,
    `guardduty:ListFindings` et `guardduty:GetFindings`. Générez un access key ID + secret.
  </Step>

  <Step title="Sortie réseau">
    L'interrogateur de CaseBender doit atteindre l'endpoint de l'API GuardDuty de votre région
    (`guardduty.<region>.amazonaws.com`).
  </Step>
</Steps>

## Configurer l'intégration dans CaseBender

<Steps>
  <Step title="Ouvrir le catalogue d'intégrations">
    Allez dans **Settings → Integrations → Create**, puis choisissez **AWS GuardDuty** dans la
    catégorie **Cloud Security**.
  </Step>

  <Step title="Saisir les identifiants AWS">
    | Champ                         | Description                                                                      |
    | ----------------------------- | -------------------------------------------------------------------------------- |
    | AWS Access Key ID             | Access key ID IAM                                                                |
    | AWS Secret Access Key         | Secret access key IAM                                                            |
    | AWS Region                    | Région où GuardDuty est activé (p. ex. `us-east-1`)                              |
    | Detector ID (facultatif)      | Découvert automatiquement à partir de la région si vide                          |
    | Minimum severity (facultatif) | Sévérité GuardDuty 1–8.9 ; seuls les findings à partir de ce seuil sont extraits |
  </Step>

  <Step title="Activer l'interrogation automatique (recommandé)">
    | Option                        | Effet                                                                                    |
    | ----------------------------- | ---------------------------------------------------------------------------------------- |
    | `pollingEnabled`              | Active l'extraction planifiée des findings                                               |
    | `pollingIntervalMinutes`      | Fréquence d'interrogation (par défaut `5`)                                               |
    | `pollingInitialLookbackHours` | Au premier passage, importe les findings mis à jour dans cette fenêtre (par défaut `24`) |
    | `pollMaxItemsPerRun`          | Limite de sécurité d'éléments par passage (par défaut `500`)                             |
  </Step>

  <Step title="Configurer la création automatique de cas">
    | Option               | Effet                                                            |
    | -------------------- | ---------------------------------------------------------------- |
    | `autoCreateCases`    | Promeut chaque finding en **Cas** (dédupliqué par ID de finding) |
    | `minSeverityForCase` | Ne crée automatiquement des cas qu'à partir de cette sévérité    |
  </Step>
</Steps>

## Entrant (interrogation automatique)

<Steps>
  <Step title="Extraction planifiée">
    À chaque intervalle, CaseBender énumère les ID de findings mis à jour depuis le dernier
    curseur (éventuellement filtrés par sévérité minimale), puis récupère les findings complets. Au
    premier passage, les findings mis à jour dans `pollingInitialLookbackHours` sont importés.
  </Step>

  <Step title="Curseur + déduplication">
    CaseBender avance le curseur jusqu'au `updatedAt` le plus récent. Les findings sont
    **dédupliqués par ID de finding**, de sorte que les fenêtres qui se chevauchent ne créent
    jamais de doublons.
  </Step>

  <Step title="Normalisation">
    Chaque finding est normalisé en alerte CaseBender avec observables, tactiques MITRE, catégorie
    d'attaque et conseils de remédiation.
  </Step>
</Steps>

<Info>
  L'interrogation s'exécute dans le service d'interrogation en arrière-plan de CaseBender. Pour une
  couverture multi-région, créez une intégration GuardDuty par région.
</Info>

## Entrant (webhook EventBridge / push)

En alternative, une règle EventBridge (avec une destination d'API) peut faire un POST des findings
vers :

```
POST https://<your-casebender-domain>/api/v1/ingest/guardduty
```

Les requêtes sont authentifiées avec l'**API key** d'intégration dans l'en-tête `x-api-key`. Le
finding brut et l'enveloppe EventBridge `{ "detail": { ... } }` sont tous deux acceptés.

## Considérations de sécurité

* **Moindre privilège** — n'accordez que les trois actions GuardDuty en lecture seule
  ci-dessus.
* **Gestion des secrets** — faites tourner la clé d'accès IAM selon la politique de votre
  organisation ; préférez des clés attribuées à un utilisateur d'intégration dédié.
* **Réseau** — restreignez la sortie à l'endpoint régional GuardDuty.

## Dépannage

<AccordionGroup>
  <Accordion title="Aucun détecteur trouvé">
    Confirmez que GuardDuty est activé dans la région configurée, ou définissez explicitement le
    Detector ID.
  </Accordion>

  <Accordion title="L'interrogation est activée mais aucun finding n'apparaît">
    Vérifiez que la clé IAM dispose de `ListDetectors`, `ListFindings` et `GetFindings`. Contrôlez
    la région et l'existence de findings plus récents que le curseur. Au premier passage, seuls les
    findings dans `pollingInitialLookbackHours` sont importés.

    **Assurez-vous que tous les services CaseBender fonctionnent** — avec Docker,
    `docker compose ps` doit afficher les services `worker` et `misp-processor` en `Up`.
  </Accordion>

  <Accordion title="Erreurs AccessDenied">
    Il manque à la politique IAM l'une des actions requises, ou la clé appartient à un compte/une
    région différent de celui attendu.
  </Accordion>
</AccordionGroup>

## Documentation connexe

* [Présentation des intégrations](./introduction.mdx)
* [Documentation AWS GuardDuty](https://docs.aws.amazon.com/guardduty/)