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

ワークフロー

Shisho Cloud における GitHub 上のリソースの検査や、評価結果（Findings）の登録は、全て「ワークフロー（Workflow）」により定義されています。

info

始めから定義されているワークフローは、画面上部バーの「ワークフロー（Workflow）」メニュー押下時に表示される、以下の画面からご閲覧いただけます:

ワークフローによる検査/監査の流れ​

ワークフローによる検査/監査は、以下のような流れに従って行われます:

ワークフロー中のトリガーの発火​

各ワークフローは トリガー（trigger） を定義しています。 トリガーとは、そのワークフローがいつ実行されるべきかを定義するものです。 Shisho Cloud は、このトリガの定義に従い、必要なときだけに必要なワークフローを実行します。

例えば、以下のようなマニフェストで定義されたワークフローは、それぞれ時間経過や非同期イベントの発生を起点に実行されます:

version: 0.1.0
id: "example-workflow"
triggers:
  schedule:
    # 10 分おきに実行
    - cron: "*/10 * * * *"
# ...
version: 0.1.0
id: "example-workflow"
triggers:
  github:
    # デフォルトブランチへの push イベント時に実行
    - push:
        branches:
          - :default_branch

各ジョブの発火​

ワークフローは複数の ジョブ（Job） を定義しています。 一つ一つのジョブは以下のように、どんなデータを・どのように検査/監査するかを定義する decide ブロック と、ジョブ実行の各フェーズにおいて、何を・どのように通知するかを定義する notify ブロック を含んでいます:

jobs:
  - id: notify
    name: Notify Job Status
    decide:
      rego: |
        # ...
      input:
        schema: |
          # ...
    notify:
      input:
        schema: |
          # ...
      rego: |
        # ...

トリガーによりワークフローの実行が決定されたとき、Shisho Cloud は、まず decide ブロックの規定に従って、検査/監査データの生成・取得を実施します。

その傍ら、notify ブロックの規定に従って、必要に応じて外部サービス（GitHub や Slack 等）へ通知します。

decide ブロックの実行​

ジョブの実行時の、decide ブロックの評価は、次の手順で行われます:

  1. データソースからのデータ取得
  2. ポリシーコードの実行

データソースからのデータ取得​

各ジョブの decide ブロック 以下には、ポリシーコードに流し込むデータ、すなわち検査/監査対象のデータの定義として、GraphQL クエリの定義が含まれています。 例えば以下のようなものです:

query {
  aws {
    accounts {
      metadata {
        id
      }
      iam {
        passwordPolicy {
          passwordReusePrevention
        }
      }
    }
  }
}

Shisho Cloud は、このようなクエリの定義に従って各ジョブごとにデータを取得し、ポリシーコードにそれを流し込みます。 これによりお客様は、AWS, Google Cloud, GitHub 等の API に自力でアクセスしたり、そのデータを元に各種メトリクスや既知脆弱性情報との紐付けを行わなくても、簡単に検査/監査対象のデータをポリシーに流し込むことが出来ます。

info

https://cloud.shisho.dev/[oid]/playground/query にて、この GraphQL クエリに関わるドキュメントを閲覧したり、実際のクエリ発行をお試しいただくことができます（α）。 [oid] はお使いの Shisho Cloud 組織の ID に適宜置換してください。

評価結果の登録​

Shisho Cloud は、実行されたポリシーコードから出力されたの値を取りまとめ、評価結果（Finding）として記録します。 これにより、お客様は、ポリシーの評価結果をダッシュボード等の画面から閲覧できるようになります:

ポリシーコードの実行​

Shisho Cloud は、GraphQL クエリにより定義されたデータの取得後、decide ブロックで定義された Rego ポリシーを実行します。

notify ブロックの実行​

decide ブロックのジョブ実行と並行して、ジョブのステータスが変わるたびに、notify ブロックが次の手順で評価・実行されます:

  1. データソースからのデータ取得
  2. ポリシーコードの実行

データソースからのデータ取得​

Shisho Cloud は、decide ブロックの評価時と同じように、notify ブロック中で定義された GraphQL クエリを元にポリシーへの入力を生成します。

ポリシーコードの実行​

Shisho Cloud は、GraphQL クエリにより定義されたデータの取得後、decide ブロックで定義された Rego ポリシーを実行します。

ワークフローの作成​

ワークフローは以下の 2 つの手段のどちらかで作成できます:

  • ワークフローの一覧画面（/[oid]/workflows）ページ中の「ワークフローを追加」ボタンから作成する
  • shishoctl workflow apply コマンドから作成する
に最終更新