Decision オブジェクト
Decision は、ワークフロー中のジョブが持つポリシーが入力値に対する検査/監査結果を出力する際に、Shisho Cloud に対して出力するオブジェクト(またはその構造)のことです。
概要
1 つの Decision オブジェクトは、主に (1) 何かしら 1 つの事象に対する意思決定結果と、(2) その補足情報から構成されています。
例えば、ポリシーは (1)「ある GitHub リポジトリ example/example
の main
」に関して、「既知脆弱性が知られたパッケージが依存関係に存在しないか」を判断した結果を (2) 補足情報とともに Decision オブジェクトとして表現し、Shisho Cloud にそれを記録することが出来ます。
このとき、 Decision オブジェクトに含まれる上述のような情報は、それぞれ以下のように呼ばれています:
- (1) のうち「ある GitHub リポジトリ
example/example
のmain
」: Decision の Subject - (1) のうち「既知脆弱性が知られたパッケージが依存関係に存在しないか」: Decision の API Version と Kind
- (2) の補足情報: Decision に紐付けられた複数の Payload
ダッシュボード画面との関連
Shisho Cloud の評価結果画面に表示される情報は、この Decision を列挙したものに他なりません。
スキーマ
形式的には、Decision は以下の擬似コードのように、header
と payload
から構成されます。
type Decision = {
header: DecisionHeader;
payload: string;
};
// a context of the decision
type DecisionHeader = {
// API version
api_version: string;
// a kind of decision
kind: string;
// a target of the decision
subject: string;
// an optional identifier that helps the detailed location in `subject`.
locator: string;
// whether or not the policy allowed the input
type: DecisionType;
// when the decision was made
created_at: Date;
// who made the decision
created_by: DecisionOrigin;
// system flags
annotations: Map<string, string>;
};
// who made the decision
type DecisionOrigin = {
workflow_id: string;
workflow_snapshot_id: string;
job_id: string;
};
enum DecisionSeverity {
SEVERITY_INFO = 0,
SEVERITY_LOW = 1,
SEVERITY_MEDIUM = 2,
SEVERITY_HIGH = 3,
SEVERITY_CRITICAL = 4,
}
enum DecisionType {
DECISION_ALLOW = 1,
DECISION_DENY = 2,
}
実際に Decision
を出力するポリシーを記述する際、ポリシーが出力する値は上記の形式に沿う必要があります。
JSON として表現した場合の、以下のような形式のデータです:
{
"header": {
"api_version": "...",
"kind": "...",
/* ... */
},
"payload": "..."
}
header.apiVersion
と header.kind
header.apiVersion
と header.kind
はそれぞれ Decision の API Version と Kind に対応するデータです。
つまり、この 2 つのフィールドの組は、その Decision が「どんな種別の意思決定か」を示します。
header.apiVersion
header.apiVersion
は、Decision の種別情報を管理する名前空間を表す値です。
現在 Shisho Cloud では、Shisho Cloud が提供している種別(Kind)を持つ Decision のみをサポートしているため、header.apiVersion
の値は定数値 decision.api.shisho.dev
に制限されています。
header.kind
header.kind
は、Decision の種別を表す値です。
Rego でポリシーを記述するための公式ライブラリ 中には、Shisho Cloud がサポートしている種別(Kind)それぞれに対して、その種別の Decision を出力するための補助関数が含まれています。
例えば shisho.decision.dependency.package_known_vulnerability は、以下のようなDecision オブジェクトを出力するための補助関数です。
header.api_version
:decision.api.shisho.dev
header.kind
:package_known_vulnerability
このとき、同ファイルの冒頭で以下のような表示があるように、この種別の Decision は「既知脆弱性を持つパッケージの未対応状況」に関するものとなっています。
@title Update packages with known vulnerabilities
このように、公式 Rego ライブラリを確認することで、Shisho Cloud が対応する Decision の種別を確認できます。 また、ライブラリ中の関数を用いることで、容易に Decision オブジェクトを作成できます。
header.subject
header.subject
は、当該 Decision がどんな対象に対する意思決定なのかを示す値です。
ポリシー記述者による取り扱い
ポリシー記述者は、このフィールドに任意の値を設定できます。
Shisho Cloud による取り扱い
Shisho Cloud ある Decision に対して、 (組織 ID, header.apiVersion, header.kind, header.subject, header.locator)
の 5 つの値の組を Decision ID と呼びます。
その上で、Shisho Cloud は、この Decision ID が常にユニークになるように Decision を保存します。
例えば、ある Decision がポリシーから出力された際、Shisho Cloud は以下のような挙動を取ります:
- その Decision ID を持つ Decision が存在しなければ、新規に Decision を記録する
- その Decision ID を持つ Decision が既に存在すれば、その Decision を上書きする
Decision ID がユニークであるということは、つまり、以下のようにも言い換えられます:
- Shisho Cloud には 各組織中の、ある種別の Decision ごとに、ユニークな
(header.subject, header.locator)
の値を持った Decision を記録できる