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

> Ingira os findings do AWS GuardDuty no CaseBender via sondagem automática (pull) ou webhook do EventBridge (push).

## Visão geral

A integração do AWS GuardDuty (**INT-023**) ingere os findings do GuardDuty no CaseBender, os
enriquece com mapeamento MITRE ATT\&CK e categorização de ataques, e os converte em alertas (e
opcionalmente casos).

<CardGroup cols={2}>
  <Card title="Sondagem automática (pull)" icon="arrow-right-to-bracket">
    O CaseBender extrai novos findings diretamente da sua conta AWS de forma
    agendada usando credenciais IAM — sem regra do EventBridge.
  </Card>

  <Card title="Webhook do EventBridge (push)" icon="bolt">
    Como alternativa, uma regra do EventBridge encaminha os findings ao endpoint de
    ingestão do CaseBender.
  </Card>
</CardGroup>

<Tip>
  **Recomendado: ative a sondagem automática.** Requer apenas uma chave IAM
  somente leitura e nenhum endpoint de entrada. Consulte
  [Sondagem automática](#entrada-sondagem-automatica).
</Tip>

<Note>
  A sondagem usa o **SDK oficial da AWS** contra a API do GuardDuty
  (`ListDetectors`, `ListFindings`, `GetFindings`).
</Note>

## Recursos

| Recurso                         | Direção | Descrição                                                                          |
| ------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| **Sondagem de findings (pull)** | Entrada | O CaseBender consulta a API do GuardDuty de forma agendada e ingere novos findings |
| Ingestão de findings (push)     | Entrada | O EventBridge encaminha os findings ao endpoint de ingestão                        |
| Extração de observáveis         | Entrada | IPs, domínios, chaves de acesso, buckets S3, IPs de instâncias                     |
| Correlação MITRE ATT\&CK        | Entrada | Os tipos de finding são mapeados para táticas/técnicas                             |
| Categorização de ataques        | Entrada | Os findings são categorizados e recebem orientação de remediação                   |

## Pré-requisitos

<Steps>
  <Step title="Habilitar o GuardDuty">
    O GuardDuty deve estar habilitado nas regiões AWS que você deseja monitorar.
  </Step>

  <Step title="Criar um usuário IAM / chave de acesso">
    Crie um principal IAM com uma política que permita `guardduty:ListDetectors`,
    `guardduty:ListFindings` e `guardduty:GetFindings`. Gere um access key ID + secret.
  </Step>

  <Step title="Saída de rede">
    O sondador do CaseBender deve alcançar o endpoint da API do GuardDuty da sua região
    (`guardduty.<region>.amazonaws.com`).
  </Step>
</Steps>

## Configurar a integração no CaseBender

<Steps>
  <Step title="Abrir o catálogo de integrações">
    Vá em **Settings → Integrations → Create** e escolha **AWS GuardDuty** na categoria
    **Cloud Security**.
  </Step>

  <Step title="Inserir as credenciais da AWS">
    | Campo                       | Descrição                                                                         |
    | --------------------------- | --------------------------------------------------------------------------------- |
    | AWS Access Key ID           | Access key ID do IAM                                                              |
    | AWS Secret Access Key       | Secret access key do IAM                                                          |
    | AWS Region                  | Região onde o GuardDuty está habilitado (ex.: `us-east-1`)                        |
    | Detector ID (opcional)      | Descoberto automaticamente a partir da região se em branco                        |
    | Minimum severity (opcional) | Severidade do GuardDuty 1–8.9; apenas findings a partir deste valor são extraídos |
  </Step>

  <Step title="Ativar a sondagem automática (recomendado)">
    | Opção                         | Efeito                                                                        |
    | ----------------------------- | ----------------------------------------------------------------------------- |
    | `pollingEnabled`              | Ativa a extração agendada de findings                                         |
    | `pollingIntervalMinutes`      | Frequência de sondagem (padrão `5`)                                           |
    | `pollingInitialLookbackHours` | Na primeira execução, importa findings atualizados nesta janela (padrão `24`) |
    | `pollMaxItemsPerRun`          | Limite de segurança de itens por execução (padrão `500`)                      |
  </Step>

  <Step title="Configurar a criação automática de casos">
    | Opção                | Efeito                                                             |
    | -------------------- | ------------------------------------------------------------------ |
    | `autoCreateCases`    | Promove cada finding a um **Caso** (deduplicado por ID de finding) |
    | `minSeverityForCase` | Cria casos automaticamente apenas a partir desta severidade        |
  </Step>
</Steps>

## Entrada (sondagem automática)

<Steps>
  <Step title="Extração agendada">
    A cada intervalo, o CaseBender enumera os IDs de findings atualizados desde o último cursor
    (opcionalmente filtrados por severidade mínima) e então busca os findings completos. Na primeira
    execução, os findings atualizados dentro de `pollingInitialLookbackHours` são importados.
  </Step>

  <Step title="Cursor + deduplicação">
    O CaseBender avança o cursor até o `updatedAt` mais recente. Os findings são **deduplicados por
    ID de finding**, de modo que janelas sobrepostas nunca criam duplicatas.
  </Step>

  <Step title="Normalização">
    Cada finding é normalizado em um alerta do CaseBender com observáveis, táticas MITRE, categoria
    de ataque e orientação de remediação.
  </Step>
</Steps>

<Info>
  A sondagem é executada no serviço de sondagem em segundo plano do CaseBender. Para cobertura
  multirregião, crie uma integração do GuardDuty por região.
</Info>

## Entrada (webhook do EventBridge / push)

Como alternativa, uma regra do EventBridge (com um destino de API) pode fazer POST dos findings
para:

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

As requisições são autenticadas com a **API key** de integração no cabeçalho `x-api-key`. Tanto o
finding bruto quanto o envelope do EventBridge `{ "detail": { ... } }` são aceitos.

## Considerações de segurança

* **Privilégio mínimo** — conceda apenas as três ações somente leitura do GuardDuty listadas acima.
* **Manejo de segredos** — faça a rotação da chave de acesso IAM conforme a política da sua
  organização; prefira chaves atribuídas a um usuário de integração dedicado.
* **Rede** — restrinja a saída ao endpoint regional do GuardDuty.

## Solução de problemas

<AccordionGroup>
  <Accordion title="Nenhum detector encontrado">
    Confirme que o GuardDuty está habilitado na região configurada, ou defina o Detector ID
    explicitamente.
  </Accordion>

  <Accordion title="A sondagem está ativada, mas nenhum finding aparece">
    Verifique se a chave IAM possui `ListDetectors`, `ListFindings` e `GetFindings`. Verifique a
    região e a existência de findings mais recentes que o cursor. Na primeira execução, apenas os
    findings dentro de `pollingInitialLookbackHours` são importados.

    **Certifique-se de que todos os serviços do CaseBender estejam em execução** — com o Docker,
    `docker compose ps` deve mostrar os serviços `worker` e `misp-processor` como `Up`.
  </Accordion>

  <Accordion title="Erros AccessDenied">
    A política IAM está sem uma das ações necessárias, ou a chave pertence a uma conta/região
    diferente da esperada.
  </Accordion>
</AccordionGroup>

## Documentação relacionada

* [Visão geral das integrações](./introduction.mdx)
* [Documentação do AWS GuardDuty](https://docs.aws.amazon.com/guardduty/)