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

Decision オブジェクト

Decision は、ワークフロー中のジョブが持つポリシーが入力値に対する検査/監査結果を出力する際に、Shisho Cloud に対して出力するオブジェクト(またはその構造)のことです。

概要

1 つの Decision オブジェクトは、主に (1) 何かしら 1 つの事象に対する意思決定結果と、(2) その補足情報から構成されています。 例えば、ポリシーは (1)「ある GitHub リポジトリ example/examplemain」に関して、「既知脆弱性が知られたパッケージが依存関係に存在しないか」を判断した結果を (2) 補足情報とともに Decision オブジェクトとして表現し、Shisho Cloud にそれを記録することが出来ます。

このとき、 Decision オブジェクトに含まれる上述のような情報は、それぞれ以下のように呼ばれています:

  • (1) のうち「ある GitHub リポジトリ example/examplemain」: DecisionSubject
  • (1) のうち「既知脆弱性が知られたパッケージが依存関係に存在しないか」: DecisionAPI VersionKind
  • (2) の補足情報: Decision に紐付けられた複数の Payload

ダッシュボード画面との関連

Shisho Cloud の評価結果画面に表示される情報は、この Decision を列挙したものに他なりません。

スキーマ

形式的には、Decision は以下の擬似コードのように、headerpayload から構成されます。

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.apiVersionheader.kind

header.apiVersionheader.kind はそれぞれ DecisionAPI VersionKind に対応するデータです。 つまり、この 2 つのフィールドの組は、その Decision が「どんな種別の意思決定か」を示します。

header.apiVersion

header.apiVersion は、Decision の種別情報を管理する名前空間を表す値です。

info

現在 Shisho Cloud では、Shisho Cloud が提供している種別(Kind)を持つ Decision のみをサポートしているため、header.apiVersion の値は定数値 decision.api.shisho.dev に制限されています。

header.kind

header.kind は、Decision の種別を表す値です。

info

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 を記録できる