# Connect RPC からのインポート

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

Connect RPC (Protocol Buffers) をもとにエンドポイントをインポートする場合は、以下の手順に従ってください。

## GitHub Actions で自動連携する (推奨)

GitHub Actions を用いてスキーマを Shisho Cloud と自動で連携させる方法について説明します。

### GitHub Actions から Shisho Cloud にログインできるようにする

GitHub Actions から Shisho Cloud にログインできるよう、Shisho Cloud 側の設定をしていきます。まず Shisho Cloud の[ボット作成画面](https://cloud.shisho.dev/*/settings/bots)を開き、「ボット」を作成します。ボットとは Shisho Cloud 組織へのアクセス権限を持つ主体であり、GitHub Actions ジョブはボットとして Shisho Cloud にログインすることになります。

![ボット作成画面](/docs/ja/_md-assets/709014004f-create-bot.png)

ボットを作成したら、ボット名をクリックすると信頼条件の設定画面に遷移します。

![信頼条件の設定画面](/docs/ja/_md-assets/947bafca52-create-trust-condition.png)

信頼条件とは、GitHub Actions ジョブが当該ボットとして Shisho Cloud にログインするために、ジョブが満たすべき条件です。ワークフローが格納されている GitHub リポジトリの Organization およびリポジトリ名を記入すると、当該リポジトリに属する GitHub Actions ジョブが、先ほど作成したボットとして Shisho Cloud にログインできるようになります。記入が完了したら、「保存」ボタンをクリックしてください。

### GitHub Actions Workflow の作成

次のような GitHub Actions Workflow を作成してください。

```yaml
name: "Sync the Connect RPC (Protocol Buffers) with Shisho Cloud"

permissions:
  contents: read
  id-token: write # Shisho Cloud にログインするために必要な権限

on:
  push:
    branches:
      - main
    paths:
      # Workflow ファイルのパス
      - .github/workflows/sync-connectrpc.yaml
      # FIXME: 参照するスキーマファイルが格納されているフォルダのパスに置換してください
      - docs/proto/**

jobs:
  sync:
    name: Sync
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install shishoctl
        run: |
          SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.15.0-x86_64-unknown-linux-gnu"
          sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
          sudo chmod +x /usr/local/bin/shishoctl

      - name: Sign in
        uses: flatt-security/shisho-cloud-action@v1
        with:
          # FIXME: 入力すべき bot-id の値は信頼条件の設定画面に記載されています
          bot-id: "BTXXXXXXXXXXXXXXXXXXXXXXXXXX"

      - name: Zip the schemas
        run: cd $IMPORT_ROOT_DIR && zip -r schema.zip $SCHEMA_DIR
        env:
          # FIXME: インポートする際のルートとなるディレクトリへのパスに置換してください
          IMPORT_ROOT_DIR: docs
          # FIXME: 参照するスキーマファイルが格納されているフォルダのパスに置換してください (IMPORT_ROOT_DIR からの相対パス)
          SCHEMA_DIR: proto

      - name: Sync with Shisho Cloud
        run: |
          shishoctl web-application collect-endpoints connectrpc \
            --org $ORG_ID \
            --app $APP_ID \
            --url $ENDPOINT_URL \
            --path schema.zip
        env:
          ORG_ID: ${{ vars.SHISHO_CLOUD_ORG_ID }}
          APP_ID: ${{ vars.SHISHO_CLOUD_APP_ID }}
          ENDPOINT_URL: ${{ vars.SHISHO_CLOUD_CONNECTRPC_ENDPOINT_URL }}
```

コード中の `FIXME` と記載された箇所を適切に書き換えてください。

Connect RPC との連携では複数のスキーマを zip 圧縮してアップロードします。複数のスキーマ間で連携するために `IMPORT_ROOT_DIR` と `SCHEMA_DIR` を適切に設定する必要があります。

例えば次のようなディレクトリ構成になっている場合を考えます。

```txt
(リポジトリルート)/
└─ docs/
   └─ proto/
      └─ feat1/
         └─ example.proto
```

ここで `example.proto` は次のような内容になっているとします。

```proto
syntax = "proto3";

package proto.feat1.example;

// ここにスキーマが来る
```

`proto` ディレクトリを起点としているため、これを実現するには次のような環境変数を指定します。

- `IMPORT_ROOT_DIR` = `docs`
- `SCHEMA_DIR` = `proto`

また次の変数を GitHub リポジトリに登録してください。詳しい設定の方法は [GitHub 公式のドキュメント](https://docs.github.com/ja/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#creating-configuration-variables-for-a-repository) を参照してください。

- `SHISHO_CLOUD_ORG_ID` 組織ID
  - Shisho Cloud のダッシュボードの URL に含まれています
  - `https://cloud.shisho.dev/{{ 組織ID }}/dashboard`
- `SHISHO_CLOUD_APP_ID` アプリケーションID
  - アプリケーションページのURLに含まれています
  - `https://cloud.shisho.dev/{{ 組織ID }}/applications/{{ アプリケーションID }}`
- `SHISHO_CLOUD_CONNECTRPC_ENDPOINT_URL` スキャンに利用する Connect RPC エンドポイント URL

## Web コンソールから手動でインポートする

まず、「ジョブ一覧」ページ (`https://cloud.shisho.dev/[orgid]/applications/[appid]/jobs/find`) に移動し、「エンドポイントを登録」ボタンをクリックします。

![「ジョブ一覧」ページ](/docs/ja/_md-assets/7e896cb85a-crawling-job-list-empty.png)

次に、ボタンを押すと表示されるサイドオーバーにおいて「スキーマファイルをアップロードする」のオプションを選択してください。

![サイドオーバー](/docs/ja/_md-assets/106540e3e1-crawling-sideover.png)

その後、遷移先の「スキーマアップローダー」ページにおいて「Connect RPC」のオプションを選択してください。
そして、表示される「Click here or drag and drop archived protocol buffer files to upload」の箇所をクリックするか、ドラッグアンドドロップにて ZIP 圧縮された Protocol Buffer ファイル群をアップロードしてください。このとき、あわせて Connect RPC エンドポイントの URL (例: `https://api.example.test/v1`) も入力してください。

![アップロード画面(初期状態)](/docs/ja/_md-assets/0c7802a25e-upload-protobuf-1.png)

ファイルをアップロードすると、フォームに「Uploaded file: `<アップロードしたファイル名>`」と表示されるので、その内容で問題なければ画面下部の「予約」ボタンをクリックしてください。

巡回ジョブを予約してからしばらく待つと、Shisho Cloud は Connect RPC エンドポイント に指定された URL 及びアップロードされた Protocol Buffer ファイル群の内容をもとにエンドポイントを登録します。ジョブの状態が「Completed」になったら、「エンドポイント」タブを開き、エンドポイントが登録されたことを確認してください。