GitHub

本チュートリアルでは、Shisho Cloud 上のワークフローを GitHub リポジトリにインポートしたのち、リポジトリ内のワークフローと Shisho Cloud 上のワークフローを同期する仕組みを GitHub Actions を用いて構築します。

info

このページでは、Shisho Cloud 上で実行される検査ルールを表す「Shisho Cloud 上のワークフロー」と GitHub Actions 上で実行される「GitHub Actions ワークフロー」の両者に言及します。単に「ワークフロー」と記載する場合は、Shisho Cloud 上のワークフローを指します。

本チュートリアルは、以下の 4 ステップからなります:

Shisho Cloud 上のワークフローを格納した GitHub リポジトリを作成する
Shisho Cloud において、特定リポジトリの GitHub Actions からのアクセスを許可する
GitHub において、ワークフローを Shisho Cloud にデプロイする GitHub Actions ワークフローを作成する
GitHub において、リポジトリ内と Shisho Cloud 上のワークフローの差分をチェックする GitHub Actions ワークフローを作成する

3. のステップによって、リポジトリ内のワークフローの変更が即座に Shisho Cloud に反映されるようになります。また 4. のステップによって、Shisho Cloud の Web インターフェースから直接ワークフローを編集した場合に、その変更に対応するプルリクエストが作成されるようになります。これらのセットアップによって、GitHub リポジトリと Shisho Cloud 上のワークフローが常に同期されるようになります。

info

GitHub Actions から Shisho Cloud にアクセスするために「Shisho Cloud のアクセストークンを GitHub Actions のシークレットに登録する」というような操作の必要はありません。その代わりに、GitHub Actions ジョブに対して GitHub が発行する OIDC トークンの情報に基づき、Shisho Cloud がジョブに短命の認証情報を発行します。これはおよそ GitHub Action が有する OIDC ベースの AWS/Google Cloud 連携の仕組みと同等の仕組みです。

ワークフローを格納した GitHub リポジトリを作成する

Shisho Cloud 上の全ての検査ルールを Git でバージョン管理するために、まずは既に Shisho Cloud 上にあるワークフローをエクスポートして、リポジトリに取り込みましょう。

まず GitHub でリポジトリを作成し、クローンしてください。クローンしたディレクトリへ Shisho Cloud 上のワークフローをエクスポートするには、次のコマンドを実行します。ただし、コマンド中の $SHISHO_CLOUD_ORG_ID はお使いの Shisho Cloud 組織の ID に置換してください。

shishoctl workflow export --structured --org $SHISHO_CLOUD_ORG_ID --path .

エクスポートが完了したら、作成されたファイルをコミットして GitHub にプッシュしてください。

特定リポジトリの 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 にログインできるようになります。記入が完了したら、「保存」ボタンをクリックしてください。

ワークフローを Shisho Cloud にデプロイする GitHub Actions ワークフローを作成する

次のステップとして、ワークフローを Shisho Cloud にデプロイする GitHub Actions ワークフローを作成しましょう。リポジトリ内に、以下のようなファイルを作成してください。

.github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

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

jobs:
  main:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        SHISHO_CLOUD_ORG_ID: ["flatt-security"] # FIXME: お使いの Shisho Cloud 組織の ID に置換してください
    steps:
      - uses: actions/checkout@v3

      - name: Install shishoctl
        run: |
          SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.14.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: Deploy workflows
        run: shishoctl workflow apply --org "$SHISHO_CLOUD_ORG_ID" --path .
        env:
          SHISHO_CLOUD_ORG_ID: ${{ matrix.SHISHO_CLOUD_ORG_ID }}

コード中の FIXME と記載された箇所を適切に書き換えてください。なお、入力すべき bot-id の値は、先ほど作成した信頼条件の設定画面下部に記載されています。

信頼条件の設定画面下部には、bot-id の値が記載されています

以上のようにしてファイル .github/workflows/deploy.yml を作成したら、コミットして GitHub にプッシュしてください。

ここまでの設定により、main ブランチにプッシュされるたびにリポジトリ内のワークフローが Shisho Cloud にデプロイされるようになります。GitHub リポジトリの Actions タブを開き、Deploy ワークフローが正常に実行されたことを確認しましょう。

正常に実行された GitHub Actions ジョブのログ

リポジトリ内と Shisho Cloud 上のワークフローの差分をチェックする GitHub Actions ワークフローを作成する

これまでのセットアップによって、デフォルトブランチにプッシュされるたびにワークフローが Shisho Cloud にデプロイされるようになりました。しかし Shisho Cloud の Web インターフェースから直接ワークフローを編集した場合、リポジトリ内のワークフローと Shisho Cloud 上のワークフローとの間に差分が生じてしまいます。GitHub リポジトリで管理しているワークフローと Shisho Cloud 上で実際に実行されているワークフローが同一である状態を維持するためには、この 2 つの差分を定期的にチェックする必要があります。

shishoctl workflow pull コマンドは、Shisho Cloud 上のワークフローをローカルに取り込むコマンドです。このコマンドを利用して、Shisho Cloud 上のワークフローとリポジトリ内のワークフローとの間に差分がある場合に自動でプルリクエストを作成する GitHub Actions ワークフローを作成していきます。

自動でプルリクエストを作成する GitHub Actions ワークフローが動作するためには、GitHub Actions によるプルリクエストの作成を許可しておく必要があります。その設定を確認・変更するには、以下の URL からリポジトリの設定を開いてください。

https://github.com/[organization]/[repository]/settings/actions

「Workflow permissions」の節にある「Allow GitHub Actions to create and approve pull requests」にチェックが入っていない場合は、チェックを入れて Save ボタンをクリックしてください。

Workflow permissions の設定

チェックボックスをクリックしてもチェックが入らない場合、GitHub Organization レベルの設定で GitHub Actions によるプルリクエストの作成が禁止されている場合があります。その場合には以下の URL から Organization の設定を開き、「Workflow permissions」の節にある「Allow GitHub Actions to create and approve pull requests」のチェックを入れてください。

https://github.com/organizations/[organization]/settings/actions

次に、以下のような GitHub Actions ワークフローファイルを作成します。

.github/workflows/check-workflow-drift.yml
name: Check for drift from the workflows on Shisho Cloud

on:
  schedule:
    - cron: "0 0 * * *" # 毎日 0:00 UTC
  workflow_dispatch:

permissions:
  contents: write # 自動作成したコミットのプッシュに必要な権限
  id-token: write # Shisho Cloud にログインするために必要な権限
  pull-requests: write # プルリクエストの自動作成に必要な権限

jobs:
  main:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        SHISHO_CLOUD_ORG_ID: ["flatt-security"] # FIXME: お使いの Shisho Cloud 組織の ID に置換してください
    steps:
      - uses: actions/checkout@v3

      - name: Install shishoctl
        run: |
          SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.14.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: Pull workflows from Shisho Cloud
        run: shishoctl workflow pull --org "$SHISHO_CLOUD_ORG_ID" --path . --structured | tee "$OUTPUT_PATH"
        env:
          SHISHO_CLOUD_ORG_ID: ${{ matrix.SHISHO_CLOUD_ORG_ID }}
          OUTPUT_PATH: ${{ runner.temp }}/output.txt

      - name: Generate PR description
        run: |
          echo 'The workflows on Shisho Cloud has changed from those in this repository.

          > [!NOTE]  
          > This PR was automatically created by `.github/workflows/check-workflow-drift.yml`.
          ' > "$PR_DESCRIPTION_PATH"

          if [ -s "$OUTPUT_PATH" ]; then
            echo 'Output of command:
          ```' >> "$PR_DESCRIPTION_PATH"
            cat "$OUTPUT_PATH" >> "$PR_DESCRIPTION_PATH"
            echo '```' >> "$PR_DESCRIPTION_PATH"
          fi
        env:
          OUTPUT_PATH: ${{ runner.temp }}/output.txt
          PR_DESCRIPTION_PATH: ${{ runner.temp }}/pr-description.txt

      - name: Create pull request
        uses: peter-evans/create-pull-request@eebb6ccce1e609378f84426acf60c49144cf2d3a
        id: create_pull_request
        with:
          title: "Workflows on Shisho Cloud has changed"
          body-path: ${{ runner.temp }}/pr-description.txt
          branch: shisho-cloud
          commit-message: "pulled changes from Shisho Cloud"

note

上記の GitHub Actions ワークフローは差分を検知した場合にプルリクエストを作成しますが、代わりに例えば Slack に通知を送ることもできます。その場合は、Create pull request ステップの代わりに以下のようなステップを追加すると良いでしょう。SLACK_WEBHOOK_URL の取得方法など slackapi/slack-github-action の詳しい使い方については、公式リポジトリをご参照ください。

- name: Check for diff
  id: diff
  run: |
    git add -N .
    git diff --quiet || echo "changed=1" >> $GITHUB_OUTPUT

- name: Notify Slack
  uses: slackapi/slack-github-action@v1
  if: steps.diff.outputs.changed == '1'
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

このファイルを作成したら、コミットして GitHub にプッシュしてください。

これにより、リポジトリ内と Shisho Cloud 上のワークフローが一致しているかどうか定期的にチェックされるようになりました。ここから先は、実際に Web インターフェースから直接ワークフローを編集し、GitHub Actions がワークフローの差分を正しく検出できることを確認していきましょう。

まずデモのワークフロー demo-notification の編集画面を開きます。

このワークフローのマニフェストを例えば以下のように編集し、「保存」ボタンをクリックしましょう。

version: 0.1.0
id: "demo-notification"
name: "DEMO: Send notifications to various channels (edited from console)"
triggers: {}
jobs:
- id: group
  name: Send to notification groups
  notify:
    rego: |
      package demo.notification.group

      import data.shisho

      notifications[n] {
        input.running_state == shisho.job.running_state_preprocessing

        data.params.group != ""
        n := shisho.notification.to_group(
          data.params.group,
          "hello! (edited from console)",
        )
      }
# 後略

次に、以下の URL から GitHub Actions ワークフローのページを開き、Run workflow ボタンをクリックして workflow_dispatch トリガーを手動実行しましょう。

https://github.com/[organization]/[repository]/actions/workflows/check-workflow-drift.yml

GitHub Actions ワークフローのページにおいて、手動でトリガーする

このチュートリアルで作成した GitHub Actions ワークフローによって、Web インターフェースから加えた変更を取り込むプルリクエストが作成されているはずです。先ほどの変更が確かに反映されていることを確認してみましょう。

自動作成されたプルリクエスト

このように、Shisho Cloud の Web インターフェースでワークフローが変更されたとしても、先ほど作成した GitHub Actions ワークフローにより、その変更を検知してリポジトリに取り込むことができます。ここでは既存のワークフローを変更した際の実行結果を確認しましたが、Web インターフェースからワークフローを新規作成したり削除したりした場合にも、この GitHub Actions ワークフローによってその変化を GitHub リポジトリに取り込むことができます。

ワークフローを格納した GitHub リポジトリを作成する​

特定リポジトリの GitHub Actions から Shisho Cloud 組織へのアクセスを許可する​

ワークフローを Shisho Cloud にデプロイする GitHub Actions ワークフローを作成する​

リポジトリ内と Shisho Cloud 上のワークフローの差分をチェックする GitHub Actions ワークフローを作成する​

ワークフローを格納した GitHub リポジトリを作成する

特定リポジトリの GitHub Actions から Shisho Cloud 組織へのアクセスを許可する

ワークフローを Shisho Cloud にデプロイする GitHub Actions ワークフローを作成する

リポジトリ内と Shisho Cloud 上のワークフローの差分をチェックする GitHub Actions ワークフローを作成する