# ホワイトボックス診断（都度）

## 概要

Takumi ホワイトボックス診断機能は、GitHub リポジトリ連携またはファイルアップロードでソースコードを受け取り、Takumi が診断を行い、結果を Web 上でレポートとして出力する機能です。

Shisho Cloud byGMO の Web 画面から利用できます。[ホワイトボックス診断（定期）](/docs/ja/t/features/periodic-assessment.md)とは異なり、Slack 連携は不要です。

## チャット経由のホワイトボックス診断との違い

本機能と、Slack や Web チャット経由で利用できるホワイトボックス診断では、**動作する Takumi エンジンが異なります。**

| 項目           | チャット経由 | Web コンソール経由 |
| -------------- | ------------ | ------------------ |
| 網羅性         | 従来通り     | **より網羅的**     |
| 診断時間       | 従来通り     | **増加傾向**       |
| クレジット消費 | 従来通り     | **増加傾向**       |

## クレジット消費に関して {#credits}

利用にはクレジットが必要です。クレジット消費量は、診断対象の特性やサイズに応じて変動します。

診断開始時に、機能列挙フェーズとスキャンフェーズそれぞれにクレジット上限を設定できます。各フェーズの消費量が指定した上限を超えることはありません。

## 診断の開始方法

サイドバーの「診断」をクリックすると表示される画面において、画面右上の「診断を作成」ボタンを押すと診断が開始できます。

![診断開始の UI](/docs/ja/_md-assets/e177f1fe7d-ui-whole.png)

### 基本設定

- 「診断名」には、この診断を識別するための名前を入力します。
- 「レポート言語」には、診断レポートの言語を選択します（英語または日本語）。
- 「診断対象」は「ソースコード」を選択します。

### 診断タイプ

診断開始時に、以下の 2 つのモードから選択できます。

- 「**全体を診断**」モード: 対象ソースコードの機能列挙・初回スキャンが一気通貫で行われ、完了後に「診断再開待ち」状態で停止します。以降の手順は「[診断結果の確認と追加スキャン](#診断結果の確認と追加スキャン)」を確認してください。
- 「**一部だけ診断**」モード: 最初に診断対象のコードベースから「機能」を列挙し、完了すると列挙された機能が表示されます。表示された機能から診断対象や診断の優先度を決定して、診断を開始できます。

### クレジット上限

クレジット上限は、機能列挙およびスキャンのそれぞれについて設定することが可能です（「一部だけ診断」モードの場合は機能列挙のみ）。Takumi は指定されたクレジット上限の範囲内で機能列挙およびスキャンを実施します。

### ソースコード設定

以下のいずれかの方法でソースコードを提供できます。

#### GitHub リポジトリ

GitHub リポジトリを1つ以上指定できます。「リポジトリを追加」ボタンから診断対象のリポジトリを追加します。

対象リポジトリのブランチを指定することができます。指定しない場合は、リポジトリのデフォルトブランチが診断対象となります。

#### ファイルアップロード

ソースコードのアーカイブファイルを直接アップロードできます。GitHub 連携が利用できない場合や、ローカルのコードベースを診断する場合に便利です。

- **対応フォーマット**：`.zip` または `.tar.gz`
- 「ファイルをアップロード」ボタンからアーカイブを選択してアップロードします
- 展開後のルートディレクトリが表示されます。後述のファイルスコープの指定の際に使用されます。

### ファイルスコープ

診断対象に含めるファイルパスと除外するファイルパスを指定できます。すべてのファイルパスには glob パターン（例：`src/auth/**`、`backend/services/**`）を使用できます。スコープを空にした場合、コードベース全体が診断対象となります。

#### 診断範囲

- 「対象」には、対象となるリポジトリまたはアップロードしたファイルを選択します
- 「機能タイプ」（オプション）には、機能のカテゴリを指定します（例：`authentication`、`payments`、`api`）
- 「ファイルパス」には、診断対象に含めるファイルパスを指定します

診断対象として指定された場合でも、Takumi の判断によりファイルパスが除外される場合があります。

#### 除外設定

- 「対象」には、対象となるリポジトリまたはアップロードしたファイルを選択します
- 「理由」（オプション）には、除外する理由を記録します（例：「テストコード」「自動生成ファイル」）
- 「ファイルパス」には、除外するファイルパスを指定します

## 機能列挙結果の確認

「一部だけ診断」モードで機能の列挙が完了すると、検出された機能と診断観点の一覧がマトリクス形式で表示されます。この画面において、スキャンに使用するクレジットの上限と各機能・観点ごとの診断優先度を設定することができます。

![診断設定の UI](/docs/ja/_md-assets/1eb0248a14-ui-pending-1.png)

設定後、「診断を開始」ボタンを押すと、実際にスキャンが開始されます。

## 診断結果の確認と追加スキャン

スキャン中に指定されたクレジット上限に達するか、すべての組み合わせに対するスキャンが完了すると、診断は「診断再開待ち」の状態で一時停止します。

「診断再開待ち」の診断を開くと、以下のようなページが表示されます。

![診断設定の UI](/docs/ja/_md-assets/3645820a73-ui-pending-2.png)

このページからは、以下の操作が可能です。

- **中間レポートのプレビュー**: 「レポートをプレビュー」をクリックすると、現時点のレポートを別タブで確認できます。診断を継続するか完了するかの判断材料として活用することができます
- **追加スキャンの実行**: クレジット上限および未診断の組み合わせに対する優先度を設定し、「診断を開始」をクリックして追加のスキャンを実行できます
- **診断の完了**: 追加スキャンが不要な場合、「診断を完了する」ボタンをクリックして診断を完了できます

### 診断を完了させる

「診断を完了する」をクリックすると、診断結果のレポートが表示されるページに遷移します。

### 診断結果を確認する

診断レポートは、以下の画面のように、Web 上で閲覧いただけます。

![診断結果の UI](/docs/ja/_md-assets/936c555fb9-ui-result-1.png)

レポートには、まず、診断結果の概要やサマリーが記載されています。

![診断結果の UI](/docs/ja/_md-assets/2dea2812a3-ui-result-2.png)

診断結果の各項目では、どの機能を、どのような観点で診断した結果、どのような深刻度・リスクの脆弱性があったかが説明されています。脆弱性が検出されたファイルパス等も含まれています。

![診断結果の UI](/docs/ja/_md-assets/7130ba0435-ui-result-3.png)

## 診断観点

ホワイトボックス診断では、以下の観点からレビューを行います。なお、対象リポジトリの特性に応じて、実際に診断を行う観点や優先度を別途指定することも可能です。

**機能単位の診断**

- インジェクション
- ファイル操作不備
- XSS
- 認可制御の不備
- ロジックの不備

**リポジトリ単位の診断**

- 設定不備
- 認証の不備

インジェクションや XSS などの脆弱性は、診断の網羅性を担保するため、Takumi が事前に特定した「各機能ごと」に検査を実行します。一方、設定不備や認証の不備など、機能ごとに分散せず特定の箇所（設定ファイルやミドルウェア層など）に問題が存在することの多い観点は、対象全体に対して一度だけ実行されます。

それぞれの詳細については、後述の「[OWASP ASVS 5.0 への準拠](#asvs)」をご覧ください。

### ブラックボックス診断との違い

ホワイトボックス診断の観点は、静的解析の特性を最大限に活かすため、ブラックボックス診断とは異なる構成をとっています。

例えばブラックボックス診断では、SSRF やコマンドインジェクションなどをそれぞれ異なるリクエストやペイロードで検査するため、観点を細分化することに意味があります。一方、ソースコードを直接解析するホワイトボックス診断では、これらを「外部入力から危険な処理への到達（taint tracking）」という共通のメカニズムで一括して追跡できます。そのため、本診断ではこれらを「インジェクション」という一つの観点に統合し、コードの重複走査を防ぎながら効率的かつ網羅的なレビューを実現しています。

### OWASP ASVS 5.0 への準拠 {#asvs}

ホワイトボックス診断では、深刻度の高い脆弱性の検出に加え、国際的な基準である OWASP ASVS 5.0 に基づいた網羅的な検査を実施します。

本診断観点と OWASP ASVS 5.0 Level 1 チェック項目の対応表は以下の通りです。

| 診断観点         | ASVS チェック項目                                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| インジェクション | V1.2.4, V1.2.5, V1.3.2, V1.5.1                                                                                                        |
| ファイル操作不備 | V5.2.1, V5.2.2, V5.3.1, V5.3.2                                                                                                        |
| XSS              | V1.2.1, V1.2.2, V1.2.3, V1.3.1, V4.1.1                                                                                                |
| 認可制御の不備   | V8.2.1, V8.2.2, V8.3.1                                                                                                                |
| ロジックの不備   | V2.3.1                                                                                                                                |
| 設定不備         | V3.4.1, V3.4.2, V3.5.2, V4.4.1, V11.3.1, V11.3.2, V11.4.1                                                                             |
| 認証の不備       | V3.3.1, V6.2.1–V6.2.8, V6.3.1, V6.3.2, V6.4.1, V6.4.2, V7.2.1–V7.2.4, V7.4.1, V7.4.2, V9.1.1–V9.1.3, V9.2.1, V10.4.1–V10.4.5, V14.3.1 |

ただし、ホワイトボックス診断では、以下の理由により一部の項目はチェック項目から除外しています。

- **実質的にカバーされるため省略している項目**

  - より具体性の高い他の項目の検査を通じて要件が満たされているか確認できるため、独立した項目としては省略しています
  - 該当項目： V2.2.1, V2.2.2, V3.2.1, V3.2.2, V14.2.1, V15.3.1

- **静的解析の対象外となるため省略している項目**

  - ホワイトボックス診断（静的解析）の特性上、ソースコードからの判定が困難であるか、または適さないインフラ・運用面の項目を省略しています
  - 該当項目： V2.1.1, V6.1.1, V8.1.1, V12.1.1, V12.2.1, V12.2.2, V15.1.1, V15.2.1

- **将来的に対応予定の項目**
  - 今後のアップデートにより順次対応を予定している項目です
  - 該当項目： V3.5.1, V3.5.3, V13.4.1