メインコンテンツまでスキップ

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 のボット作成画面を開き、「ボット」を作成します。ボットとは Shisho Cloud 組織へのアクセス権限を持つ主体であり、GitHub Actions ジョブはボットとして Shisho Cloud にログインすることになります。

ボット作成画面

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

信頼条件の設定画面

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

GitHub Actions Workflow の作成

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

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.13.1-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_DIRSCHEMA_DIR を適切に設定する必要があります。

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

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

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

syntax = "proto3";

package proto.feat1.example;

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

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

  • IMPORT_ROOT_DIR = docs
  • SCHEMA_DIR = proto

また次の変数を GitHub リポジトリに登録してください。詳しい設定の方法は GitHub 公式のドキュメント を参照してください。

  • 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) に移動し、「エンドポイントを登録」ボタンをクリックします。

「ジョブ一覧」ページ

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

サイドオーバー

その後、遷移先の「スキーマアップローダー」ページにおいて「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) も入力してください。

アップロード画面(初期状態)

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

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