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

> Ingest AWS GuardDuty findings into CaseBender by automatic polling (pull) or EventBridge webhook (push).

## Overview

The AWS GuardDuty integration (**INT-023**) ingests GuardDuty findings into CaseBender, enriches
them with MITRE ATT\&CK mapping and attack categorization, and turns them into alerts (and
optionally cases).

<CardGroup cols={2}>
  <Card title="Automatic polling (pull)" icon="arrow-right-to-bracket">
    CaseBender pulls new findings directly from your AWS account on a schedule
    using IAM credentials — no EventBridge rule required.
  </Card>

  <Card title="EventBridge webhook (push)" icon="bolt">
    Alternatively, an EventBridge rule forwards findings to the CaseBender
    ingestion endpoint.
  </Card>
</CardGroup>

<Tip>
  **Recommended: enable Automatic polling.** It requires only a read-only IAM
  key and no inbound endpoint. See
  [Automatic polling](#inbound-automatic-polling-recommended).
</Tip>

<Note>
  Polling uses the official **AWS SDK** against the GuardDuty API
  (`ListDetectors`, `ListFindings`, `GetFindings`).
</Note>

## Capabilities

| Capability                 | Direction | Description                                                               |
| -------------------------- | --------- | ------------------------------------------------------------------------- |
| **Finding polling (pull)** | Inbound   | CaseBender polls the GuardDuty API on a schedule and ingests new findings |
| Finding ingestion (push)   | Inbound   | EventBridge forwards findings to the ingestion endpoint                   |
| Observable extraction      | Inbound   | IPs, domains, access keys, S3 buckets, instance IPs                       |
| MITRE ATT\&CK correlation  | Inbound   | Finding types are mapped to tactics/techniques                            |
| Attack categorization      | Inbound   | Findings are categorized and given remediation guidance                   |

## Prerequisites

<Steps>
  <Step title="Enable GuardDuty">
    GuardDuty must be enabled in the AWS region(s) you want to monitor.
  </Step>

  <Step title="Create an IAM user / access key">
    Create an IAM principal with a policy allowing `guardduty:ListDetectors`,
    `guardduty:ListFindings`, and `guardduty:GetFindings`. Generate an access key ID + secret.
  </Step>

  <Step title="Network egress">
    The CaseBender poller must reach the GuardDuty API endpoint for your region
    (`guardduty.<region>.amazonaws.com`).
  </Step>
</Steps>

## Configure the integration in CaseBender

<Steps>
  <Step title="Open the integration catalog">
    Go to **Settings → Integrations → Create**, then choose **AWS GuardDuty** from the
    **Cloud Security** category.
  </Step>

  <Step title="Enter AWS credentials">
    | Field                       | Description                                                 |
    | --------------------------- | ----------------------------------------------------------- |
    | AWS Access Key ID           | IAM access key ID                                           |
    | AWS Secret Access Key       | IAM secret access key                                       |
    | AWS Region                  | Region where GuardDuty is enabled (e.g. `us-east-1`)        |
    | Detector ID (optional)      | Auto-discovered from the region if blank                    |
    | Minimum severity (optional) | GuardDuty severity 1–8.9; only findings at/above are pulled |
  </Step>

  <Step title="Enable automatic polling (recommended)">
    | Option                        | Effect                                                                  |
    | ----------------------------- | ----------------------------------------------------------------------- |
    | `pollingEnabled`              | Turn on scheduled pulling of findings                                   |
    | `pollingIntervalMinutes`      | How often to poll (default `5`)                                         |
    | `pollingInitialLookbackHours` | On first run, import findings updated within this window (default `24`) |
    | `pollMaxItemsPerRun`          | Safety cap on items ingested per run (default `500`)                    |
  </Step>

  <Step title="Configure auto-case creation">
    | Option               | Effect                                                     |
    | -------------------- | ---------------------------------------------------------- |
    | `autoCreateCases`    | Promote each finding to a **Case** (deduped by finding ID) |
    | `minSeverityForCase` | Only auto-create cases at/above this severity              |
  </Step>
</Steps>

## Inbound (automatic polling, recommended)

<Steps>
  <Step title="Scheduled pull">
    On each interval, CaseBender lists finding IDs updated since the last cursor (optionally
    filtered by minimum severity), then fetches the full findings. On first run, findings updated
    within `pollingInitialLookbackHours` are imported.
  </Step>

  <Step title="Cursor + deduplication">
    CaseBender advances the cursor to the newest `updatedAt`. Findings are **deduplicated by
    finding ID**, so overlapping windows never create duplicates.
  </Step>

  <Step title="Normalization">
    Each finding is normalized into a CaseBender alert with observables, MITRE tactics, attack
    category, and remediation guidance.
  </Step>
</Steps>

<Info>
  Polling runs in CaseBender's background poller service. For multi-region coverage, create one
  GuardDuty integration per region.
</Info>

## Inbound (EventBridge webhook / push)

As an alternative, an EventBridge rule (with an API destination) can POST findings to:

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

Requests are authenticated with the integration **API key** in the `x-api-key` header. Both the
raw finding and the EventBridge `{ "detail": { ... } }` envelope are accepted.

## Security considerations

* **Least privilege** — grant only the three read-only GuardDuty actions listed above.
* **Secret handling** — rotate the IAM access key on your organization's schedule; prefer keys
  scoped to a dedicated integration user.
* **Network** — restrict egress to the GuardDuty regional endpoint.

## Troubleshooting

<AccordionGroup>
  <Accordion title="No detector found">
    Confirm GuardDuty is enabled in the configured region, or set the Detector ID explicitly.
  </Accordion>

  <Accordion title="Polling is enabled but no findings appear">
    Verify the IAM key has `ListDetectors`, `ListFindings`, and `GetFindings`. Check the region
    and that findings exist newer than the cursor. On first run only findings within
    `pollingInitialLookbackHours` are imported.

    **Make sure all CaseBender services are running** — with Docker, `docker compose ps` should
    show the `worker` and `misp-processor` services `Up`.
  </Accordion>

  <Accordion title="AccessDenied errors">
    The IAM policy is missing one of the required actions, or the key belongs to a different
    account/region than expected.
  </Accordion>
</AccordionGroup>

## Related documentation

* [Integrations overview](./introduction.mdx)
* [AWS GuardDuty documentation](https://docs.aws.amazon.com/guardduty/)