OpenAPI Specification からのインポート
本チュートリアルで扱う機能は、Web アプリケーション診断機能をご契約いただいた組織でのみご利用いただけます。
OpenAPI Specification をもとにエンドポイントをインポートする場合は、以下の手順に従ってください。
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 OpenAPI Specification with Shisho Cloud"
permissions:
contents: read
id-token: write # Shisho Cloud にログインするために必要な権限
on:
push:
branches:
- main
paths:
# Workflow ファイルのパス
- .github/workflows/sync-openapi.yaml
# FIXME: 参照するスキーマファイルのパスに置換してください
- docs/openapi.yaml
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.12.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: Sync with Shisho Cloud
run: |
shishoctl web-application collect-endpoints openapi \
--org $ORG_ID \
--app $APP_ID \
--path $SCHEMA_PATH
env:
ORG_ID: ${{ vars.SHISHO_CLOUD_ORG_ID }}
APP_ID: ${{ vars.SHISHO_CLOUD_APP_ID }}
# FIXME: 参照するスキーマファイルのパスに置換してください
SCHEMA_PATH: docs/openapi.yaml
コード中の FIXME
と記載された箇所を適切に書き換えてください。
また次の変数を 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 }}
Web コンソールから手動でインポートする
まず、「巡回ジョブ」タブ (https://cloud.shisho.dev/[orgid]/applications/[appid]/jobs/find
) に移動し、「スキーマから巡回」ボタンをクリックします。
次に、ボタンを押すと表示されるサイドオーバーにおいて「OpenAPI Specification」のタブを選択し、表示される「Click here or drag and drop a OpenAPI Specification file to upload」の箇所をクリックするか、ドラッグアンドドロップにて OpenAPI Specification ファイルをアップロードしてください。
ファイルをアップロードすると、フォーム下部にアップロードされた OpenAPI Specification ファイルの内容が表示されます。
表示された内容で問題なければ、画面下部の「予約」ボタンをクリックしてください。
巡回ジョブを予約してからしばらく待つと、Shisho Cloud はアップロードされた OpenAPI Specification ファイルの内容をもとにエンドポイントを登録します。ジョブの状態が「Completed」になったら、「エンドポイント」タブを開き、エンドポイントが登録されたことを確認してください。