Skip to main content

Operating with the 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.14.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, you can sign in using a bot account. There are two methods for signing in as a bot.

Sign in with Trust Conditions (for use with GitHub Actions / GitLab CI)​

For OIDC-compliant environments like GitHub Actions and GitLab CI, we recommend using authentication based on trust conditions. This method is more secure because it eliminates the need to manage API keys.

For more details, please refer to the following documentation:

Sign in with an API Key​

For bot authentication in environments that are not OIDC-compliant, you can use an API key to access Shisho Cloud from shishoctl.

API keys are associated with bots. Therefore, if you have not yet created a bot, you should create one first. Follow these steps:

  1. Access the bots list page
  2. Click the "Add Bot" button to create a new bot

Once created, you can issue an API key by following these steps:

  1. Access the bots list page.
  2. Click on the name of the bot you created to open its detail page.
  3. In the API Key tab, click "Create API Key" to create a new API key for the bot.
Important

API keys are only displayed once at creation time. You cannot retrieve them later, so make sure to save them in a secure location when they are created.

To sign in using an API key, run the following command:

shishoctl auth signin:bot \
  --bot <Bot ID> \
  --api-key-json "$(cat api-key.json)"

The api-key.json file must be in the following JSON format:

{
  "api_key": "shisho_apikey_..."
}

Alternatively, you can specify the API key directly:

shishoctl auth signin:bot \
  --bot <Bot ID> \
  --api-key-json '{"api_key":"shisho_apikey_..."}'
info

The Bot ID is an ID starting with BT. After creating a bot on the bot creation page, you can find it in the URL of the bot's details page.

https://cloud.shisho.dev/{ORGANIZATION_ID}/settings/bots/{BOT_ID}

Security Best Practices

Like API keys for general SaaS products, if a bot's API key is leaked, data on Shisho Cloud may be compromised. To handle them securely, please keep the following in mind:

  • Do not publicly expose API keys. In particular, do not commit them to public repositories such as GitHub.
  • When storing API keys in private locations, use the most secure location possible. For example, use GitHub Actions' secret management feature rather than including them directly in a GitHub repository.
  • Delete API keys promptly when they are no longer needed.

Choosing an Authentication Method​

The following table shows the recommended authentication methods for different environments. Please select the method that best suits your environment.

EnvironmentRecommended Authentication Method
GitHub ActionsTrust Conditions (OIDC)
GitLab CITrust Conditions (OIDC)
Other CI/CD EnvironmentsAPI Key

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