# 自動トリアージ {#auto-triage}

## 機能概要 {#overview}

「Takumi」は Slack や WebUI を通じて手動で仕事を依頼できるだけでなく、イベント駆動でレビューを行う機能も提供しています。

Takumi は開発ワークフローのイベントを監視し、セキュリティ上のリスクを含む可能性のあるプルリクエストを自動的にトリアージします。手動レビューの負担を軽減し、本当に対処すべき問題にチームが集中できるようにします。

現在は **Dependabot 自動トリアージ** に対応しています。Dependabot が作成したプルリクエストを自動で精査し、セキュリティ的な観点から安全かどうかを判断します。

## 設計思想 {#design-philosophy}

本機能は「脆弱性を見逃さない」ことを最優先に開発されています。そのため、安全な更新についても「問題がある可能性がある」と報告する場合があります。

理由として、重大な脆弱性の見逃しはセキュリティインシデントに直結する可能性を高め、その対応コストは誤検知を確認するコストを大幅に上回るためです。

Takumi の分析は、公開されている脆弱性情報と、お客様のソースコードを読み解くホワイトボックス検証などを組み合わせた独自のアプローチに基づいています。

しかしながら、このアプローチには制約も存在します。例として、公開されている情報は時として、脆弱性の具体的な説明が乏しい場合や、その脆弱性を再現する方法などが不足している場合があります。

このような制約があるからこそ、Takumi は偽陰性（実際の脅威の見逃し）を最小限に抑えることに注力しています。言い換えると、偽陽性を許容していると言えます。

その結果、偽陽性（ノイズとなりうる場合）を許容している側面もありますが、**より精度の高い分析を実現するため、日々継続的な研究開発に取り組んでいます。**

## Dependabot 自動トリアージ {#dependabot}

GitHub で Dependabot が有効化されている場合に、Dependabot が作成したプルリクエスト（PR）を自動で精査し、セキュリティ的な観点から安全かどうかを判断します。

継続的な依存関係の更新はセキュリティの向上に役立ちますが、大量に生成された PR を一つ一つ手動で確認し、セキュリティリスクがないかを分析することは大きな負担となります。Takumi は、人間の代わりに自動的かつ迅速にセキュリティ分析を行い、リスクを検知・判断することで、この課題を解決します。

### 実行フロー {#dependabot-execution-flow}

Dependabot が PR を作成すると、Takumi は以下のステップを自動的に実行します。

- **PR の監視** として、GitHub で Dependabot が PR を作成すると、Takumi がこれを検知し、即座に分析を開始する
- **分析の実行** として、PR 内の依存関係について以下の分析を行う
  - **セキュリティに関連するか判断（フェーズ 1）** では、PR の内容がセキュリティ分析の対象であるかどうかを判断する。セキュリティとは関係のない更新と判断した場合は、その時点で分析を中断し、不必要なクレジットの消費を防ぐ
  - **既知の脆弱性の特定（フェーズ 2）** では、ライブラリに CVE や GHSA といった主要なデータベースに登録されている脆弱性がないかを確認する
  - **コードベースにおける悪用可能性の分析（フェーズ 3）** では、脆弱性がお客様のコードベースで実際に悪用可能かどうかを分析・判断する
- **リスクの評価** として、脆弱性の深刻度と悪用可能性を総合的に評価し、セキュリティリスクを判断する
- **分析結果の通知** として、分析結果はワークプレイスの Web ダッシュボードで確認できる。Slack 連携を利用している場合は、Slack にも直接投稿される。重大かつ悪用可能な脆弱性が発見された場合は、Slack チャンネル全体へ即座に通知し、迅速な対応を促す

### 使用方法 {#dependabot-how-to-use}

Dependabot 自動トリアージ機能の利用方法には、ワークプレイス（Web コンソール）からの利用と、Slack からの利用の 2 つがあります。

#### ワークプレイスから利用する {#workplace}

**ワークプレイス**は GitHub リポジトリをグループ化するための単位です。チーム、プロジェクトなど任意の基準でリポジトリをまとめ、Slack 連携なしで Web コンソールから直接 Dependabot トリアージを管理できます。

##### 設定手順

1. サイドバーナビゲーションの**ワークプレイス**をクリックしてください
2. 新しいワークプレイスを作成し、対象の GitHub リポジトリを選択してください
3. ワークプレイスの設定から **Dependabot 自動トリアージ**を有効化してください
4. 応答言語（日本語または英語）を設定してください

登録したリポジトリで Dependabot が PR を作成すると、ワークプレイスの **Dependabot** タブにトリアージ結果が表示されます。

#### Slack から利用する {#slack}

Slack 経由で本機能を利用するには、外部連携（GitHub）と Takumi の設定を完了している必要があります。詳細は以下のページをご参照ください。

- [外部連携を設定する](/docs/ja/g/getting-started/integrate-apps/github.md)
- [Takumi を Slack に招待する](/docs/ja/t/getting-started/index.md)
- [Slack チャンネル毎のデータスコープの設定](/docs/ja/t/features/chat-interface/slack-configs.md#1-takumi-scopesでのアクセス可能なコードベースの管理)

上記の設定が完了していることを確認してください。その後、以下の画面のようにダッシュボードから、対象の Slack チャンネルで **「Dependabot のトリアージ」** を有効化してください。

![Dependabot トリアージの有効化](/docs/ja/_md-assets/0bbccb6373-config.png)

この時、レビュー結果の表示言語として、日本語または英語を選択してください。

以上で設定は完了です。これより、Dependabot が PR を作成すると、以下のようなメッセージが該当チャンネルに送信されます。

![初回メッセージ](/docs/ja/_md-assets/c9b2a55ad7-initial-message.png)

レビュー結果は最終的にスレッド内に送信されます。以下は、レビュー対象の PR がセキュリティ関連ではないと判断された場合のメッセージ例です。

![IRRELEVANT の結果](/docs/ja/_md-assets/7f5031e2df-result-irrelevant.png)

以下は、レビュー対象の PR が特定の脆弱性に関連し、悪用可能と判断された場合のメッセージ例です。

![CRITICAL の結果](/docs/ja/_md-assets/e89d04cefc-result-critical.png)

### レビュー結果 {#dependabot-review-results}

セキュリティへの影響度に基づいて、PR を内部的に 4 段階で分類します。この評価は、次に取るべき対応を判断するのに役立ちます。

以下に、分類ごとの詳細と推奨される対応を説明します。

- **SECURITY_CRITICAL**
  - 重大または高深刻度の脆弱性であり、高リスクと判断され、かつ実際にコードベースで悪用可能と判断されたもの
  - チャンネルに緊急対応が必要であることを通知し、即座のレビューとパッチ適用を強く推奨する
- **SECURITY_HIGH**
  - 高リスクと判断された、重大・高深刻度の脆弱性だが、現時点のコードベースでは悪用可能ではないもの
  - メッセージはスレッド内に投稿される。即座の対応は不要だが、速やかなレビューを推奨する
- **SECURITY_MODERATE**
  - 中程度のリスクと判断された、中・低深刻度の脆弱性
  - メッセージはスレッド内に投稿され、必要に応じたレビューを推奨する
- **IRRELEVANT**
  - 最終的な分類が「セキュリティに関連しない」と判断されたもの
  - メッセージはスレッド内に投稿される。通常のメンテナンス更新として対応することを推奨する

:::warning
悪用可能と判断された重大な脆弱性の場合のみ、チャンネルにメッセージをブロードキャストします。
それ以外の場合、Takumi からの通知はスレッド内にのみ投稿されます。

これは、普段の業務に不要なノイズを生み出すことなく、対応が必須なセキュリティリスクにチームが迅速かつ確実に気づけるようにするためです。
:::

### PR の自動クローズ機能 {#dependabot-auto-close}

Takumi は分析結果を PR に直接コメントすることができます。加えて、最終的な分析結果に基づいて対象の PR を自動でクローズすることも可能です。
この機能により、効率的に PR を自動的に処理し、開発者の手動管理の負担を軽減します。

#### PR 処理モードの設定方法 {#pr-handling-mode}

Takumi は 3 つの PR 処理モード（保守的、バランス、積極的）を提供しています。各モードは、セキュリティリスクの評価結果に基づいて、どの PR を自動的にクローズするかを決定します。

##### GitHub 書き込み権限の設定

PR を自動的にクローズする機能を使用するには、現在連携中の GitHub App に加えて、新たに書き込み処理専用の GitHub App との連携が必要です。

書き込み処理専用の GitHub App を連携するには、以下の手順を実施してください。

1. 「設定」>「サービス連携」タブを開いてください
2. GitHub 連携の「書き込み権限を有効化」をクリックしてください
3. 既存の設定と同様に対象の GitHub 組織にインストールしてください

![書き込み権限の有効化](/docs/ja/_md-assets/2fc961d250-enable-write.png)

##### 処理モードの選択

PR 処理モードは、各 Slack チャンネルごとに設定できます。

1. ダッシュボードから本機能を有効化しているチャンネルの設定画面を開いてください
2. 「PR 処理モード」から、以下のいずれかを選択してください
   - **保守的モード**
   - **バランスモード**
   - **積極的モード**
3. 設定を保存してください

![処理モードの選択](/docs/ja/_md-assets/fac50478e9-choose-mode.png)

デフォルトでは **保守的モード** が設定されています。後述の説明を読んだ上で必要に応じて変更してください。

#### 各処理モードの違い {#mode-differences}

Takumi は 3 つの PR 処理モードを提供しています。チームの方針やセキュリティ要件に応じて、最適なモードを選択してください。

- **保守的モード** では、PR を一切自動クローズしない。Takumi は分析結果のコメントのみを投稿する
- **バランスモード** では、低リスクのセキュリティ更新（SECURITY_MODERATE）のみをクローズする
- **積極的モード** では、Takumi が悪用不可能と判断したセキュリティ更新（SECURITY_MODERATE、SECURITY_HIGH）をクローズする

以下の表は、各分類に対する各モードの動作をまとめたものです。

| 分類                  | 保守的モード | バランスモード | 積極的モード |
| --------------------- | ------------ | -------------- | ------------ |
| **IRRELEVANT**        | keep         | keep           | keep         |
| **SECURITY_MODERATE** | keep         | **close**      | **close**    |
| **SECURITY_HIGH**     | keep         | keep           | **close**    |
| **SECURITY_CRITICAL** | keep         | keep           | keep         |

:::info
どのモードを選択しても、以下の動作が保証されます。

- SECURITY_CRITICAL（悪用可能な脆弱性）は自動クローズされない
- IRRELEVANT（非セキュリティ更新）は自動クローズされない
- 分析コメントは全てのモードで投稿される
- 書き込み用 GitHub App を連携していない場合 PR への操作は行われない（PR へのコメントを含む）
  :::

### トリアージ精度 {#dependabot-accuracy}

当社では、公開されている複数の脆弱性情報に基づき、実際に攻撃が可能な状態（悪用可能な状態）を再現した複数のサンプルプログラムを独自に構築し、ベンチマークに使用しています。

#### データセットの概要

最新のベンチマークでは、Dependabot が作成した PR（合計 21 件）をデータセットとして使用しています。

このデータセットは、Takumi が「早急な対応が必要」と判断すべき PR（9 件）と、「リスクが低いもしくは無い」と判断すべき PR（12 件）で構成されています。

なお、「早急な対応が必要」な PR（9 件）には、Log4j に関する脆弱性や Next.js における認証バイパスなど、影響度が大きい脆弱性を修正するケース等が含まれています。

#### ベンチマーク結果

このデータセットに対し、Takumi のトリアージ精度は以下のとおりです。

| メトリクス      | 結果                     |
| --------------- | ------------------------ |
| **所要時間**    | **1.84 時間**            |
| **精度**        | **95.2 %**               |
| **真陽性 (TP)** | **100 %** (9 件) [\^1]   |
| **偽陰性 (FN)** | **0 %** (0 件) [\^1]     |
| **真陰性 (TN)** | **91.7 %** (11 件) [\^2] |
| **偽陽性 (FP)** | **8.3 %** (1 件) [\^2]   |

[\^1]: 「早急な対応が必要」の PR（9 件）が基準
[\^2]: 「リスクが低いもしくは無い」PR（12 件）が基準

ベンチマークの結果、Takumi はこのデータセットにおいて、以下の 2 点で優れた性能を持つと言えます。

#### 脆弱性を見逃さない

「早急な対応が必要」なケースでは偽陰性（見逃し）は 0 件でした。これは「設計思想」で言及している「脆弱性を見逃さない」という本機能の最優先事項を達成していることを示しています。

#### レビュー業務の大幅な削減

「リスクが低いもしくは無い」ケースでは 12 件のうち **11 件（91.7 %）** を正しく判別し、開発者のノイズになり得る件数を大幅に抑えています。

また工数削減効果を試算してみましょう。仮に、人間が手動でレビューする場合、単純な更新（12 件）に 10 分/件、脆弱性調査が必要な更新（9 件）に 30 分/件かかると仮定すると、推定される所要時間の合計は 6.5 時間に達します。

これに対し、Takumi は 1.84 時間で 21 件すべてのトリアージを完了しました。このデータセットにおいて、**Takumi は人間が手動で行う場合に比べてトリアージ工数を約 72 % 削減したと試算できます。**

### クレジット消費（推定コスト） {#dependabot-credit}

実際の利用データに基づく、各ケースの推定コストは以下のとおりです。

- **シンプルな更新（早期終了）** の場合は 0.01〜0.49 credits
  - セキュリティに関連しない変更など、フェーズ 1 で終了するケース
- **完全な詳細分析** の場合は 0.50〜1.00 credits
  - コードベースの調査を含む、全 3 フェーズの悪用可能性分析を実行するケース

:::warning
これらの値は概算であり、正確なコストを保証するものではありません。
実際のコストは、コードベースの複雑さや検出された脆弱性の数、その他の要因により変動します。
:::

Takumi の詳細な活用方法については、[Prompting Guide](/docs/ja/t/features/chat-interface/prompting-guide.md) をご確認ください。