Skip to main content
View as Markdown

shishoctl CLI

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 shishoctl CLI is a tool for operating Shisho Cloud. With this tool, you can deploy and manage policies on Shisho Cloud, providing an experience similar to using the docker or kubectl commands.

Installation​

The following commands install shishoctl for each supported environment:

You can install shishoctl to /usr/local/bin with the following command:

SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.15.0-x86_64-unknown-linux-gnu"
sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
sudo chmod +x /usr/local/bin/shishoctl

Sign in​

By running the following command in an environment where the shishoctl command can be executed, you can sign in to Shisho Cloud from shishoctl:

shishoctl auth signin
note

The authentication information obtained from Shisho Cloud by the shishoctl auth signin command expires after a certain period. If you encounter an authentication error, please run the shishoctl auth signin command again.

Sign in as a Bot​

When accessing Shisho Cloud in environments where a browser is not available, such as CI/CD or server environments, sign in using a bot instead of a personal account. See Bot / Authentication for the available methods - API key, GitHub Actions OIDC, GitLab CI OIDC, or a custom OIDC identity provider - and how to run shishoctl auth signin:bot with each of them.

Example: Get a list of workflows​

Once successfully signed in via the shishoctl CLI, you can perform a range of operations on Shisho Cloud using shishoctl. For example, the following command retrieves a list of workflows registered to the organization ID org-a:

shishoctl workflow list -o org-a
info

The organization ID refers to the ID registered when creating an organization. If the organization ID is unclear, please follow the steps below to check it:

  1. Open the Shisho Cloud dashboard in a web browser.
  2. Check the organization ID (the [oid] part) in the URL displayed in your web browser, as shown below:
https://cloud.shisho.dev/[oid]/dashboard

Example: Chaining Multiple Commands​

The shishoctl CLI outputs data in JSON or YAML format. This allows you to process the output of one command and use it as input for another, enabling complex chained operations.

For example, the following is a Python script that retrieves a list of findings in an organization, then gets the information of the resources targeted by each finding, and displays them together. Before running, please set the environment variables SHISHOCTL_ORG_ID (Organization ID) and SHISHOCTL_PROJECT_ID (Project ID).

import subprocess
import yaml
import os

org_id = os.getenv("SHISHOCTL_ORG_ID")
project_id = os.getenv("SHISHOCTL_PROJECT_ID")

result = subprocess.run(
  ["shishoctl", "project", "finding", "list", "--org", org_id, "--project", project_id, "--format", "yaml"],
  capture_output=True,
  text=True,
)
parsed = yaml.safe_load(result.stdout)

summary = {"entries": []}
for i, finding in enumerate(parsed["entries"]):
  api_version = finding["id"]["apiVersion"]
  kind = finding["id"]["kind"]

  result = subprocess.run(
    ["shishoctl", "finding", "describe", "--org", org_id, api_version, kind],
    capture_output=True,
    text=True,
  )
  parsed = yaml.safe_load(result.stdout)

  summary["entries"].append({
    "id": {
      "apiVersion": api_version,
      "kind": kind,
    },
    "subjects": [],
  })

  for entry in parsed["decisions"]["entries"]:
    summary["entries"][i]["subjects"].append(entry['header']['subject'])

print(yaml.dump(summary))

Checking How to Use Other Commands​

For more information on how to use the shishoctl command, please see other pages on this website or run the following command:

shishoctl --help
Last updated on