# グレーボックス診断 ## 概要 Takumi グレーボックス診断機能は、アプリケーションのソースコードと、そのソースコードが稼働しているアプリケーションのURLの両方を受け取る診断機能です。ソースコードの解析によって脆弱性の候補を洗い出し、稼働中のアプリケーションに対して実際に攻撃を行って再現の可否を確認し、その結果を Web 上でレポートとして出力します。 Shisho Cloud byGMO の Web 画面から利用できます。 動的検証で再現が確認できたものだけが指摘事項として報告されます。静的解析が指摘した脆弱性の候補のうち再現が確認できなかったものは、レポート内の別のセクションに記録されるため、再現が確認できた脆弱性と確認できなかった脆弱性を区別して読むことができます。詳細は [レポートの読み方](#report-structure) をご覧ください。 ## 組織または診断対象の所有権証明 グレーボックス診断は稼働中のアプリケーションに対してリクエストを送信するため、診断を開始する前に、組織認証あるいは診断対象の所有権証明が必要になります。詳細は「[診断前の組織認証あるいは所有権証明](/docs/ja/t/assessment/features/assessment-authentication.md)」を参照ください。 ## 診断の開始方法 サイドバーの「診断」をクリックすると表示される画面において、画面右上の「診断を作成」ボタンを押すと診断が開始できます。 ![診断開始の UI](/docs/ja/_md-assets/aca0f31d96-start.png) ### 基本設定 設定画面の主な項目は以下のとおりです。 - 「診断名」：この診断を識別するための名前を入力する - 「レポート言語」：診断レポートの言語を選択する（英語または日本語） - 「診断手法」：「グレーボックス診断」を選択する ### 診断タイプ 診断開始時に、以下の 2 つのモードから選択できます。 - 「**全体を診断**」モード：対象ソースコードの機能列挙・初回スキャンを一気通貫で実行し、完了後に「診断再開待ち」状態で停止する。以降の手順は [診断結果の確認と追加スキャン](#診断結果の確認と追加スキャン) を確認する - 「**一部だけ診断**」モード：最初に診断対象のコードベースから「機能」を列挙し、完了すると列挙された機能が表示される。表示された機能から診断対象や診断の優先度を決定して、診断を開始する ### クレジット上限 クレジット上限は、機能列挙およびスキャンのそれぞれについて設定することが可能です（「一部だけ診断」モードの場合は機能列挙のみ）。Takumi は指定されたクレジット上限の範囲内で機能列挙およびスキャンを実施します。 スキャンのクレジット上限は最小 40 クレジットであり、ホワイトボックス診断よりも大きい値が必要です。グレーボックス診断では、この上限を静的解析と、その後に続く動的検証との間で分け合うためです。 ### ソースコード設定 以下のいずれかの方法でソースコードを提供できます。 #### GitHub リポジトリ GitHub リポジトリを1つ以上指定できます。「リポジトリを追加」ボタンから診断対象のリポジトリを追加します。 対象リポジトリのブランチを指定することができます。指定しない場合は、リポジトリのデフォルトブランチが診断対象となります。 #### ファイルアップロード ソースコードのアーカイブファイルを直接アップロードできます。GitHub 連携が利用できない場合や、ローカルのコードベースを診断する場合に便利です。 - **対応フォーマット**：`.zip` または `.tar.gz` - 「ファイルをアップロード」ボタンからアーカイブを選択してアップロードする - 展開後のルートディレクトリが表示され、後述のファイルスコープの指定で使用される ### ファイルスコープ 診断対象に含めるファイルパスと除外するファイルパスを指定できます。すべてのファイルパスには glob パターン（例：`src/auth/**`、`backend/services/**`）を使用できます。スコープを空にした場合、コードベース全体が診断対象となります。 #### 診断範囲 - 「対象」：対象となるリポジトリまたはアップロードしたファイルを選択する - 「機能タイプ」（オプション）：機能のカテゴリを指定する（例：`authentication`、`payments`、`api`） - 「ファイルパス」：診断対象に含めるファイルパスを指定する 診断対象として指定された場合でも、Takumi の判断によりファイルパスが除外される場合があります。 #### 除外設定 - 「対象」：対象となるリポジトリまたはアップロードしたファイルを選択する - 「理由」（オプション）：除外する理由を記録する（例：「テストコード」「自動生成ファイル」） - 「ファイルパス」：除外するファイルパスを指定する ### アプリケーション設定 動的検証の対象となる、稼働中のアプリケーションに関する設定です。 - 「対象URL」：診断対象に指定したソースコードが稼働しているアプリケーションの URL を入力する。1つのソースコードが複数のオリジンで稼働している場合（例：Web フロントエンドとその API が別ホストで動作している場合）は、複数指定できる - 「スコープ外URL」：動的検証において検証対象から除外する URL を指定する - 「アプリケーション内の認証」：アプリケーションにログインするための認証情報を設定する。ID とパスワードを入力するほか、「その他」を選択して認証手順を自由記述で説明することもできる。「アカウント種別」（例：管理者、一般ユーザー）には、その認証情報がどの権限を持つものかを記入する :::info スコープ外 URL は、動的検証が何を検証対象として扱うかを判定するために使われます。そのため、スコープ外の URL であっても、診断の過程で Takumi が実際にアクセスすること自体はあり得ます。この設定は、こうしたアクセスを完全に遮断するものではない点にご注意ください。 ::: ## 機能列挙結果の確認 「一部だけ診断」モードで機能の列挙が完了すると、検出された機能と診断観点の一覧がマトリクス形式で表示されます。この画面において、スキャンに使用するクレジットの上限と各機能・観点ごとの診断優先度を設定することができます。 機能と観点の組み合わせごとに「おまかせ・高・中・低・なし」の優先度を設定でき、優先度の高いものから順に診断されます。「おまかせ」を選択した場合は、Takumi がリスク分析に基づいて優先度を自動的に決定します。 設定後、「診断を開始」ボタンを押すと、実際にスキャンが開始されます。 ## 診断結果の確認と追加スキャン スキャン中に指定されたクレジット上限に達するか、すべての組み合わせに対するスキャンが完了すると、診断は「診断再開待ち」の状態で一時停止します。 「診断再開待ち」の診断を開くと、マトリクス画面が再度表示されます。 この画面からは、以下の操作が可能です。 - **中間レポートのプレビュー**：「レポートをプレビュー」をクリックすると、現時点のレポートを別タブで確認できる。診断を継続するか完了するかの判断材料に使える - **追加スキャンの実行**：クレジット上限および未診断の組み合わせに対する優先度を設定し、「診断を開始」をクリックして追加のスキャンを実行する - **診断の完了**：追加スキャンが不要な場合、「診断を完了する」ボタンをクリックして診断を完了する ### 診断を完了させる 「診断を完了する」をクリックすると、診断結果のレポートが表示されるページに遷移します。 ### 診断結果を確認する 診断レポートは Web 上で閲覧いただけます。診断結果の各項目では、どの機能を、どのような観点で診断した結果、どのような深刻度・リスクの脆弱性があったか、そして動的検証によってそれをどのように確認したかが説明されています。 ### PDF レポートのエクスポート {#pdf-report} 診断レポートを PDF としてダウンロードできます。診断レポートページの **「PDFレポートを発行」** ボタンから、表紙の言語（英語または日本語）を選んで発行します。発行が完了すると、ログイン中のアカウントに紐づいたメールアドレスに対して、ダウンロードリンクが送付されます。 ダウンロードリンクの有効期限は 15 分ですが、再度ダウンロードボタンをクリックすることで新しいリンクを取得できます。発行した PDF は 30 日後に削除されるため、必要に応じて保存してください。 ## 診断観点 グレーボックス診断における静的解析は、[ホワイトボックス診断](/docs/ja/t/assessment/features/whitebox-assessment.md#診断観点)と同じ観点でコードをレビューします。 **機能単位の診断** - インジェクション - ファイル操作不備 - XSS - 認可制御の不備 - ロジックの不備 **リポジトリ単位の診断** - 設定不備 - 認証の不備 インジェクションや XSS などの脆弱性は、診断の網羅性を担保するため、Takumi が事前に特定した「各機能ごと」に検査を実行します。一方、設定不備や認証の不備など、機能ごとに分散せず特定の箇所（設定ファイルやミドルウェア層など）に問題が存在することの多い観点は、対象全体に対して一度だけ実行されます。 これらの観点から挙げられた脆弱性の候補は、稼働中のアプリケーションに対する攻撃によって検証され、再現できたものだけが指摘事項として報告されます。再現できるかどうかは稼働中のアプリケーションの状態に依存するため、静的解析の指摘そのものが正しくても再現に至らない場合があります。たとえば、該当の機能が、設定した認証情報では到達できないデータや権限を必要とする場合が挙げられます。 各観点と OWASP ASVS 5.0 との対応については、[OWASP ASVS 5.0 への準拠](/docs/ja/t/assessment/features/whitebox-assessment.md#asvs) をご覧ください。 ## レポートの読み方 {#report-structure} レポートは、動的検証によって何が確認できたかを軸に構成されています。 - 「**解析対象機能一覧**」には、静的解析が検査した機能が記載されます。診断がどの範囲をカバーしたかを確認できます - 「**指摘事項一覧**」には、動的検証で再現が確認できた脆弱性が記載されます。各指摘事項には、検証によって何が確認できたかを述べる「検証結果」と、そのために実際に行った操作を示す「再現手順」が含まれます。再現手順は、読み手が同じ手順をたどって脆弱性を確認できる粒度で記述されます - 「**再現が確認できなかった事項**」には、静的解析が挙げた脆弱性の候補のうち、動的検証では再現が確認できなかったものが記載されます。再現していないため、このセクションに再現手順は含まれません ## クレジット消費に関して {#credits} 利用にはクレジットが必要です。クレジット消費量は、診断対象の特性やサイズに応じて変動します。 おおよその目安として、ある「機能・観点」の組み合わせ（設定画面での特定のセルに該当）に対して、**5〜8 クレジット**程度が消費されます。ただし、実際の消費量は対象の機能の規模や、診断中に Takumi が発見した手がかりの数等によっても変動するため、上記の範囲に収まらない場合もあります。 診断開始時に、機能列挙フェーズとスキャンフェーズそれぞれにクレジット上限を設定できます。各フェーズの消費量が指定した上限を超えることはありません。 なお、診断の実行中は、指定したクレジット上限分があらかじめ残高から確保されるため、表示されるクレジット残高は確保分を差し引いた値となります。詳細は [診断実行中のクレジット確保](/docs/ja/t/assessment/billing/pricing.md#credit-reservation) を参照してください。