メインコンテンツまでスキップ

shishoctl CLI から操作する

shishoctl CLI は Shisho Cloud を操作するための CLI です。 このツールを用いると、docker コマンド や kubectl コマンドに近い体験で Shisho Cloud へのポリシーのデプロイや管理を行えます。

インストール​

現在 shishoctl がサポートしている各環境で、shishoctl をインストールするコマンドを以下に示します:

以下のコマンドにより、shishoctl を /usr/local/bin にインストールできます:

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

サインイン​

shishoctl コマンドが実行できる環境で以下のコマンドを実行することで、shishoctl から Shisho Cloud にサインインすることができます:

shishoctl auth signin
note

shishoctl auth signin コマンドで Shisho Cloud から取得された認証情報は、一定時間経過後に無効になります。 認証状態に関するエラーが発生した場合には、再度 shishoctl auth signin コマンドを実行してください。

ボットとしてサインインする​

CI/CD 環境やサーバー環境など、ブラウザを使用できない環境から Shisho Cloud にアクセスする場合は、ボットアカウントを使ってサインインすることができます。 ボットによるサインイン方法は、以下の2通りです。

信頼条件を使用したサインイン (GitHub Actions / GitLab CI での利用)​

GitHub Actions や GitLab CI という OIDC 対応環境では、信頼条件を使用した認証を推奨します。 この方法では API Key を管理する必要がなく、より安全に認証できます。

詳細は以下のドキュメントを参照してください:

API Key を使用したサインイン​

OIDC 対応環境以外でボット認証を行う場合、API Key を使用して shishoctl から Shisho Cloud にアクセスできます。

APIキーはボットに紐づく概念です。 そのため、ボットを未だ作成していない場合は、まずボットを作成しましょう。 具体的な手順は以下です。

  1. ボット一覧 ページにアクセスする
  2. 「ボットの追加」ボタンから、新しいボットを作成する

ボット作成画面

作成できたら、以下の手順でAPIキーが発行できます。

  1. ボット一覧 ページにアクセスする。
  2. 作成したボットの名前をクリックし、個別ページを開く。
  3. APIキータブで、「APIキーの作成」を押下し、ボットの API キーを新規作成する。

API キー作成画面

重要

API キーは作成時に一度しか表示されません。あとからの再確認は不可能なので、作成時に控え、安全な場所に保存してください。

以下のコマンドで API キーを使って認証してください:

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

なお、api-key.json ファイルは、以下のような JSON 形式で作成する必要があります。

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

または API Key を直接指定することもできます:

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

Bot ID は BTから始まるIDで、ボット作成画面で作成後、ボットの詳細ページURLにて確認できます。

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

セキュリティのベストプラクティス

一般的な SaaS の API キーと同様に、ボットの API キーが漏れると、Shisho Cloud 上のでデータが侵害される可能性があります。安全に扱うため、以下に留意ください。

  • API キーを外部公開しない。特に、GitHub 等の公開リポジトリにコミットしない。
  • 非公開領域に API キーを保管する場合も、極力安全な場所を利用する。例えば、GitHub リポジトリ内に直接含めるよりは、GitHub Actions のシークレット管理機能を利用する。
  • 不要になった API キーは速やかに削除する。

認証方法の使い分け​

以下の表は、利用環境に応じた推奨認証方法の一覧です。環境に最も適した方法を選択してください。

環境推奨認証方法
GitHub Actions信頼条件 (OIDC)
GitLab CI信頼条件 (OIDC)
その他の CI/CD 環境API Key

例: ワークフローの一覧を取得する​

shishoctl を通じて Shisho Cloud 上の各種操作を実行できるようになります。 例えば、以下のコマンドは組織ID org-a に登録されているワークフローの一覧を取得する例です:

shishoctl workflow list -o org-a
info

組織 ID とは、組織の作成時に登録した ID のことです。 組織 ID が不明な場合は、以下の手順で組織 ID を確認してください:

  1. Shisho Cloud のダッシュボード画面を Web ブラウザ上で開く
  2. その際に Web ブラウザに表示される以下のような URL に含まれる組織 ID ([oid] 部分) を確認する
https://cloud.shisho.dev/[oid]/dashboard

例: 複数のコマンドをつなげて実行する​

shishoctl CLI では、データを取得するためのコマンドの結果は JSON か YAML 形式で出力されます。 これを利用し、あるコマンドの結果を加工・抽出して次のコマンドの引数とすることで、複数のコマンドをつなげて複雑な処理を実現することができます。

たとえば、以下はある組織に含まれる検知事項の一覧を取得したあと、それぞれの検知事項が対象とするリソースの情報を取得し、それらをまとめて表示する Python スクリプトの例です。 実行の際は、環境変数 SHISHOCTL_ORG_ID (組織 ID) と SHISHOCTL_PROJECT_ID (プロジェクト 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))

その他のコマンドの使い方を確認する​

shishoctl コマンドのさらなる用法については、本 Web サイトの他のページや、以下のコマンドを通して確認してください:

shishoctl --help
に最終更新