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

# CrowdStrike Falcon

> CaseBender와 CrowdStrike Falcon 간의 양방향 통합으로 탐지 수집(pull 또는 push)과 처리 상태 동기화를 제공합니다.

## 개요

CrowdStrike Falcon 통합(**INT-008**)은 Falcon 탐지를 CaseBender로 수집하고, 케이스가 종료될 때
처리 상태를 Falcon으로 다시 전달할 수 있습니다.

<CardGroup cols={2}>
  <Card title="인바운드 수집" icon="arrow-right-to-bracket">
    Falcon 탐지는 예약된 일정에 따라 **자동으로 가져오거나**(권장) 웹훅으로
    **푸시**된 후, 정규화되어 관찰 대상과 MITRE ATT\&CK 기법으로 보강되고 알림으로
    변환됩니다.
  </Card>

  <Card title="아웃바운드 동기화" icon="arrow-right-from-bracket">
    CaseBender에서 연결된 케이스가 종료되면 Falcon 탐지 상태가 감사 코멘트와 함께
    업데이트됩니다.
  </Card>
</CardGroup>

<Tip>
  **권장: 자동 폴링을 활성화하세요.** CaseBender는 동일한 Falcon API 클라이언트를
  사용하여 예약된 일정에 따라 새 탐지를 가져올 수 있습니다. 웹훅이나 SIEM 커넥터가
  필요하지 않습니다. [자동 폴링](#인바운드자동-폴링)을 참조하세요.
</Tip>

<Note>
  이 통합은 **Falcon Alerts API v2**를 사용하며 client-credentials 플로우로
  **OAuth2 API 클라이언트**(client ID + secret)를 통해 인증합니다.
</Note>

## 기능

| 기능               | 방향    | 설명                                                                        |
| ---------------- | ----- | ------------------------------------------------------------------------- |
| **탐지 폴링(pull)**  | 인바운드  | CaseBender가 예약된 일정에 따라 Alerts API를 조회하고 새 탐지를 자동으로 수집합니다(Falcon 측 구성 불필요) |
| 탐지 수집(push)      | 인바운드  | Falcon 탐지가 웹훅으로 푸시되어 알림으로 정규화됩니다                                          |
| 관찰 대상 추출         | 인바운드  | IP, 파일 해시, 파일 이름, 호스트, 사용자                                                |
| MITRE ATT\&CK 상관 | 인바운드  | 기법/전술 ID가 태그 및 TTP로 추가됩니다                                                 |
| 처리 상태 동기화        | 아웃바운드 | 케이스 종료 시 탐지 상태 + 코멘트를 전송                                                  |
| 연결 테스트           | 양방향   | OAuth2 자격 증명 및 API 액세스를 검증                                                |

## 사전 요구 사항

<Steps>
  <Step title="Falcon API 클라이언트">
    Falcon 콘솔에서 **Support and resources → API clients and keys**로 이동하여 API 클라이언트를
    생성합니다. **Alerts: Read** 범위(아웃바운드 종료가 필요하면 **Alerts: Write**)를 부여합니다.
    **Client ID**와 **Secret**을 복사합니다.
  </Step>

  <Step title="클라우드 리전 기본 URL">
    Falcon 클라우드의 기본 URL(예: `https://api.crowdstrike.com`,
    `https://api.us-2.crowdstrike.com`, `https://api.eu-1.crowdstrike.com`)을 기록합니다.
  </Step>

  <Step title="네트워크 아웃바운드">
    CaseBender 폴링 서비스가 Falcon API 기본 URL에 도달할 수 있어야 합니다.
  </Step>
</Steps>

## CaseBender에서 통합 구성

<Steps>
  <Step title="통합 카탈로그 열기">
    **Settings → Integrations → Create**로 이동하여 **EDR/XDR** 카테고리에서 **CrowdStrike Falcon**
    을 선택합니다.
  </Step>

  <Step title="Falcon API 자격 증명 입력">
    | 필드                       | 설명                                                    |
    | ------------------------ | ----------------------------------------------------- |
    | API URL                  | Falcon 클라우드 기본 URL(기본값 `https://api.crowdstrike.com`) |
    | Falcon API Client ID     | OAuth2 client ID                                      |
    | Falcon API Client Secret | OAuth2 client secret                                  |
  </Step>

  <Step title="자동 폴링 활성화(권장)">
    **Automatic polling** 카드에서 **Enable automatic polling**을 켜고 다음을 구성합니다.

    | 옵션                            | 효과                                               |
    | ----------------------------- | ------------------------------------------------ |
    | `pollingEnabled`              | Falcon 탐지의 예약 가져오기 활성화                           |
    | `pollingIntervalMinutes`      | 폴링 주기(기본값 `5`, 범위 1–1440)                        |
    | `pollingInitialLookbackHours` | 첫 실행 시 이 범위 내에 업데이트된 탐지를 가져옴(기본값 `24`, 범위 1–168) |
    | `pollMaxItemsPerRun`          | 실행당 수집 항목 안전 상한(기본값 `500`)                       |
  </Step>

  <Step title="케이스 자동 생성 구성">
    | 옵션                   | 효과                                                               |
    | -------------------- | ---------------------------------------------------------------- |
    | `autoCreateCases`    | 수집된 각 탐지를 **케이스**로 승격(탐지 ID로 중복 제거). 비활성화 시 탐지는 알림 받은 편지함에 유지됩니다 |
    | `minSeverityForCase` | 이 심각도 이상일 때만 케이스를 자동 생성                                          |
  </Step>
</Steps>

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

**자동 폴링**을 활성화하면 CaseBender 폴러가 주기적으로 Falcon Alerts API를 조회하고 새 탐지를
스스로 수집합니다.

<Steps>
  <Step title="예약 가져오기">
    각 주기마다 CaseBender는 Alerts API v2를 통해 마지막 커서 이후 업데이트된 복합 ID를 조회한 다음
    전체 탐지 엔터티를 가져옵니다. 첫 실행 시에는 커서가 없으므로 `pollingInitialLookbackHours` 이내의
    탐지를 가져옵니다.
  </Step>

  <Step title="커서 + 중복 제거">
    CaseBender는 통합별 커서를 가장 최근의 `updated_timestamp`까지 진행합니다. 탐지는 **탐지 ID로
    중복 제거**되므로 폴링 윈도우가 겹쳐도 중복 알림이 생성되지 않습니다.
  </Step>

  <Step title="정규화">
    각 탐지는 CaseBender 알림으로 정규화됩니다(심각도 매핑, 제목/설명 생성, 관찰 대상 추출, MITRE
    TTP 생성).
  </Step>
</Steps>

<Info>
  폴링은 CaseBender의 백그라운드 폴링 서비스에서 실행됩니다. 해당 서비스가 Falcon API 기본 URL에
  (직접 또는 구성된 프록시를 통해) 도달할 수 있는지 확인하세요.
</Info>

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

폴링의 대안으로 Falcon(또는 중계자)이 탐지 페이로드를 CaseBender 수집 엔드포인트로 푸시할 수
있습니다.

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

요청은 `x-api-key` 헤더의 통합 **API 키**로 인증됩니다. Falcon 웹훅 API 키에는 `cbr_crowdstrike_`
접두사가 붙습니다.

## 아웃바운드: Falcon으로 처리 상태 동기화

케이스가 종료되면 `case_closed` 이벤트가 CrowdStrike 핸들러로 디스패치됩니다. 케이스가 Falcon
탐지에 연결되어 있으면(탐지 ID가 수집된 알림에 각인됨) 핸들러가 탐지 상태를 업데이트하고 감사
코멘트를 추가합니다. 아웃바운드 종료에는 API 클라이언트의 **Alerts: Write** 범위가 필요합니다.

## 보안 고려 사항

* **최소 권한** — 인바운드 전용이면 **Alerts: Read**만 부여하고, 아웃바운드 종료를 활성화할 때만
  **Alerts: Write**를 추가하세요.
* **시크릿 처리** — client secret은 통합 설정에 저장됩니다. 조직 정책에 따라 교체하세요.
* **토큰 캐시** — 액세스 토큰은 메모리에 캐시되며 만료 전에 갱신됩니다.
* **네트워크** — 아웃바운드를 Falcon API 기본 URL로 제한하세요.

## 문제 해결

<AccordionGroup>
  <Accordion title="연결 테스트가 OAuth2 오류로 실패함">
    client ID, secret, API 기본 URL(리전)을 확인하세요. API 클라이언트가 활성화되어 있고 Alerts 범위를
    가지고 있는지 확인합니다.
  </Accordion>

  <Accordion title="폴링은 활성화되어 있지만 탐지가 표시되지 않음">
    **Enable automatic polling**이 켜져 있고 API 클라이언트에 Alerts: Read 범위가 있는지 확인하세요.
    폴러가 Falcon 기본 URL에 도달할 수 있는지 확인합니다. 첫 실행 시에는 `pollingInitialLookbackHours`
    이내의 탐지만 가져옵니다.

    **모든 CaseBender 서비스가 실행 중인지 확인하세요.** 탐지는 백그라운드 프로세서가 가져오고
    백그라운드 **worker**가 알림(및 선택적으로 케이스)으로 변환합니다. Docker에서는 `docker compose ps`
    를 실행하여 `worker` 및 `misp-processor` 서비스가 `Up` 상태인지 확인하세요.
  </Accordion>

  <Accordion title="케이스 종료가 Falcon을 업데이트하지 않음">
    API 클라이언트에 Alerts: Write 범위가 있고 케이스가 Falcon 탐지에 연결되어 있는지 확인하세요.
    동기화 결과는 케이스 타임라인에서 확인할 수 있습니다.
  </Accordion>
</AccordionGroup>

## 관련 문서

* [통합 개요](./introduction.mdx)
* [CrowdStrike Falcon API 문서](https://falcon.crowdstrike.com/documentation/)