# サービスモードREST API
## Keeperコマンダーサービスモード Keeperコマンダーのサービスモードモジュールは、最小限の設定で導入可能な、安全で設定可能なAPIサーバーを提供することで、REST APIの統合を可能にします。このモジュールにより、ユーザーはセキュリティと設定の柔軟性を維持しながら、REST APIインターフェースを介してコマンダーのCLIコマンドを実行できます。このサービスはローカルで実行でき、オプションでNgrokと統合して、既存のNgrokネットワークにルーティング可能なアドレスを作成することもできます。 ## 特徴 ### コア機能 * **API サーバー**: コマンダーCLI コマンドを実行するためのFlaskベースのREST APIサーバー * **サービス管理**: APIサービスのライフサイクル全体を管理 * **構成管理**: インタラクティブなセットアップと簡略化されたセットアップの両方を備えた柔軟な構成システム * **セキュリティ制御**: API キー管理、アクセス制御、レート制限、IP 許可/拒否などの包括的なセキュリティ機能 * **APIバージョン管理**\ 同期処理 (v1) と非同期処理 (v2) の両方をサポートする2種類のAPIバージョンを提供しています。 * **リクエストキューシステム**\ 高度な非同期リクエスト処理機能を備え、リクエストの追跡とステータスの監視が可能です。 * **柔軟なホスティングオプション**: オンプレミス、Dockerコンテナ、統合された**Ngrok**エージェントを使用したクラウドでの実行 ### サービスコマンド
コマンド説明
service-createカスタマイズ可能な設定でサービスを初期化および構成する
service-start既存の構成でサービスを開始する
service-stop実行中のサービスを正常に停止する
service-status現在のサービスステータスを表示する
service-config-add新しいAPI構成とコマンドアクセス設定を追加する
service-docker-setupKSM構成を使用したDockerサービスモードの自動セットアップ
slack-app-setupコマンダーサービスモードを使用したSlackアプリ連携の自動セットアップ
### セキュリティ機能 * APIキー認証 * 設定可能なトークンの有効期限 (分/時間/日) * API応答のオプションのAES-256 GCM暗号化 * 提供された証明書 (.pem) を使用したTLS対応 * 構成可能なルールでレート制限 * IP許可リスト (ホワイトリスト) とIP拒否リスト (ブラックリスト) の管理 * リクエストの検証とポリシーの適用 * 秘密鍵を使用したローカルサービス構成のJSONまたはYAMLファイル暗号化 ## セキュリティ Keeperコマンダーサービスモード機能は、既存のコマンダーセッションをREST APIでラップするセルフホステッドミドルウェアです。この機能は、高速なリクエストとシンプルなHTTPSベースのAPIが求められる環境に適しています。 この機能を最も安全に使用するためには、以下のことをお勧めします。 * コマンダーサービス専用のサービスアカウントを使用し、必要な権限と機能のみに範囲を限定してください。 * また、コマンドのアクセス制御についても、ユースケースに応じて必要なコマンドのみに制限することを推奨します。 * REST APIエンドポイントへのアクセスにIPホワイトリストを適用する。 * コマンダーサービスを実行しているマシンへのアクセスを保護する。 * 異なるコマンドや使用ケースごとに異なるAPIトークンを使用する。 ## 使用法 ### 基本設定 [Keeperコマンダーをインストール](https://docs.keeper.io/jp/keeperpam/commander-cli/commander-installation-setup)してからシェルへログインします。 ``` keeper shell ``` プロンプトが表示されたら、Keeperの認証情報を使用してログインします。コマンダーサービスモードは通常サービスとして実行されるため、生体認証ログイン、または永続的なログインセッションの利用を推奨します。 生体認証ログイン ``` biometric register ``` または、以下のコマンドを使用して永続的なログインセッションを作成します。 ``` this-device persistent-login on this-device register this-device timeout 30d this-device 2fa_expiration forever ``` ※ 上記の設定により、30日間ログイン状態が維持されます。 ### サービスモードの作成: 対話的設定を使用 対話形式のプロンプトを使ってサービスを作成・構成します。 ``` service-create ``` 実行すると、以下の項目の設定を順に求められます。 * ポート番号 * Ngrok認証トークン (任意) * Cloudflareトンネルトークン (任意) * TLS証明書のパス (任意) * リクエストキューシステムの有効化 (y/n) * セキュリティ設定 (任意) * 設定フォーマット (yaml/json) (未作成の場合) * 実行モード (フォアグラウンド/バックグラウンド) * コマンドアクセス制御 例: TLS証明書 (https) を使用してサービスモードを作成する ```bash My Vault> service-create Enter Port No:9090 Enable Ngrok Tunneling? (y/n):n Enable TLS Certificate (y/n):y Enter Certificate Path:/Users/profile/Documents/cert.pem Enter Certificate Password:/Users/profile/Documents/key.pem Enable Request Queue? (y/n):y Enable Advanced Security? (y/n):n Select Run Mode (foreground/background):background List of supported commands, Enter comma separated:whoami,record-add,tree,ls Select configuration format (json/yaml):yaml Generated API key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Uploading service_config.yaml ... Commander Service starting on http://localhost:9090/api/v2/ Generated ngrok URL: https://myname.ngrok.io Commander Service started with PID: 35215 ``` ### ストリームライン構成 1つのコマンドでサービスをすばやく構成できます (デフォルトではHTTP・フォアグラウンドモードで実行されます)。 ```bash service-create -p 9090 -c 'record-add,whoami' -f json ``` Ngrokを使用してすばやく構成する場合 (Ngrokの認証トークンとサブドメインを指定) ```bash service-create -p 9090 -c 'record-add,whoami' -ng xxxxxxxxxxx -cd mydomain ``` Cloudflareを使用してすばやく構成する場合 (Cloudflareの認証トークンとドメイン名を指定) ```bash service-create -p 9090 -c 'record-add,whoami' -cf xxxxxxxxxxx -cfd myname ``` 詳細オプションを使用して構成する場合 {% code overflow="wrap" %} ```bash service-create -p -f -c -rm -q -crtf -crtp -aip -dip ``` {% endcode %} ストリームラインパラメータ * `-p`、`--port`\ サービスのポート番号 (簡易セットアップを開始するために必須) * `-c`、`--commands`\ 許可コマンドまたはエイリアスのカンマ区切りリスト (必須) * `-ng`、`--ngrok`\ クラウド管理のURLアクセス用のngrok認証トークン (任意) * `-cd`\ Ngrokのカスタムドメイン。サブドメイン部分のみ (任意) * `-cf`、`--cloudflare`\ Cloudflareトンネルトークン (クラウド経由でURLアクセスを行うための認証トークン) (任意) * `-cfd`\ Cloudflareカスタムドメイン (任意) * `-crtf`、`--certfile`\ SSL証明書ファイルのパス。拡張子 `.crt` / `.pem` / `.key` に対応 (任意) * `-crtp`、`--certpassword`\ SSL証明書のパスワード (任意) * `-q`、`--queue_enabled`\ リクエストキュー機構を有効化 (y/n)\ **デフォルト: y** * `-rm`、`--run_mode`\ サービスの実行モード (foreground/background)\ **デフォルト: foreground** * `-f`、`--fileformat`\ 構成ファイル形式 (json/yaml) - セットアップを促す前に、サービスはローカルの構成ファイルとボルトを確認し、既存の構成形式があるかをチェックします。 * `-rl`、`--ratelimit`\ IPアドレスごと、かつエンドポイントごとのレート制限を指定します。\ 例: `10/minute`、`100/hour`、`1000/day`\ (任意) * `-aip`、`--allowedip`\ アクセスを許可するIPアドレスのリストを指定します。\ **デフォルト: 0.0.0.0/0, ::/0**\ (任意) * `-dip`\ アクセスを拒否するIPアドレスのリストを指定します。\ (任意) * `-ek`、`--encryption_key`\ レスポンスをAES-256で暗号化するための、Base64形式の32バイト鍵を指定します。\ (任意) * `-te`、`--token_expiration`\ APIキーの有効期限を指定します。\ 例: `30m`、`24h`、`7d`\ (任意) * `-ur`、`--update-record `\ 生成されたAPIキーとサービスURLを、指定したボルトレコードに保存します。\ ログにAPIキーを出力しないようにする目的で有用です。\ (任意) ### 構成ファイル 初期設定が完了すると、ボルト内に「Commander Service Mode」というタイトルのレコードが作成されます。このレコードには`service_config.yaml`というYAML/JSONファイルが含まれています。

コマンダーサービスモードレコード

次回以降のサービス起動では、パラメータなしの `service-create` コマンドを実行します。構成はローカルで暗号化済みの `service_config` ファイルから読み込まれます。 {% hint style="info" %} 構成はボルトに安全に保存されていますが、サービスは起動時にローカルにキャッシュされた暗号化ファイルを使用します。ボルトからの再読み込みを強制するには、`service-start` を実行する前にローカルの構成ファイル (`~/.keeper/service_config.json または .yaml`) を削除してください。 {% endhint %} ### 例: ターミナルからフォアグラウンドで起動する場合 サービスはシステムのターミナルから起動できます。以下の例では、`/api/v1` をフォアグラウンドモードで実行します (`/api/v2` を使用する場合は `-q y` でキューモードを有効化します)。 {% code overflow="wrap" %} ```bash keeper service-create -p 8090 -f json -c 'sync-down,whoami,record-add,login-status' -rm foreground -q n ``` {% endcode %} Ctrl + C でサービスを停止できます。一度サービスを作成した後は、次のようにして再起動できます。 ``` keeper service-start ``` [生体認証ログイン](https://docs.keeper.io/jp/keeperpam/commander-installation-setup/logging-in#logging-in-with-biometric-authentication)または[永続ログインモード](https://docs.keeper.io/jp/keeperpam/commander-installation-setup/logging-in#persistent-login-sessions-stay-logged-in)tohaが有効になっている場合、サービスの起動はシームレスに行われます。 ### サービス管理 サービスステータスを確認します。 ```bash My Vault> service-status Current status: Commander Service is Running (PID: 12345, Terminal: /dev/ttys003) ``` 追加の構成を追加します。 ```bash My Vault> service-config-add List of supported commands, Enter comma separated:tree Generated API key: XXXXXXXXXXXXXXXXXXX= Uploading service_config.yaml ... Config Record with API key created successfully. ``` サービスを開始します。 ```bash My Vault> service-start Commander Service starting on https://localhost:8900/api/v2/ Commander Service started with PID: 12345 ``` サービスを停止します。 ```bash My Vault> service-stop Service stopped successfully ``` ## ヘルスチェック コマンダーのサービスモードでは、サービスの稼働状態を確認するためのヘルスチェック用URLが用意されています。以下は、サービスがlocalhostのポート8080で稼働している場合の例です。 リクエスト ``` curl http://localhost:8080/health ``` レスポンス ``` {"status":"ok"} ``` ## サポート サポートや機能のリクエストについては、[Github](https://github.com/Keeper-Security/Commander/issues)でIssueを提出するか、下記までお問い合わせください。 * ## 次の手順 * [APIの使用](https://docs.keeper.io/jp/keeperpam/commander-cli/service-mode-rest-api/api-usage) * [サービストンネル](https://docs.keeper.io/jp/keeperpam/commander-cli/service-mode-rest-api/service-tunneling) * [Dockerによるデプロイ](https://docs.keeper.io/jp/keeperpam/commander-cli/service-mode-rest-api/docker-deployment) * [高度な設定](https://docs.keeper.io/jp/keeperpam/commander-cli/service-mode-rest-api/advanced-settings)