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

> 자동 폴링(pull) 또는 EventBridge 웹훅(push)을 통해 AWS GuardDuty 발견 항목을 CaseBender로 수집합니다.

## 개요

AWS GuardDuty 통합(**INT-023**)은 GuardDuty 발견 항목(findings)을 CaseBender로 수집하고 MITRE
ATT\&CK 매핑 및 공격 분류로 보강하여 알림(및 선택적으로 케이스)으로 변환합니다.

<CardGroup cols={2}>
  <Card title="자동 폴링(pull)" icon="arrow-right-to-bracket">
    CaseBender는 IAM 자격 증명을 사용하여 예약된 일정에 따라 AWS 계정에서 직접 새
    발견 항목을 가져옵니다. EventBridge 규칙이 필요하지 않습니다.
  </Card>

  <Card title="EventBridge 웹훅(push)" icon="bolt">
    대안으로 EventBridge 규칙이 발견 항목을 CaseBender 수집 엔드포인트로 전달합니다.
  </Card>
</CardGroup>

<Tip>
  **권장: 자동 폴링을 활성화하세요.** 읽기 전용 IAM 키만 필요하며 인바운드
  엔드포인트가 필요하지 않습니다. [자동 폴링](#인바운드자동-폴링)을 참조하세요.
</Tip>

<Note>
  폴링은 **공식 AWS SDK**를 사용하여 GuardDuty API(`ListDetectors`, `ListFindings`,
  `GetFindings`)를 호출합니다.
</Note>

## 기능

| 기능                 | 방향   | 설명                                                        |
| ------------------ | ---- | --------------------------------------------------------- |
| **발견 항목 폴링(pull)** | 인바운드 | CaseBender가 예약된 일정에 따라 GuardDuty API를 조회하고 새 발견 항목을 수집합니다 |
| 발견 항목 수집(push)     | 인바운드 | EventBridge가 발견 항목을 수집 엔드포인트로 전달합니다                       |
| 관찰 대상 추출           | 인바운드 | IP, 도메인, 액세스 키, S3 버킷, 인스턴스 IP                            |
| MITRE ATT\&CK 상관   | 인바운드 | 발견 항목 유형이 전술/기법에 매핑됩니다                                    |
| 공격 분류              | 인바운드 | 발견 항목이 분류되고 대응 지침이 부여됩니다                                  |

## 사전 요구 사항

<Steps>
  <Step title="GuardDuty 활성화">
    모니터링하려는 AWS 리전에서 GuardDuty를 활성화해야 합니다.
  </Step>

  <Step title="IAM 사용자 / 액세스 키 생성">
    `guardduty:ListDetectors`, `guardduty:ListFindings`, `guardduty:GetFindings`를 허용하는 정책을
    가진 IAM 주체를 생성합니다. access key ID + secret을 생성합니다.
  </Step>

  <Step title="네트워크 아웃바운드">
    CaseBender 폴러가 해당 리전의 GuardDuty API 엔드포인트(`guardduty.<region>.amazonaws.com`)에
    도달할 수 있어야 합니다.
  </Step>
</Steps>

## CaseBender에서 통합 구성

<Steps>
  <Step title="통합 카탈로그 열기">
    **Settings → Integrations → Create**로 이동하여 **Cloud Security** 카테고리에서 **AWS GuardDuty**
    를 선택합니다.
  </Step>

  <Step title="AWS 자격 증명 입력">
    | 필드                    | 설명                                        |
    | --------------------- | ----------------------------------------- |
    | AWS Access Key ID     | IAM access key ID                         |
    | AWS Secret Access Key | IAM secret access key                     |
    | AWS Region            | GuardDuty가 활성화된 리전(예: `us-east-1`)        |
    | Detector ID(선택)       | 비워두면 리전에서 자동 검색                           |
    | Minimum severity(선택)  | GuardDuty 심각도 1–8.9. 이 값 이상의 발견 항목만 가져옵니다 |
  </Step>

  <Step title="자동 폴링 활성화(권장)">
    | 옵션                            | 효과                                        |
    | ----------------------------- | ----------------------------------------- |
    | `pollingEnabled`              | 발견 항목의 예약 가져오기 활성화                        |
    | `pollingIntervalMinutes`      | 폴링 주기(기본값 `5`)                            |
    | `pollingInitialLookbackHours` | 첫 실행 시 이 범위 내에 업데이트된 발견 항목을 가져옴(기본값 `24`) |
    | `pollMaxItemsPerRun`          | 실행당 수집 항목 안전 상한(기본값 `500`)                |
  </Step>

  <Step title="케이스 자동 생성 구성">
    | 옵션                   | 효과                                    |
    | -------------------- | ------------------------------------- |
    | `autoCreateCases`    | 각 발견 항목을 **케이스**로 승격(발견 항목 ID로 중복 제거) |
    | `minSeverityForCase` | 이 심각도 이상일 때만 케이스를 자동 생성               |
  </Step>
</Steps>

## 인바운드(자동 폴링)

<Steps>
  <Step title="예약 가져오기">
    각 주기마다 CaseBender는 마지막 커서 이후 업데이트된 발견 항목 ID를 열거하고(선택적으로 최소
    심각도로 필터링) 전체 발견 항목을 가져옵니다. 첫 실행 시에는 `pollingInitialLookbackHours` 이내에
    업데이트된 발견 항목을 가져옵니다.
  </Step>

  <Step title="커서 + 중복 제거">
    CaseBender는 커서를 가장 최근의 `updatedAt`까지 진행합니다. 발견 항목은 **발견 항목 ID로 중복
    제거**되므로 윈도우가 겹쳐도 중복이 생성되지 않습니다.
  </Step>

  <Step title="정규화">
    각 발견 항목은 관찰 대상, MITRE 전술, 공격 카테고리, 대응 지침을 포함한 CaseBender 알림으로
    정규화됩니다.
  </Step>
</Steps>

<Info>
  폴링은 CaseBender의 백그라운드 폴링 서비스에서 실행됩니다. 다중 리전 커버리지를 위해서는 리전마다
  GuardDuty 통합을 생성하세요.
</Info>

## 인바운드(EventBridge 웹훅 / 푸시)

대안으로 EventBridge 규칙(API 대상 포함)이 발견 항목을 다음으로 POST할 수 있습니다.

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

요청은 `x-api-key` 헤더의 통합 **API 키**로 인증됩니다. 원시 발견 항목과 EventBridge 래퍼
`{ "detail": { ... } }`를 모두 허용합니다.

## 보안 고려 사항

* **최소 권한** — 위에 나열된 세 가지 읽기 전용 GuardDuty 작업만 부여하세요.
* **시크릿 처리** — 조직 정책에 따라 IAM 액세스 키를 교체하고, 전용 통합 사용자에게 할당된 키를
  사용하세요.
* **네트워크** — 아웃바운드를 리전의 GuardDuty 엔드포인트로 제한하세요.

## 문제 해결

<AccordionGroup>
  <Accordion title="탐지기(detector)를 찾을 수 없음">
    구성한 리전에서 GuardDuty가 활성화되어 있는지 확인하거나 Detector ID를 명시적으로 설정하세요.
  </Accordion>

  <Accordion title="폴링은 활성화되어 있지만 발견 항목이 표시되지 않음">
    IAM 키에 `ListDetectors`, `ListFindings`, `GetFindings`가 있는지 확인하세요. 리전과 커서보다 새로운
    발견 항목의 존재 여부를 확인합니다. 첫 실행 시에는 `pollingInitialLookbackHours` 이내의 발견 항목만
    가져옵니다.

    **모든 CaseBender 서비스가 실행 중인지 확인하세요** — Docker에서는 `docker compose ps`에서
    `worker` 및 `misp-processor` 서비스가 `Up` 상태여야 합니다.
  </Accordion>

  <Accordion title="AccessDenied 오류">
    IAM 정책에 필요한 작업 중 하나가 없거나, 키가 예상과 다른 계정/리전에 속해 있습니다.
  </Accordion>
</AccordionGroup>

## 관련 문서

* [통합 개요](./introduction.mdx)
* [AWS GuardDuty 문서](https://docs.aws.amazon.com/guardduty/)