# Decision Object

The **_Decision_** refers to an object (or its structure) that a job within a workflow outputs to Shisho Cloud, encapsulating the inspection/audit results of its policies against the input values.

![](/docs/_md-assets/45d0c0b173-how-workflows-work.png)

## Overview

A single _Decision_ object primarily comprises **(1) a decision result pertaining to a certain event** and **(2) its corresponding supplementary information**. For instance, a policy can determine (1) "whether known vulnerable packages exist in the dependency relations of `main` in the GitHub repository `example/example`", and express the result along with (2) the supplementary information, as a _Decision_ object, which can then be logged in Shisho Cloud.

In this context, the information included in the _Decision_ object is referred to as follows:

- (1) "The GitHub repository `example/example`’s `main`": This is the **_Subject_** of the _Decision_
- (1) "Whether known vulnerable packages exist in the dependencies": This pertains to the **_API Version_** and **_Kind_** of the _Decision_
- (2) Supplementary information: These are multiple **_Payload_** elements tied to the _Decision_

## Relationship with the Dashboard Screen

The information displayed on the Shisho Cloud's assessment results screen is essentially a list of these _Decisions_.

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

## Schema

Technically, a _Decision_ consists of a `header` and a `payload`, as shown in the pseudocode below:

```typescript
type Decision = {
  header: DecisionHeader;
  payload: string;
};

// the context of the decision
type DecisionHeader = {
  // API version
  api_version: string;

  // a kind of decision
  kind: string;

  // the 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>;
};

// the entity that 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,
}
```

When drafting a policy that generates a `Decision`, the output value of the policy needs to conform to the above structure. As expressed in JSON, it would take the form of:

```typescript
{
    "header": {
        "api_version": "...",
        "kind": "...",
        /* ... */
    },
    "payload": "..."
}
```

## `header.apiVersion` and `header.kind`

`header.apiVersion` and `header.kind` correspond to the **_API Version_** and **_Kind_** of the _Decision_, respectively. In other words, these two fields combined indicate what kind of decision the _Decision_ represents.

### `header.apiVersion`

`header.apiVersion` denotes the namespace that manages the type information of the _Decision_.

:::info

Currently, as Shisho Cloud only supports _Decisions_ bearing the types (_Kind_) provided by Shisho Cloud, the value for `header.apiVersion` is limited to the constant `decision.api.shisho.dev`.

:::

### `header.kind`

`header.kind` signifies the type of _Decision_.

:::info

The [official libraries for scripting policies in Rego](https://github.com/flatt-security/shisho-cloud-rego-libraries) include helper functions for each _Kind_ that Shisho Cloud supports, which help generate the corresponding _Decision_.

For instance, [shisho.decision.dependency.package_known_vulnerability](https://github.com/flatt-security/shisho-cloud-rego-libraries/blob/ed057664c7f687432af8b16530a3aaf7617e841e/decision/dependency/package.gen.rego#L8) is a helper function that creates a _Decision_ object with:

- `header.api_version`: `decision.api.shisho.dev`
- `header.kind`: `package_known_vulnerability`

At this point, as mentioned at the beginning of the same file, this type of _Decision_ relates to "The status of unaddressed packages with known vulnerabilities".

```
@title Update packages with known vulnerabilities
```

By going through the official Rego library, you can learn about the kinds of _Decisions_ that Shisho Cloud supports. Moreover, you can create _Decision_ objects with ease using the functions in the library.

:::

## `header.subject`

`header.subject` indicates what the given _Decision_ is about.

### Handling by Policy Authors

Policy authors are free to assign any value to this field.

### Treatment by Shisho Cloud

Shisho Cloud refers to the tuple `(organization ID, header.apiVersion, header.kind, header.subject, header.locator)` associated with a _Decision_ as the _Decision ID_. Shisho Cloud then stores the _Decision_, ensuring that this _Decision ID_ is always unique.

For example, when a _Decision_ is outputted from a policy, Shisho Cloud behaves as follows:

- If no _Decision_ with that _Decision ID_ exists, it logs a new _Decision_.
- If a _Decision_ with that _Decision ID_ already exists, it overwrites the existing _Decision_.

The uniqueness of the _Decision ID_ implies that Shisho Cloud can **record a _Decision_ with a unique `header.subject` value for each type of _Decision_ within each organization**.