# Decision オブジェクト

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

![](/docs/ja/_md-assets/005ec9db77-how-workflows-work.ja.png)

## 概要

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_ を列挙したものに他なりません。

![](/docs/ja/_md-assets/623135318e-findings.png)

## スキーマ

形式的には、_Decision_ は以下の擬似コードのように、`header` と `payload` から構成されます。

```typescript
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 として表現した場合の、以下のような形式のデータです:

```typescript
{
    "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 でポリシーを記述するための公式ライブラリ](https://github.com/flatt-security/shisho-cloud-rego-libraries) 中には、Shisho Cloud がサポートしている種別（_Kind_）それぞれに対して、その種別の _Decision_ を出力するための補助関数が含まれています。

例えば [shisho.decision.dependency.package_known_vulnerability](https://github.com/flatt-security/shisho-cloud-rego-libraries/blob/ed057664c7f687432af8b16530a3aaf7617e841e/decision/dependency/package.gen.rego#L8) は、以下のような*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 を記録できる**