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 クエリにより取得されたデータが格納されます。
例えば同 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 ライブラリ 中の定義が格納されています。
例えば、shisho.decision.dependency パッケージ中の package_known_vulnerability 関数 にアクセスしたい場合、以下のような Rego ポリシーを記述できます:
import data.shisho
x := shisho.decision.dependency.package_known_vulnerability(...)
ポリシーに期待される出力
decisions
変数
インラインポリシーは decisions
というリストに、Decision と呼ばれる構造のデータのリスト(配列)を格納しなくてはなりません。
これを通して、インラインポリシーは、ポリシーによる検査/監査結果を Shisho Cloud に伝えることが出来ます。
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
当該インラインポリシーが指定されているジョブの実行状態が格納されています。
shisho.job 以下 に、この変数が取りうる値が定数として定義されています。
input.exit_code
当該インラインポリシーが指定されているジョブの実行状態が格納されています。
shisho.job 以下 に、この変数が取りうる値が定数として定義されています。
data.shisho
data.shisho
変数には、Shisho Cloud 公式の Rego ライブラリ 中の定義が格納されています。
ポリシーに期待される出力
notifications
変数
インラインポリシーは notifications
というリストに、Notification と呼ばれる構造のデータのリスト(配列)を格納する必要があります。
これを通して、インラインポリシーは、Shisho Cloud に通知の送信を指示できます。
Shisho Cloud 公式の Rego ライブラリ 中の shisho.notification.new()
関数を用いて、Notification オブジェクトを容易に作成できます。