# shishoctl CLI から操作する

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

## インストール

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

<Tabs>
<TabItem value="linux-amd64" label="Linux (amd64)" default>

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

```sh
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
```

</TabItem>

<TabItem value="linux-arm64" label="Linux (arm64)">

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

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

</TabItem>

<TabItem value="apple-amd64" label="macOS (Intel CPU)">

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

```sh
SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.15.0-x86_64-apple-darwin"
sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
sudo chmod +x /usr/local/bin/shishoctl
```

</TabItem>

<TabItem value="apple-arm64" label="macOS (Apple Silicon)">

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

```sh
SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.15.0-aarch64-apple-darwin"
sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
sudo chmod +x /usr/local/bin/shishoctl
```

</TabItem>

<TabItem value="windows-amd64" label="Windows (amd64)">

WSL 等で Linux 向けバイナリを利用するか、[https://shisho.dev/releases/shishoctl-0.15.0-x86_64-pc-windows-gnu.exe](https://shisho.dev/releases/shishoctl-0.15.0-x86_64-pc-windows-gnu.exe) からダウンロードし、`shishoctl.exe` として利用してください。

</TabItem>

</Tabs>

## サインイン

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

```shell
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 を管理する必要がなく、より安全に認証できます。

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

- [検査ルールを Git リポジトリで管理する - GitHub](/docs/ja/g/getting-started/deploy-policies-with-git-repositories/github.md)
- [検査ルールを Git リポジトリで管理する - GitLab](/docs/ja/g/getting-started/deploy-policies-with-git-repositories/gitlab.md)

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

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

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

1. [ボット一覧](https://cloud.shisho.dev/*/settings/bots) ページにアクセスする
2. 「ボットの追加」ボタンから、新しいボットを作成する

![ボット作成画面](/docs/ja/_md-assets/d6e927005e-bot-creation.png)

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

1. [ボット一覧](https://cloud.shisho.dev/*/settings/bots) ページにアクセスする。
2. 作成したボットの名前をクリックし、個別ページを開く。
3. APIキータブで、「APIキーの作成」を押下し、ボットの API キーを新規作成する。

![API キー作成画面](/docs/ja/_md-assets/411cecba16-api-key-creation.png)

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

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

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

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

```json
{
  "api_key": "shisho_apikey_..."
}
```

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

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

:::info
Bot ID は `BT`から始まるIDで、[ボット作成画面](https://cloud.shisho.dev/*/settings/bots)で作成後、ボットの詳細ページURLにて確認できます。

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

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

一般的な 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 に登録されているワークフローの一覧を取得する例です:

```shell
shishoctl workflow list -o org-a
```

:::info
組織 ID とは、[組織の作成](/docs/ja/g/getting-started/create-an-organization.md)時に登録した 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) を事前に設定してください。

```python
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 サイトの他のページや、以下のコマンドを通して確認してください:

```shell
shishoctl --help
```