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

> Ingiera los hallazgos de AWS GuardDuty en CaseBender mediante sondeo automático (pull) o webhook de EventBridge (push).

## Descripción general

La integración de AWS GuardDuty (**INT-023**) ingiere los hallazgos de GuardDuty en CaseBender,
los enriquece con mapeo MITRE ATT\&CK y categorización de ataques, y los convierte en alertas (y
opcionalmente casos).

<CardGroup cols={2}>
  <Card title="Sondeo automático (pull)" icon="arrow-right-to-bracket">
    CaseBender extrae nuevos hallazgos directamente de su cuenta de AWS de forma
    programada usando credenciales IAM — sin regla de EventBridge.
  </Card>

  <Card title="Webhook de EventBridge (push)" icon="bolt">
    Como alternativa, una regla de EventBridge reenvía los hallazgos al endpoint
    de ingesta de CaseBender.
  </Card>
</CardGroup>

<Tip>
  **Recomendado: active el sondeo automático.** Solo requiere una clave IAM de
  solo lectura y ningún endpoint entrante. Véase
  [Sondeo automático](#entrada-sondeo-automatico-recomendado).
</Tip>

<Note>
  El sondeo usa el **SDK oficial de AWS** contra la API de GuardDuty
  (`ListDetectors`, `ListFindings`, `GetFindings`).
</Note>

## Capacidades

| Capacidad                      | Dirección | Descripción                                                                            |
| ------------------------------ | --------- | -------------------------------------------------------------------------------------- |
| **Sondeo de hallazgos (pull)** | Entrante  | CaseBender consulta la API de GuardDuty de forma programada e ingiere nuevos hallazgos |
| Ingesta de hallazgos (push)    | Entrante  | EventBridge reenvía los hallazgos al endpoint de ingesta                               |
| Extracción de observables      | Entrante  | IP, dominios, claves de acceso, buckets S3, IP de instancias                           |
| Correlación MITRE ATT\&CK      | Entrante  | Los tipos de hallazgo se mapean a tácticas/técnicas                                    |
| Categorización de ataques      | Entrante  | Los hallazgos se categorizan y reciben orientación de remediación                      |

## Requisitos previos

<Steps>
  <Step title="Habilitar GuardDuty">
    GuardDuty debe estar habilitado en las regiones de AWS que desea supervisar.
  </Step>

  <Step title="Crear un usuario IAM / clave de acceso">
    Cree un principal IAM con una política que permita `guardduty:ListDetectors`,
    `guardduty:ListFindings` y `guardduty:GetFindings`. Genere un access key ID + secret.
  </Step>

  <Step title="Salida de red">
    El sondeador de CaseBender debe alcanzar el endpoint de la API de GuardDuty de su región
    (`guardduty.<region>.amazonaws.com`).
  </Step>
</Steps>

## Configurar la integración en CaseBender

<Steps>
  <Step title="Abrir el catálogo de integraciones">
    Vaya a **Settings → Integrations → Create** y elija **AWS GuardDuty** en la categoría
    **Cloud Security**.
  </Step>

  <Step title="Introducir las credenciales de AWS">
    | Campo                       | Descripción                                                                    |
    | --------------------------- | ------------------------------------------------------------------------------ |
    | AWS Access Key ID           | Access key ID de IAM                                                           |
    | AWS Secret Access Key       | Secret access key de IAM                                                       |
    | AWS Region                  | Región donde GuardDuty está habilitado (p. ej. `us-east-1`)                    |
    | Detector ID (opcional)      | Se descubre automáticamente de la región si está en blanco                     |
    | Minimum severity (opcional) | Severidad de GuardDuty 1–8.9; solo se extraen hallazgos a partir de este valor |
  </Step>

  <Step title="Activar el sondeo automático (recomendado)">
    | Opción                        | Efecto                                                                                            |
    | ----------------------------- | ------------------------------------------------------------------------------------------------- |
    | `pollingEnabled`              | Activa la extracción programada de hallazgos                                                      |
    | `pollingIntervalMinutes`      | Frecuencia de sondeo (por defecto `5`)                                                            |
    | `pollingInitialLookbackHours` | En la primera ejecución, importa hallazgos actualizados dentro de esta ventana (por defecto `24`) |
    | `pollMaxItemsPerRun`          | Límite de seguridad de elementos por ejecución (por defecto `500`)                                |
  </Step>

  <Step title="Configurar la creación automática de casos">
    | Opción               | Efecto                                                                |
    | -------------------- | --------------------------------------------------------------------- |
    | `autoCreateCases`    | Promueve cada hallazgo a un **Caso** (deduplicado por ID de hallazgo) |
    | `minSeverityForCase` | Solo crea casos automáticamente a partir de esta severidad            |
  </Step>
</Steps>

## Entrada (sondeo automático, recomendado)

<Steps>
  <Step title="Extracción programada">
    En cada intervalo, CaseBender enumera los ID de hallazgos actualizados desde el último cursor
    (opcionalmente filtrados por severidad mínima) y luego obtiene los hallazgos completos. En la
    primera ejecución se importan los hallazgos actualizados dentro de
    `pollingInitialLookbackHours`.
  </Step>

  <Step title="Cursor + deduplicación">
    CaseBender avanza el cursor hasta el `updatedAt` más reciente. Los hallazgos se **deduplican
    por ID de hallazgo**, por lo que las ventanas superpuestas nunca crean duplicados.
  </Step>

  <Step title="Normalización">
    Cada hallazgo se normaliza como una alerta de CaseBender con observables, tácticas MITRE,
    categoría de ataque y orientación de remediación.
  </Step>
</Steps>

<Info>
  El sondeo se ejecuta en el servicio de sondeo en segundo plano de CaseBender. Para cobertura
  multirregión, cree una integración de GuardDuty por región.
</Info>

## Entrada (webhook de EventBridge / push)

Como alternativa, una regla de EventBridge (con un destino de API) puede hacer POST de los
hallazgos a:

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

Las solicitudes se autentican con la **API key** de integración en el encabezado `x-api-key`. Se
aceptan tanto el hallazgo en bruto como el sobre de EventBridge `{ "detail": { ... } }`.

## Consideraciones de seguridad

* **Privilegio mínimo** — otorgue solo las tres acciones de solo lectura de GuardDuty indicadas
  arriba.
* **Manejo de secretos** — rote la clave de acceso IAM según la política de su organización;
  prefiera claves asignadas a un usuario de integración dedicado.
* **Red** — restrinja la salida al endpoint regional de GuardDuty.

## Solución de problemas

<AccordionGroup>
  <Accordion title="No se encuentra ningún detector">
    Confirme que GuardDuty está habilitado en la región configurada o establezca el Detector ID
    explícitamente.
  </Accordion>

  <Accordion title="El sondeo está activado pero no aparecen hallazgos">
    Verifique que la clave IAM tiene `ListDetectors`, `ListFindings` y `GetFindings`. Compruebe la
    región y que existen hallazgos más nuevos que el cursor. En la primera ejecución solo se
    importan hallazgos dentro de `pollingInitialLookbackHours`.

    **Asegúrese de que todos los servicios de CaseBender estén en ejecución** — con Docker,
    `docker compose ps` debe mostrar los servicios `worker` y `misp-processor` como `Up`.
  </Accordion>

  <Accordion title="Errores AccessDenied">
    A la política IAM le falta una de las acciones requeridas, o la clave pertenece a una cuenta o
    región distinta de la esperada.
  </Accordion>
</AccordionGroup>

## Documentación relacionada

* [Descripción general de integraciones](./introduction.mdx)
* [Documentación de AWS GuardDuty](https://docs.aws.amazon.com/guardduty/)