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

> Acquisisci i finding di AWS GuardDuty in CaseBender tramite polling automatico (pull) o webhook EventBridge (push).

## Panoramica

L'integrazione di AWS GuardDuty (**INT-023**) acquisisce i finding di GuardDuty in CaseBender, li
arricchisce con mappatura MITRE ATT\&CK e categorizzazione degli attacchi, e li trasforma in avvisi
(ed eventualmente casi).

<CardGroup cols={2}>
  <Card title="Polling automatico (pull)" icon="arrow-right-to-bracket">
    CaseBender estrae nuovi finding direttamente dal tuo account AWS in modo
    pianificato utilizzando credenziali IAM — senza regola EventBridge.
  </Card>

  <Card title="Webhook EventBridge (push)" icon="bolt">
    In alternativa, una regola EventBridge inoltra i finding all'endpoint di
    acquisizione di CaseBender.
  </Card>
</CardGroup>

<Tip>
  **Consigliato: abilita il polling automatico.** Richiede solo una chiave IAM in
  sola lettura e nessun endpoint in entrata. Vedi
  [Polling automatico](#entrata-polling-automatico).
</Tip>

<Note>
  Il polling utilizza l'**SDK AWS ufficiale** verso l'API di GuardDuty
  (`ListDetectors`, `ListFindings`, `GetFindings`).
</Note>

## Funzionalità

| Funzionalità                    | Direzione | Descrizione                                                                              |
| ------------------------------- | --------- | ---------------------------------------------------------------------------------------- |
| **Polling dei finding (pull)**  | Entrata   | CaseBender interroga l'API di GuardDuty in modo pianificato e acquisisce i nuovi finding |
| Acquisizione dei finding (push) | Entrata   | EventBridge inoltra i finding all'endpoint di acquisizione                               |
| Estrazione di osservabili       | Entrata   | IP, domini, chiavi di accesso, bucket S3, IP delle istanze                               |
| Correlazione MITRE ATT\&CK      | Entrata   | I tipi di finding vengono mappati a tattiche/tecniche                                    |
| Categorizzazione degli attacchi | Entrata   | I finding vengono categorizzati e ricevono indicazioni di remediation                    |

## Prerequisiti

<Steps>
  <Step title="Abilita GuardDuty">
    GuardDuty deve essere abilitato nelle regioni AWS che desideri monitorare.
  </Step>

  <Step title="Crea un utente IAM / chiave di accesso">
    Crea un principale IAM con una policy che consenta `guardduty:ListDetectors`,
    `guardduty:ListFindings` e `guardduty:GetFindings`. Genera un access key ID + secret.
  </Step>

  <Step title="Uscita di rete">
    Il poller di CaseBender deve raggiungere l'endpoint dell'API di GuardDuty della tua regione
    (`guardduty.<region>.amazonaws.com`).
  </Step>
</Steps>

## Configurare l'integrazione in CaseBender

<Steps>
  <Step title="Apri il catalogo delle integrazioni">
    Vai su **Settings → Integrations → Create** e scegli **AWS GuardDuty** nella categoria
    **Cloud Security**.
  </Step>

  <Step title="Inserisci le credenziali AWS">
    | Campo                          | Descrizione                                                                         |
    | ------------------------------ | ----------------------------------------------------------------------------------- |
    | AWS Access Key ID              | Access key ID IAM                                                                   |
    | AWS Secret Access Key          | Secret access key IAM                                                               |
    | AWS Region                     | Regione in cui GuardDuty è abilitato (es. `us-east-1`)                              |
    | Detector ID (facoltativo)      | Rilevato automaticamente dalla regione se vuoto                                     |
    | Minimum severity (facoltativo) | Gravità GuardDuty 1–8.9; vengono estratti solo i finding a partire da questo valore |
  </Step>

  <Step title="Abilita il polling automatico (consigliato)">
    | Opzione                       | Effetto                                                                                   |
    | ----------------------------- | ----------------------------------------------------------------------------------------- |
    | `pollingEnabled`              | Attiva l'estrazione pianificata dei finding                                               |
    | `pollingIntervalMinutes`      | Frequenza di polling (predefinito `5`)                                                    |
    | `pollingInitialLookbackHours` | Alla prima esecuzione, importa i finding aggiornati in questa finestra (predefinito `24`) |
    | `pollMaxItemsPerRun`          | Limite di sicurezza di elementi per esecuzione (predefinito `500`)                        |
  </Step>

  <Step title="Configura la creazione automatica dei casi">
    | Opzione              | Effetto                                                       |
    | -------------------- | ------------------------------------------------------------- |
    | `autoCreateCases`    | Promuove ogni finding a **Caso** (deduplicato per ID finding) |
    | `minSeverityForCase` | Crea automaticamente casi solo a partire da questa gravità    |
  </Step>
</Steps>

## Entrata (polling automatico)

<Steps>
  <Step title="Estrazione pianificata">
    A ogni intervallo, CaseBender enumera gli ID dei finding aggiornati dall'ultimo cursore
    (eventualmente filtrati per gravità minima), quindi recupera i finding completi. Alla prima
    esecuzione vengono importati i finding aggiornati entro `pollingInitialLookbackHours`.
  </Step>

  <Step title="Cursore + deduplicazione">
    CaseBender avanza il cursore fino all'`updatedAt` più recente. I finding vengono **deduplicati
    per ID finding**, quindi finestre sovrapposte non creano mai duplicati.
  </Step>

  <Step title="Normalizzazione">
    Ogni finding viene normalizzato in un avviso di CaseBender con osservabili, tattiche MITRE,
    categoria di attacco e indicazioni di remediation.
  </Step>
</Steps>

<Info>
  Il polling viene eseguito nel servizio di polling in background di CaseBender. Per la copertura
  multi-regione, crea un'integrazione GuardDuty per regione.
</Info>

## Entrata (webhook EventBridge / push)

In alternativa, una regola EventBridge (con una destinazione API) può eseguire un POST dei finding
verso:

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

Le richieste sono autenticate con l'**API key** di integrazione nell'intestazione `x-api-key`.
Sono accettati sia il finding grezzo sia il wrapper EventBridge `{ "detail": { ... } }`.

## Considerazioni sulla sicurezza

* **Privilegio minimo** — concedi solo le tre azioni GuardDuty in sola lettura elencate sopra.
* **Gestione dei segreti** — ruota la chiave di accesso IAM secondo la policy della tua
  organizzazione; preferisci chiavi assegnate a un utente di integrazione dedicato.
* **Rete** — limita l'uscita all'endpoint regionale di GuardDuty.

## Risoluzione dei problemi

<AccordionGroup>
  <Accordion title="Nessun detector trovato">
    Conferma che GuardDuty sia abilitato nella regione configurata, oppure imposta esplicitamente
    il Detector ID.
  </Accordion>

  <Accordion title="Il polling è abilitato ma non appaiono finding">
    Verifica che la chiave IAM disponga di `ListDetectors`, `ListFindings` e `GetFindings`.
    Controlla la regione e la presenza di finding più recenti del cursore. Alla prima esecuzione
    vengono importati solo i finding entro `pollingInitialLookbackHours`.

    **Assicurati che tutti i servizi di CaseBender siano in esecuzione** — con Docker,
    `docker compose ps` deve mostrare i servizi `worker` e `misp-processor` come `Up`.
  </Accordion>

  <Accordion title="Errori AccessDenied">
    Alla policy IAM manca una delle azioni richieste, oppure la chiave appartiene a un account/una
    regione diversa da quella prevista.
  </Accordion>
</AccordionGroup>

## Documentazione correlata

* [Panoramica delle integrazioni](./introduction.mdx)
* [Documentazione di AWS GuardDuty](https://docs.aws.amazon.com/guardduty/)