ワークフローからの通知

このチュートリアルでは、通知グループ を通して、指定したメッセージを Slack チャンネル等の通知チャネルに送信するワークフローの記述方法を説明します。

ゴール

• Shisho Cloud の通知機能を用いてできることを把握する
• 実際に通知を送信するための、notify ブロックの記述方法を理解する

通知グループの準備（Slack 通知の場合）

このチュートリアルでは、通知グループを通して Slack チャンネルに通知を送信します。 まずはページ『通知グループを設定する』に従って、以下を準備してください:

• Shisho Cloud からのテストメッセージの受信を確認済みの Slack チャンネル
• 同 Slack チャンネルを含む通知グループ

通知グループが作成できたら、画面右上の歯車 ⚙️ マーク > 通知（Notifications）タブからアクセスできる通知グループ一覧画面に表示されている、通知グループの ID を控えておいてください。ID は原則 NG から始める文字列です。

例: 10 分おきに決まったメッセージを通知する

通知を設定する

通知グループが用意できたら、実際に当該グループに通知を送信するワークフローを作成してみましょう。 以下のワークフロー・マニフェストを、YOUR_NOTIFICATION_GROUP_ID をここまでのステップで控えておいた対象の通知グループ の ID に変更した上で Shisho Cloud の組織に登録してください:

info

組織へのワークフローマニフェストの登録方法はこちらのページで確認できます。 また、ワークフローやワークフローのマニフェストの基本的な構造を確認したい場合は、ワークフローのマニフェストをご覧ください。

version: 0.1.0
id: "test-workflow"
name: "test workflow run by cron schedule"
triggers:
  schedule:
    - cron: "*/10 * * * *"
jobs:
  - id: notify-job
    name: Notify Job Status by cron schedule
    notify:
      rego: |
        import data.shisho

        notification_groups := [
            # ポリシーから通知を送信する宛先通知グループの ID
            "YOUR_NOTIFICATION_GROUP_ID",
        ]

        # ワークフロージョブのステータス
        notifications[n] {
          input.running_state == shisho.job.running_state_in_queue

            ng := notification_groups[_]
            target := shisho.notification.to_notification_group(ng)
            n := shisho.notification.new(target, "Hello, this is a test message!")
        }

別ページで説明されているように、このワークフローのマニフェストが定義している triggers 以下の schedule トリガーは、同ワークフローを 10 分に 1 度起動します。

info

10 分のトリガーを待たず、作成したワークフローを直ちに実行してみたい場合は、ワークフロー一覧画面にある実行ボタンをクリックしてください。

実際に、上記のワークフローを登録してからは、10 分ごとに 1 度メッセージが Slack チャンネルに投稿されるはずです。

info

通知に関する事前準備が完了しているのに、メッセージが確認できない場合は、サービス運営元（Flatt Security）にお問い合わせください。

通知設定を理解する

上記のワークフローの notify-job というジョブには notify ブロックが含まれています。 このブロックこそが通知の送信を Shisho Cloud に指示している実態です。

ワークフロー 中の notify ブロックは、当該ブロックが含まれるジョブのステータスが変化するたびに評価・実行されます。その上で、同 notify ブロックに含まれているポリシーは、以下のようなロジックを定義するものです:

1. ジョブのステータスが running_state_in_queue である場合のみ
   • input.running_state == shisho.job.running_state_in_queue
2. 指定した通知グループをターゲットとして
   • ng := notification_groups[_]
   • target := shisho.notification.to_notification_group(ng)
3. 対象の Slack チャンネルへ文字列 "Hello, this is a test message!" を送信する
   • n := shisho.notification.new(target, "Hello, this is a test message!")

info

notifications[n] { ... n := shisho.notification.new(...) ... } という記述により通知が送信できるのは、以下のような仕様によります:

1. Rego インラインポリシーの API で定義されているとおり、Shisho Cloud は notify ブロック中のポリシーを実行した結果の notifications 変数に格納された配列の各要素を元に通知先を決定する
2. n := shisho.notification.new(...) という記述により、notifications 変数に格納された配列 shisho.notification.new(...) なる要素が追加される

info

notify ブロックは、当該ブロックが含まれるジョブのステータスが変化するたびに実行されます。 この仕様は、「ポリシーの実行開始時・終了時の両方で通知を行う」などの柔軟な通知を行うためのものです。

なお、上記で作成したワークフロー中の通知ポリシーを以下のように変更することで、実際にこの仕様の挙動を確認できます:

notifications[n] {
  # 下記の行をコメントアウトし、ジョブのステータス変更をチェックしない
  # input.running_state == shisho.job.running_state_in_queue

  ng := notification_groups[_]
  target := shisho.notification.to_notification_group(ng)
  n := shisho.notification.new(target, "Hello, this is a test message!")
}

例: GitHub 上のイベントを起点に通知する

通知を設定する

次は GitHub 上の各リポジトリのデフォルトブランチに対する push イベントが発生した際の通知を実現してみましょう。 以下のワークフロー・マニフェストを、YOUR_NOTIFICATION_GROUP_ID をここまでのステップで控えておいた対象の通知グループ の ID に変更した上で Shisho Cloud の組織に登録してください:

info

組織へのワークフローマニフェストの登録方法はこちらのページで確認できます。 また、ワークフローやワークフローのマニフェストの基本的な構造を確認したい場合は、ワークフローのマニフェストをご覧ください。

version: 0.1.0
id: "test-workflow-by-push-event"
name: "test workflow run by a GitHub push event"
triggers:
  github:
    - push:
        branches:
          - :default_branch
jobs:
  - id: notify-job
    name: Notify Job Status by GitHub Push Event
    notify:
      rego: |
        import data.shisho

        notification_groups := ["YOUR_NOTIFICATION_GROUP_ID"]　# 作成した通知グループIDの配列

        notifications[n] {
          input.running_state == shisho.job.running_state_in_queue　# ワークフロージョブのステータス

            ng := notification_groups[_]
            target := shisho.notification.to_notification_group(ng)
            n := shisho.notification.new(target, "Hello, this is a test message sent by a GitHub push event!")
        }

上記のワークフローが設定できたら、いずれかのリポジトリの対象ブランチに対して、push イベントを発生させてみてください。

info

push イベントは、例えば以下のようにして意図的に引きこすことができます:

• Shisho Cloud が連携された GitHub 組織内にテスト用リポジトリを作成する
• git commit --allow-empty --message="test" のようなコマンドでデフォルトブランチに空コミットを作成する
• push する

すると、連携済み GitHub リポジトリへの push イベントが発生するたびに Slack チャンネルにテストメッセージが投稿されるはずです。

info

通知に関する事前準備が完了しているのに、メッセージが確認できない場合は、サービス運営元（Flatt Security）にお問い合わせください。

通知設定を理解する

上記のワークフローの notify-job というジョブには notify ブロックが含まれています。 先述の schedule トリガーを用いた例と同様に、このブロックこそが通知の送信を Shisho Cloud に指示しています。

ワークフロー 中の notify ブロックは、当該ブロックが含まれるジョブのステータスが変化するたびに評価・実行されます。 また、先述の schedule トリガーを用いた例と同様に、同 notify ブロックに含まれているポリシーは以下のようなロジックを定義するものです:

1. ジョブのステータスが running_state_in_queue である場合のみ
   • input.running_state == shisho.job.running_state_in_queue
2. 指定した通知グループをターゲットとして
   • ng := notification_groups[_]
   • target := shisho.notification.to_notification_group(ng)
3. 対象の Slack チャンネルへ文字列 "Hello, this is a test message!" を送信する
   • n := shisho.notification.new(target, "Hello, this is a test message!")

info

今回利用しなかった notify ブロックの機能を利用することで、以下のようなことも実現できます:

• 特定の緊急度の Decision が発行されたときのみ通知する
• 通知内容（メッセージ）中に検出されたセキュリティ上の問題の情報を詳細に含める
• ...

notify ブロックの他の用例については、通知に関するチュートリアル を確認してください。