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

Rego インラインポリシー

このページでは、ワークフロー中のジョブに対して Rego で記述されたインラインポリシーと、Shisho Cloud の間の API 仕様を示します。

jobs[].decide.rego に関する API

jobs[].decide.rego に指定されたインラインポリシーは、ワークフロー の持つ「データ取得 → 検査/監査 → 結果の通知・結果の記録」という機能のうち、検査・監査の役割を持ちます。

パッケージ名

制限はありません。自由なパッケージ名を指定できます。

package arbitrary.name.could.be.specified

ポリシー実行時の入力

jobs[].decide.rego に指定されたインラインポリシーに対しては、いくつかの入力が与えられます。

input

input 変数には、jobs[].decide.input.schema に指定された GraphQL クエリにより取得されたデータが格納されます。

info

例えば同 GraphQL クエリが以下のようなものだったとします:

query {
github {
organizations {
login
requiresTwoFactorAuthentication
}
}
}

このとき、インラインポリシー中からアクセスできる input という変数に、以下のようなオブジェクトが格納されます:

{
"github": {
"organizations": [
{
"login": "octcat",
"requiresTwoFactorAuthentication": true
},
{
"login": "your-org-name",
"requiresTwoFactorAuthentication": false
}
]
}
}

インラインポリシーから上記のオブジェクトへのアクセスは、以下のようにして行えます:

org := input.github.organizations[_]

data.shisho

data.shisho 変数には、Shisho Cloud 公式の Rego ライブラリ 中の定義が格納されています。

info

例えば、shisho.decision.dependency パッケージ中の package_known_vulnerability 関数 にアクセスしたい場合、以下のような Rego ポリシーを記述できます:

import data.shisho

x := shisho.decision.dependency.package_known_vulnerability(...)

ポリシーに期待される出力

decisions 変数

インラインポリシーは decisions というリストに、Decision と呼ばれる構造のデータのリスト(配列)を格納しなくてはなりません。 これを通して、インラインポリシーは、ポリシーによる検査/監査結果を Shisho Cloud に伝えることが出来ます。

info

Shisho Cloud 公式の Rego ライブラリ 中で、"Emits a decision ..." なる description が指定された関数を用いることで、特定の kind を持った decision を簡単に発行できます。

jobs[].notify.rego に関する API

パッケージ名

制限はありません。自由なパッケージ名を指定できます。

ポリシー実行時の入力

input.query

jobs[].notify.input.schema で指定された GraphQL クエリにより取得されたデータが格納されています。

input.organization_id

ワークフローが実行されている組織の ID が格納されています。

input.workflow_id

ワークフローの ID が格納されています。

input.job_id

当該インラインポリシーが指定されているジョブの ID が格納されています。

input.decisions

当該インラインポリシーが指定されているジョブの decide ブロックにより生成された decisions が格納されています。

input.running_state

当該インラインポリシーが指定されているジョブの実行状態が格納されています。

info

shisho.job 以下 に、この変数が取りうる値が定数として定義されています。

input.exit_code

当該インラインポリシーが指定されているジョブの実行状態が格納されています。

info

shisho.job 以下 に、この変数が取りうる値が定数として定義されています。

data.shisho

data.shisho 変数には、Shisho Cloud 公式の Rego ライブラリ 中の定義が格納されています。

ポリシーに期待される出力

notifications 変数

インラインポリシーは notifications というリストに、Notification と呼ばれる構造のデータのリスト(配列)を格納する必要があります。 これを通して、インラインポリシーは、Shisho Cloud に通知の送信を指示できます。

info

Shisho Cloud 公式の Rego ライブラリ 中の shisho.notification.new() 関数を用いて、Notification オブジェクトを容易に作成できます。