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

# Microsoft Defender XDR

> 알림/인시던트 수집 및 처리 결과 동기화를 위한 CaseBender와 Microsoft Defender XDR(Windows Defender) 간의 양방향 통합.

## 개요

Microsoft Defender XDR 통합(**INT-021**)은 **Microsoft Defender for Endpoint(MDE)** 및
**Microsoft Defender XDR**를 포함한 Microsoft의 확장 탐지 및 대응 플랫폼과 CaseBender 간에
**양방향** 동기화를 제공합니다.

<CardGroup cols={2}>
  <Card title="인바운드 수집" icon="arrow-right-to-bracket">
    Defender 알림 및 인시던트가 CaseBender로 수집되어 정규화되고, 관찰 가능 항목과 MITRE
    ATT\&CK 기법으로 보강되어 알림/케이스로 변환됩니다.
  </Card>

  <Card title="아웃바운드 동기화" icon="arrow-right-from-bracket">
    CaseBender 케이스가 종료되면 연결된 Defender 알림/인시던트가 Microsoft Graph를 통해 상태,
    분류 및 감사 코멘트와 함께 업데이트됩니다.
  </Card>
</CardGroup>

<Note>
  이 통합은 **Microsoft Graph 보안 API**(`https://graph.microsoft.com/v1.0/security`)를
  사용합니다. OAuth2 클라이언트 자격 증명 흐름을 사용하여 **Azure AD(Entra ID) 애플리케이션**으로
  인증합니다.
</Note>

## 기능

| 기능                  | 방향    | 설명                                                           |
| ------------------- | ----- | ------------------------------------------------------------ |
| 알림 수집               | 인바운드  | Defender 알림을 CaseBender 알림으로 정규화                             |
| 인시던트 수집             | 인바운드  | Defender 인시던트(하위 알림 포함) 수집                                   |
| 관찰 가능 항목 추출         | 인바운드  | 증거에서 IP, URL, 파일 해시, 파일 이름, 호스트 이름, 사용자 계정 추출                |
| 자산 추출               | 인바운드  | `devices[]`에서 디바이스 호스트 이름, IP, OS 플랫폼 캡처                     |
| MITRE ATT\&CK 상관 관계 | 인바운드  | 기법 ID를 태그 및 TTP로 추가(예: `mitre:T1078`)                        |
| 알림 동기화              | 아웃바운드 | 케이스 종료 시 `status`, `classification`, `determination`, 코멘트 전송 |
| 인시던트 동기화            | 아웃바운드 | 케이스 종료 시 `status`, `classification`, `determination`, 코멘트 전송 |
| 연결 테스트              | 양방향   | OAuth2 자격 증명 및 Graph 보안 API 액세스 검증                           |

## 사전 요구 사항

<Steps>
  <Step title="Microsoft Defender / Entra ID 액세스">
    Microsoft Defender XDR 또는 Microsoft Defender for Endpoint가 라이선스되고 활성화된
    Microsoft Entra ID(Azure AD) 테넌트. 애플리케이션을 등록하고 관리자 동의를 부여할 권한이
    필요합니다.
  </Step>

  <Step title="네트워크 송신">
    CaseBender 배포는 다음에 연결할 수 있어야 합니다:

    * `https://login.microsoftonline.com`(OAuth2 토큰 엔드포인트)
    * `https://graph.microsoft.com`(Graph 보안 API)
  </Step>

  <Step title="CaseBender 관리자 역할">
    **설정 → 통합**에서 통합을 생성하고 관리할 수 있어야 합니다.
  </Step>
</Steps>

## 파트 A — Azure AD 애플리케이션 등록

<Steps>
  <Step title="앱 등록 생성">
    [Microsoft Entra 관리 센터](https://entra.microsoft.com)에서 **ID → 애플리케이션 →
    앱 등록 → 새 등록**으로 이동합니다. 이름(예: `CaseBender Defender Integration`)을 지정하고
    등록합니다.
  </Step>

  <Step title="식별자 기록">
    애플리케이션 **개요**에서 **애플리케이션(클라이언트) ID**와 **디렉터리(테넌트) ID**를
    복사합니다. 이를 CaseBender에 입력합니다.
  </Step>

  <Step title="클라이언트 비밀 생성">
    **인증서 및 비밀 → 새 클라이언트 비밀**에서 비밀을 만들고 그 **값**을 즉시 복사합니다
    (한 번만 표시됨).
  </Step>

  <Step title="Graph 보안 API 권한 부여">
    **API 권한 → 권한 추가 → Microsoft Graph → 애플리케이션 권한**에서 다음을 추가한 후
    **관리자 동의 부여**를 클릭합니다:

    | 권한                               | 목적                      |
    | -------------------------------- | ----------------------- |
    | `SecurityAlert.ReadWrite.All`    | Defender 알림 읽기 및 업데이트   |
    | `SecurityIncident.ReadWrite.All` | Defender 인시던트 읽기 및 업데이트 |

    <Warning>
      **애플리케이션** 권한(위임 아님)을 사용하십시오. 통합은 클라이언트 자격 증명 흐름으로
      헤드리스 실행되며 테넌트 관리자 동의가 필요합니다.
    </Warning>
  </Step>
</Steps>

## 파트 B — CaseBender에서 통합 구성

<Steps>
  <Step title="통합 카탈로그 열기">
    **설정 → 통합 → 생성**으로 이동한 다음 **EDR/XDR** 범주에서 **Microsoft Defender XDR**를
    선택합니다.
  </Step>

  <Step title="Azure AD 자격 증명 입력">
    파트 A에서 캡처한 값을 입력합니다:

    | 필드             | 설명               |
    | -------------- | ---------------- |
    | `tenantId`     | 디렉터리(테넌트) ID     |
    | `clientId`     | 애플리케이션(클라이언트) ID |
    | `clientSecret` | 클라이언트 비밀 값       |
  </Step>

  <Step title="동기화 옵션 구성">
    필요한 동작을 활성화합니다:

    | 옵션                          | 효과                                |
    | --------------------------- | --------------------------------- |
    | `syncCaseUpdates`           | 케이스 업데이트를 Defender로 전송            |
    | `syncCaseClose`             | 케이스 종료를 Defender로 전송              |
    | `autoCreateCases`           | 수집된 Defender 인시던트에서 케이스 자동 생성     |
    | `closeAlertsOnCaseClose`    | 케이스 종료 시 연결된 Defender **알림** 해결   |
    | `closeIncidentsOnCaseClose` | 케이스 종료 시 연결된 Defender **인시던트** 해결 |
  </Step>

  <Step title="연결 테스트">
    **연결 테스트**를 사용하여 검증합니다. CaseBender는 OAuth2 토큰을 요청하고
    `GET /security/alerts_v2?$top=1`을 호출합니다.

    <Note>
      테스트 중 `403` 응답은 **성공**으로 처리됩니다. 앱이 해당 특정 엔드포인트에 대한 읽기
      범위를 아직 부여받지 못한 경우에도 인증이 작동했음을 확인합니다.
    </Note>
  </Step>
</Steps>

## 인바운드: Defender 알림 및 인시던트 수집

### 엔드포인트

Defender(또는 Logic Apps, Sentinel, 웹훅 전달자와 같은 중개자)는 알림/인시던트 페이로드를
CaseBender 수집 엔드포인트로 전송합니다:

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

요청은 `x-api-key` 헤더의 통합 **API 키**로 인증됩니다(`authorization: Bearer <key>` 헤더도
허용됨). Defender 웹훅 API 키에는 `sk_def_` 접두사가 붙습니다.

### 페이로드 형식

**배치** 형식(Graph `value[]` 배열)과 **단일 알림** 개체가 모두 지원됩니다.

<CodeGroup>
  ```bash 배치 (Graph value[]) theme={null}
  curl -X POST "https://<your-casebender-domain>/api/v1/ingest/defender" \
    -H "x-api-key: sk_def_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "value": [
        {
          "id": "da637...",
          "incidentId": "12345",
          "title": "의심스러운 PowerShell 실행",
          "severity": "high",
          "status": "new",
          "classification": "unknown",
          "createdDateTime": "2026-07-03T18:20:00Z",
          "mitreTechniques": ["T1059.001"],
          "evidence": [
            { "@odata.type": "#microsoft.graph.security.fileEvidence",
              "sha256": "9f2b...", "fileName": "payload.ps1" }
          ]
        }
      ]
    }'
  ```

  ```bash 단일 알림 theme={null}
  curl -X POST "https://<your-casebender-domain>/api/v1/ingest/defender" \
    -H "x-api-key: sk_def_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "da637...",
      "title": "엔드포인트에서 맬웨어 탐지됨",
      "severity": "medium",
      "status": "new",
      "createdDateTime": "2026-07-03T18:20:00Z"
    }'
  ```
</CodeGroup>

성공한 요청은 HTTP `202 Accepted`를 반환합니다:

```json theme={null}
{ "success": true, "processed": 1, "failed": 0 }
```

### 처리 파이프라인

<Steps>
  <Step title="수집 프록시">
    `/api/v1/ingest/defender`는 소스를 검증하고 요청을 수집 서비스
    (`POST /v1/sources/defender`)로 전달합니다.
  </Step>

  <Step title="큐 게시">
    수집 서비스는 API 키를 인증하고 페이로드를 검증한 후 각 알림을 처리 큐에 게시합니다.
  </Step>

  <Step title="정규화">
    Defender 프로세서는 각 레코드를 CaseBender 알림으로 정규화합니다. 심각도 매핑, 제목/설명
    구성, 관찰 가능 항목 및 디바이스 자산 추출, MITRE TTP 생성을 수행합니다.
  </Step>
</Steps>

### 데이터 매핑 참조

**심각도 매핑**(Defender → CaseBender 1–4):

| Defender 심각도    | CaseBender 심각도 |
| --------------- | -------------- |
| `high`          | 1              |
| `medium`        | 2              |
| `low`           | 3              |
| `informational` | 4              |
| `unknown`       | 3              |

**관찰 가능 항목 추출**(`evidence[]`에서):

| 증거 필드           | 관찰 가능 항목 유형              |
| --------------- | ------------------------ |
| `ipAddress`     | `ip`                     |
| `url`           | `url`                    |
| `sha256`        | `hash`                   |
| `fileName`      | `filename`               |
| `deviceDnsName` | `hostname`               |
| `userAccount`   | `user`(`DOMAIN\account`) |

수집 시 적용되는 태그에는 `defender`, `xdr`, `service:<serviceSource>`,
`category:<category>`, `incident`(인시던트의 경우), 그리고 각 MITRE 기법당 하나의
`mitre:<technique>` 태그가 포함됩니다. 수집된 레코드는 기본적으로 **TLP:2** 및 **PAP:2**를
사용합니다.

## 아웃바운드: 케이스 처리 결과를 Defender로 동기화

CaseBender에서 케이스가 종료되면 `case_closed` 이벤트가 Defender 핸들러로 디스패치됩니다.
케이스가 Defender 알림 또는 인시던트에 연결되어 있으면 CaseBender는 Graph 보안 API를 통해
해결 결과를 전송합니다.

### 연결된 Defender 엔터티가 해결되는 방식

핸들러는 다음 순서로 Defender 식별자를 찾습니다:

1. `extraData.defenderAlertId` / `extraData.defenderIncidentId`
2. `extraData.source === "defender"`일 때 `sourceRef`
3. Defender 알림 참조처럼 보일 때 `sourceRef`(접두사 `da`)

알림 또는 인시던트 ID를 찾을 수 없으면 이 통합에서 케이스 종료를 건너뜁니다.

### 해결 → 분류 매핑

| CaseBender 해결   | Defender 분류                     |
| --------------- | ------------------------------- |
| `TruePositive`  | `truePositive`                  |
| `FalsePositive` | `falsePositive`                 |
| `Duplicate`     | `informationalExpectedActivity` |
| `NoImpact`      | `informationalExpectedActivity` |
| *(기타 / 없음)*     | `truePositive`(기본값)             |

종료 시 CaseBender는 알림/인시던트 `status`를 `resolved`로 설정하고, 매핑된 `classification`을
적용하며, 다음과 같은 코멘트를 추가합니다:

```
Case <case-id> closed in CaseBender with resolution: <resolution>
```

<Note>
  아웃바운드 알림 업데이트에는 `closeAlertsOnCaseClose`가 활성화되어야 하며, 인시던트
  업데이트에는 `closeIncidentsOnCaseClose`가 필요합니다. 둘 다 활성화되지 않으면 아웃바운드
  동기화가 발생하지 않습니다.
</Note>

## 보안 고려 사항

* **비밀 처리** — 클라이언트 비밀은 통합 설정에 저장됩니다. 조직에서 요구하는 일정에 따라
  교체하고 교체 시 통합을 업데이트하십시오.
* **최소 권한** — `SecurityAlert.ReadWrite.All` 및 `SecurityIncident.ReadWrite.All`만
  부여하십시오. 더 광범위한 Graph 범위를 추가하지 마십시오.
* **토큰 캐싱** — 액세스 토큰은 통합별로 메모리에 캐시되고 만료 1분 전에 갱신됩니다. 토큰은
  디스크에 유지되지 않습니다.
* **웹훅 키** — `sk_def_` API 키를 비밀로 취급하십시오. 노출되면 교체하고 발신자 구성을
  업데이트하십시오.
* **네트워크** — 송신을 `login.microsoftonline.com` 및 `graph.microsoft.com`으로 제한하십시오.

## 문제 해결

<AccordionGroup>
  <Accordion title="연결 테스트가 OAuth2 오류로 실패함">
    `tenantId`, `clientId`, `clientSecret`을 확인하십시오. 클라이언트 비밀이 만료되지 않았고
    Graph 애플리케이션 권한에 대해 관리자 동의가 부여되었는지 확인하십시오.
  </Accordion>

  <Accordion title="수집이 401 Unauthorized를 반환함">
    `x-api-key` 헤더가 없거나 유효하지 않습니다. 통합의 구성된 웹훅 API 키와 일치하는
    `sk_def_` 키를 보내고 있는지 확인하십시오.
  </Accordion>

  <Accordion title="수집이 400 'No alerts in payload'를 반환함">
    페이로드에 `value[]` 배열이나 최상위 `id`가 없습니다. Graph 배치 개체 또는 단일 알림 개체를
    보내십시오.
  </Accordion>

  <Accordion title="케이스 종료가 Defender를 업데이트하지 않음">
    `closeAlertsOnCaseClose` / `closeIncidentsOnCaseClose`가 활성화되어 있고 케이스에 Defender
    알림/인시던트 ID(`extraData` 또는 `sourceRef`를 통해)가 있는지 확인하십시오.
  </Accordion>

  <Accordion title="아웃바운드 업데이트가 403을 반환함">
    Azure AD 앱에 쓰기 권한이 없습니다. `SecurityAlert.ReadWrite.All` 및
    `SecurityIncident.ReadWrite.All`이 관리자 동의와 함께 부여되었는지 확인하십시오.
  </Accordion>
</AccordionGroup>

## 관련 문서

* [통합 개요](./introduction.mdx)
* [Microsoft Graph 보안 API](https://learn.microsoft.com/ko-kr/graph/api/resources/security-api-overview)
* [Microsoft Defender XDR](https://learn.microsoft.com/ko-kr/defender-xdr/)