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

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 の種別情報を管理する名前空間を表す値です。

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 を記録できる
に最終更新