# Web 診断を実行する

:::info
本チュートリアルで扱う機能は、Web アプリケーション診断機能をご契約いただいた組織でのみご利用いただけます。
:::

## セットアップ

Web 診断を実行する前に必要なセットアップは以下です:

1. Web アプリケーションの登録（[Web アプリケーションを登録する](/docs/ja/g/getting-started/register-web-applications/index.md)を参照してください）
1. 診断対象エンドポイントの登録（[診断対象エンドポイントを洗い出す](/docs/ja/g/getting-started/register-web-applications/collect-endpoints/index.md)を参照してください）
1. 診断対象の Web アプリケーションの所有権の証明

### Web アプリケーションの所有権の証明

Shisho Cloud では本診断機能の悪意のある利用を防止するため、Web 診断をご利用いただく際に診断対象であるアプリケーションの所有権の証明を必須としております。診断の実行前に Shisho Cloud が所有権の検証を行い、検証できなかった場合には診断は開始せず診断ジョブが終了します。検証の対象は登録されたエンドポイントのホストで、エンドポイントが複数のホストで成り立っている場合は各ホストが検証されます。

検証方法は２つあり、アプリケーションの全てのホストに対してどちらかが満たされた場合に所有権が証明されたこととなります:

- 診断対象 Web アプリケーションのホストは Shisho Cloud に連携したクラウド上のリソースにあるか
- 診断対象 Web アプリケーションのホストが検証用の URL にリクエストを送ると期待されたレスポンスを返すか

所有権の検証の結果は「診断ジョブ」タブ (`https://cloud.shisho.dev/[orgid]/applications/[appid]/jobs/scan`) に表示されます。本ページが開かれる時点でも検証が行われ、最新の状態での検証結果を確認できます。

![診断の必要条件の検証結果](/docs/ja/_md-assets/adbcb3d995-scan-prerequisites-verification-results.png)

#### Shisho Cloud に連携したクラウド上のリソースを通して証明する場合

診断対象アプリケーションのホストが Shisho Cloud に連携したクラウド上のリソースにある場合、そのホストは所有権があると判断されます。既に連携がされている場合は基本的には対応は必要ありません。クラウドのリソースを連携するには[外部連携を設定する](/docs/ja/g/getting-started/integrate-apps/index.md)を参照してください。

Shisho Cloud によって検出されたホストは「アプリケーション > Attack Surfaces」のタブでご確認いただけます。

![アタックサーフェス一覧](/docs/ja/_md-assets/40908f5ac1-attack_surface_list.png)

:::warning
ご利用のクラウドリソースの構成によっては Shisho Cloud に連携していてもホストを正しく検出できない場合がございます。その際は運営元（Flatt Security） へお気軽にお問い合わせください。
:::

クラウドサービスを利用していない、もしくは利用しているがリソースの連携が困難な場合は検証用の URL を通しての証明をご検討ください。

#### 検証用の URL を通して証明する場合

検証用の URL を通して診断対象アプリケーションのホストの所有権を証明するには、指定された URL がアプリケーション検証トークンを返す必要があります。

Shisho Cloud が送るリクエスト:

```
GET http[s]://<ホスト>/.well-known/shisho-cloud/<アプリケーション検証トークン>
```

診断対象アプリケーションのホストが返すレスポンス:

```
Status: 200 OK
Body: <アプリケーション検証トークン>
```

アプリケーション検証トークンは「一般」タブ (`https://cloud.shisho.dev/[orgid]/applications/[appid]`)から確認できます。

![アプリケーション検証トークン](/docs/ja/_md-assets/64622abf8f-ownership-token.png)

例えば、`sample-app.com` のホストを `01J5TAXF0RV6G9DVH4BPM1SX1G` のトークンで検証する場合、以下リクエストが Shisho Cloud により送られます:

```
GET http://sample-app.com/.well-known/shisho-cloud/01J5TAXF0RV6G9DVH4BPM1SX1G
```

ここで、`sample-app.com` がレスポンスでステータスコード `200 OK` と以下のボディを返したらこのホストの所有権は証明されたことになります:

```
01J5TAXF0RV6G9DVH4BPM1SX1G
```

## 診断スケジュールをカスタマイズする (任意)

デフォルトでは、Web 診断は毎月 1 日の 00:00 UTC (日本時間 09:00) に実行されますが、診断スケジュールを cron 形式でカスタマイズしたり、スケジュール実行を無効にして手動での実行のみとする設定も可能です。

Web アプリケーション診断は、「ワークフロー」によって定期実行されています。Web 診断を実行するワークフローの詳細画面は[こちら](https://cloud.shisho.dev/*/workflows?wfid=prebundle-web-review)または[こちら](https://cloud.shisho.dev/*/workflows?wfid=free-trial-web-scanning)からアクセスしていただけます。

![Web アプリケーション診断用ワークフロー](/docs/ja/_md-assets/a2e19911e9-scan-execution-workflow-list.png)

診断スケジュールを変更・無効化したい場合は、まず画面右側の「更新」ボタンを押してください。

スケジュールは以下のように `.triggers.schedule[].cron` にて指定されています。

```yaml
version: 0.1.0
id: "free-trial-web-scanning"
name: "Review Web application posture (Free Trial)"
triggers:
  schedule:
    # highlight-next-line
    - cron: "0 0 1 * *"
# (略)
```

スケジュールを変更したい場合は、希望するスケジュールを cron 形式で記載して、「保存」ボタンをクリックしてください。
例えば毎日 12:00 UTC (日本時間 21:00) に診断を実行したい場合は以下のように設定します。

```yaml
version: 0.1.0
id: "free-trial-web-scanning"
name: "Review Web application posture (Free Trial)"
triggers:
  schedule:
    # highlight-next-line
    - cron: "0 12 * * *"
# (略)
```

:::caution
cron スケジュールは UTC 時間で解釈されます。お使いのタイムゾーンと UTC 時間の時差を考慮して設定してください。
:::

またスケジュールを無効化したい場合は、以下のように変更して「保存」ボタンをクリックしてください。

```yaml
version: 0.1.0
id: "free-trial-web-scanning"
name: "Review Web application posture (Free Trial)"
triggers:
  # highlight-next-line
  schedule: []
# (略)
```

なお、ワークフローのトリガー設定の詳細については[こちら](/g/concepts/workflow-manifest)を参照してください。

## 診断を実行する

### ワークフローから診断を実行する

デフォルトの設定では Web アプリケーション診断は毎月 1 日の 00:00 UTC (日本時間 09:00) に実行されます。スケジュール実行を待たずにすぐ診断を実行したい場合は、以下の手順で実行できます。

Web アプリケーション診断は、「ワークフロー」によって定期実行されています。Web 診断を実行するワークフローの詳細画面は[こちら](https://cloud.shisho.dev/*/workflows?wfid=prebundle-web-review)または[こちら](https://cloud.shisho.dev/*/workflows?wfid=free-trial-web-scanning)からアクセスしていただけます。

![Web アプリケーション診断用ワークフロー](/docs/ja/_md-assets/a2e19911e9-scan-execution-workflow-list.png)

このワークフローは Web 診断を実行するワークフローです。この画面の「実行」ボタンを押すと、Web 診断が全ての登録された Web アプリケーションに対して実行されます。

診断のステータスや進捗を確認するには、画面上部バーの「[アプリケーション](https://cloud.shisho.dev/*/applications)」を開き、アプリケーションの一覧から確認したいアプリケーションを押下して詳細のページを開いてください。次に、「診断ジョブ」タブ (`https://cloud.shisho.dev/[orgid]/applications/[appid]/jobs/scan`) を開くと、診断の実行履歴が表示されます。

![診断ジョブの一覧](/docs/ja/_md-assets/20a4105d72-scan-job-list.png)

診断ジョブの進捗は、実行中の診断ジョブを押下してジョブの詳細画面 (`https://cloud.shisho.dev/[orgid]/applications/[appid]/jobs/scan/[jobid]`) を開くと確認できます。

![診断ジョブの詳細](/docs/ja/_md-assets/f622ba6659-scan-job-details.png)

### 診断の評価結果を確認する

診断ジョブが正常に終了したら評価結果が[ダッシュボード](https://cloud.shisho.dev/*/dashboard)や[リソース](https://cloud.shisho.dev/*/resources)に反映されます。詳しくは、[検出事項を確認する](/docs/ja/g/getting-started/review-findings.md)を参照してください。