Skip to main content

Decision Object

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

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.

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.

Schema​

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

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:

{
    "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 include helper functions for each Kind that Shisho Cloud supports, which help generate the corresponding Decision.

For instance, shisho.decision.dependency.package_known_vulnerability 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.

Last updated on