> ## 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、Webhook フォワーダーなどの仲介) は、アラート/インシデント
ペイロードを CaseBender の取り込みエンドポイントに送信します:

```
POST https://<あなたの-casebender-ドメイン>/api/v1/ingest/defender
```

リクエストは `x-api-key` ヘッダーの統合 **API キー**で認証されます
(`authorization: Bearer <キー>` ヘッダーも受け入れられます)。Defender の Webhook API キーには
`sk_def_` プレフィックスが付きます。

### ペイロード形式

**バッチ**形式 (Graph の `value[]` 配列) と**単一アラート**オブジェクトの両方がサポートされます。

<CodeGroup>
  ```bash バッチ (Graph の value[]) theme={null}
  curl -X POST "https://<あなたの-casebender-ドメイン>/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://<あなたの-casebender-ドメイン>/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 テクニックごとに 1 つの
`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 <ケース ID> closed in CaseBender with resolution: <解決>
```

<Note>
  アウトバウンドのアラート更新には `closeAlertsOnCaseClose` の有効化が必要です。インシデント
  更新には `closeIncidentsOnCaseClose` が必要です。どちらも有効になっていない場合、アウトバウンド
  同期は行われません。
</Note>

## セキュリティに関する考慮事項

* **シークレットの取り扱い** — クライアントシークレットは統合設定に保存されます。組織が要求する
  スケジュールでローテーションし、その際に統合を更新してください。
* **最小権限** — `SecurityAlert.ReadWrite.All` と `SecurityIncident.ReadWrite.All` のみを付与し
  ます。より広範な Graph スコープを追加しないでください。
* **トークンキャッシュ** — アクセストークンは統合ごとにメモリ内にキャッシュされ、有効期限の
  1 分前に更新されます。トークンはディスクに永続化されません。
* **Webhook キー** — `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` ヘッダーが欠落しているか無効です。統合の構成済み Webhook 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/ja-jp/graph/api/resources/security-api-overview)
* [Microsoft Defender XDR](https://learn.microsoft.com/ja-jp/defender-xdr/)