Workflows

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.

All inspections of GitHub resources on Shisho Cloud and the registration of evaluation results, known as "Findings", are governed by "Workflows".

info

Predefined workflows can be viewed from the screen that appears when you click on the "Workflow" menu in the top bar:

Workflow-guided Inspection/Audit Process

Inspections or audits handled by workflows adhere to the following process:

Firing Triggers within Workflows

Each workflow comes with a trigger. A trigger specifies when the workflow should execute. Shisho Cloud adheres to these triggers, running workflows only when needed.

For instance, workflows defined in manifests as shown below are executed based on the passage of time or the occurrence of asynchronous events:

version: 0.1.0
id: "example-workflow"
triggers:
  schedule:
    # Runs every 10 minutes
    - cron: "*/10 * * * *"
# ...

version: 0.1.0
id: "example-workflow"
triggers:
  github:
    # Runs when a push event occurs to the default branch
    - push:
        branches:
          - :default_branch

Job Initiation

A workflow defines multiple jobs. Each job encompasses a decide block, outlining what data to inspect/audit and how, and a notify block, specifying what and how to notify during each phase of job execution:

jobs:
  - id: notify
    name: Notify Job Status
    decide:
      rego: |
        # ...
      input:
        schema: |
          # ...
    notify:
      input:
        schema: |
          # ...
      rego: |
        # ...

Upon triggering, Shisho Cloud first adheres to the decide block's rules to generate and fetch inspection/audit data.

Simultaneously, following the notify block's norms, it sends out notifications to external services like GitHub or Slack as needed.

Execution of the decide Block

During job execution, the decide block's evaluation proceeds as follows:

1. Fetch data from the data source.
2. Execute the policy code.

Fetching Data from the Data Source

The decide block in each job includes a GraphQL query definition. This acts as the regulation for data to flow into the policy code or the data to be inspected/audited.

For instance:

query {
  aws {
    accounts {
      metadata {
        id
      }
      iam {
        passwordPolicy {
          passwordReusePrevention
        }
      }
    }
  }
}

Shisho Cloud, accordingly, fetches data for each job according to this query definition and feeds it into the policy code. This way, customers need not access the AWS, Google Cloud, GitHub APIs individually or connect data with various metrics and known vulnerability data but can smoothly feed inspection/audit data into the policy.

info

Users can view related GraphQL query documentation and try to issue actual queries at https://cloud.shisho.dev/[oid]/playground/query (alpha version). Replace [oid] with your Shisho Cloud organization's ID.

Registering Evaluation Results

Shisho Cloud collects output values from the executed policy code and records them as evaluation results (Findings). This allows customers to view the policy evaluations from screens like the dashboard:

Executing the Policy Code

Following the data collection defined by the GraphQL query, Shisho Cloud executes the Rego policy outlined in the decide block.

Execution of the notify Block

In parallel to the execution of the decide block's job, every change in job status triggers the evaluation and execution of the notify block, which progresses as follows:

1. Fetch data from the data source.
2. Execute the policy code.

Fetching Data from the Data Source

Just like the decide block's evaluation, Shisho Cloud forms input for the policy based on the GraphQL query defined in the notify block.

Executing the Policy Code

Upon obtaining the data defined by the GraphQL query, Shisho Cloud executes the Rego policy defined in the decide block.

Creating Workflows

Users can create workflows using one of the two ways:

• By clicking on the "Add Workflow" button on the workflow list page (/[oid]/workflows).
• Via the shishoctl workflow apply command.