GitHub
本チュートリアルでは、Shisho Cloud 上のワークフローを GitHub リポジトリにインポートしたのち、リポジトリ内のワークフローと Shisho Cloud 上のワークフローを同期する仕組みを GitHub Actions を用いて構築します。
このページでは、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 上のワークフローが常に同期されるようになります。
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 ワークフローを作成しましょう。リポジトリ内に、以下のようなファイルを作成してください。
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.9.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
の値は、先ほど作成した信頼条件の設定画面下部に記載されています。
以上のようにしてファイル .github/workflows/deploy.yml
を作成したら、コミットして GitHub にプッシュしてください。
ここまでの設定により、main
ブランチにプッシュされるたびにリポジトリ内のワークフローが Shisho Cloud にデプロイされるようになります。GitHub リポジトリの Actions タブを開き、Deploy ワークフローが正常に実行されたことを確認しましょう。
リポジトリ内と 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 ボタンをクリックしてください。
チェックボックスをクリックしてもチェックが入らない場合、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 ワークフローファイルを作成します。
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.9.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"
上記の 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 ワークフローによって、Web インターフェースから加えた変更を取り込むプルリクエストが作成されているはずです。先ほどの変更が確かに反映されていることを確認してみましょう。
このように、Shisho Cloud の Web インターフェースでワークフローが変更されたとしても、先ほど作成した GitHub Actions ワークフローにより、その変更を検知してリポジトリに取り込むことができます。ここでは既存のワークフローを変更した際の実行結果を確認しましたが、Web インターフェースからワークフローを新規作成したり削除したりした場合にも、この GitHub Actions ワークフローによってその変化を GitHub リポジトリに取り込むことができます。