サービスモードREST API
KeeperコマンダーサービスモードでREST APIをを作成
最終更新
KeeperコマンダーサービスモードでREST APIをを作成
最終更新
Keeperコマンダーのサービスモードモジュールは、最小限の設定で導入可能な、安全で設定可能なAPIサーバーを提供することで、REST APIの統合を可能にします。このモジュールにより、ユーザーはセキュリティと設定の柔軟性を維持しながら、REST APIインターフェースを介してコマンダーのCLIコマンドを実行できます。このサービスはローカルで実行でき、オプションでNgrokと統合して、既存のNgrokネットワークにルーティング可能なアドレスを作成することもできます。
API サーバー: コマンダーCLI コマンドを実行するためのFlaskベースのREST APIサーバー
サービス管理: APIサービスのライフサイクル全体を管理
構成管理: インタラクティブなセットアップと簡略化されたセットアップの両方を備えた柔軟な構成システム
セキュリティ制御: API キー管理、アクセス制御、レート制限、IP 許可/拒否などの包括的なセキュリティ機能
柔軟なホスティングオプション: オンプレミス、Dockerコンテナ、統合されたNgrokエージェントを使用したクラウドでの実行
service-create
カスタマイズ可能な設定でサービスを初期化および構成する
service-start
既存の構成でサービスを開始する
service-stop
実行中のサービスを正常に停止する
service-status
現在のサービスステータスを表示する
service-config-add
新しいAPI構成とコマンドアクセス設定を追加する
APIキー認証
設定可能なトークンの有効期限 (分/時間/日)
API応答のオプションのAES-256 GCM暗号化
提供された証明書を使用したTLS
レート制限
IP拒否リスト管理
リクエストの検証とポリシーの適用
Keeperコマンダーサービスモード機能は、既存のコマンダーセッションをREST APIでラップするセルフホステッドミドルウェアです。この機能は、高速なリクエストとシンプルなHTTPベースのAPIが求められる環境に適しています。
この機能を最も安全に使用するためには、以下のことをお勧めします。
使用ケースに基づいて必要なコマンドに限定したコマンドアクセス制御を適用する。
REST APIエンドポイントへのアクセスにIPホワイトリストを適用する。
コマンダーサービスを実行しているマシンへのアクセスを保護する。
異なるコマンドや使用ケースごとに異なるAPIトークンを使用する。
Keeperコマンダーを起動します。
keeper shell
プロンプトが表示されたら、Keeperの認証情報でログインします。
対話型プロンプトを使用してサービスを作成および構成します。
service-create
以下を設定します。
設定フォーマット
ポート番号
Ngrok認証トークン (任意)
セキュリティ設定 (任意)
コマンドアクセス制御
例
My Vault> service-create
Enter Port No:9090
Enable Ngrok Tunneling? (y/n):y
Enter Ngrok Auth Token:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Enter Ngrok Custom Domain:myname
Enable Advanced Security? (y/n):n
List of supported commands, Enter comma separated:whoami,record-add,tree,ls
Generated API key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Uploading service_config.yaml ...
2025-03-26 11:47:46 [INFO] keeper_service - Route initialization completed
Route initialization completed successfully
Keeper Commander Service initialization complete
Commander Service starting on http://localhost:9090
Process ID: 34291
Generated ngrok URL: https://myname.ngrok.io
* Serving Flask app 'keepercommander.service.app'
* Debug mode: off
1 つのコマンドでサービスを構成します。
service-create -p 9090 -c 'record-add,whoami'
Ngrok認証トークンとカスタムドメインを使用してサービスを開始します。
service-create -p 9090 -c 'record-add,whoami' -ng xxxx -cd myname
パラメータ
-p, --port
: サービスのポート番号
-c, --commands
: 許可するコマンドのコンマ区切りリスト
-ng, --ngrok
: クラウド管理URLアクセス用のNgrok認証トークン (任意)
-cd
: Ngrokカスタムドメイン、サブドメイン部分のみ (任意)
-aip
: 許可するIPリスト (任意)
-dip
: 拒否するIPリスト (任意)
-crtf, --certfile
: SSL証明書ファイルのパス、.crt
または.pem
(.key
オプション)を受け入れます
-crtp, --certpassword
: SSL証明書のパスワード(オプション)
初期設定が完了すると、ボルト内に「Commander Service Mode」というタイトルのレコードが作成されます。このレコードにはservice_config.yaml
というYAMLファイルが含まれています。
次回以降のサービス起動では、パラメータなしのservice-create
コマンドのみを実行します。設定はボルトから読み込まれ、起動されます。
サービスステータスを確認します。
service-status
追加の構成を追加します。
service-config-add
サービスを開始します。
service-start
サービスを停止します。
service-stop
REST API の使用は非常に簡単で、CLIで入力する場合とまったく同じように、提供されたAPIキーとコマンダーコマンドだけで実行できます。
curl --location 'http://localhost:<port>/api/v1/executecommand' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
"command": "tree"
}'
Ngrok を使用している場合、Curl コマンドは以下のようになります。
curl --location 'http://<your-ngrok-url>/api/v1/executecommand' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
"command": "tree"
}'
Postmanアプリからリクエストを送信できます。以下の画像を参照の上、Content-TypeヘッダーとAPIキーヘッダが指定されていることを確認してください。
すべての応答では以下の基本形式を使用します。
{ "command": "<command_name>", "data": <command_specific_data> , "status": "success"}
一部のコマンドは、整形されたJSONを返すように変更されています。それ以外のコマンドは、通常のコマンダーCLIバージョンと同様の形式でデータを返します。
出力が変更されたコマンドの例
{
"status": "success",
"command": "ls",
"data": {
"folders": [
{
"number": 1,
"uid": "folder_uid_string",
"name": "My Folder",
"flags": "RW"
}
],
"records": [
{
"number": 1,
"uid": "record_uid_string",
"type": "login",
"title": "My Login",
"description": "Optional description"
}
]
}
}
{
"status": "success",
"command": "tree",
"data": [
{
"level": 0,
"name": "Root Folder",
"path": "Root Folder"
},
{
"level": 1,
"name": "Subfolder",
"path": "Root Folder/Subfolder"
}
]
}
{
"status": "success",
"command": "mkdir",
"data": {
"folder_uid": "new_folder_uid_string"
}
}
{
"status": "success",
"command": "record-add",
"data": {
"record_uid": "new_record_uid_string"
}
}
{
"status": "success",
"command": "search record",
"data": [
{
"number": 1,
"uid": "record_uid_string",
"type": "login",
"title": "Matching Record",
"description": "Optional description"
}
]
}
{
"status": "success",
"command": "search folder",
"data": [
{
"number": 1,
"uid": "folder_uid_string",
"name": "Matching Folder"
}
]
}
{
"command": "get",
"data": {
"attachments": "service_config.yaml 537b ID: XYZ",
"last_modified": "2025-01-18 15:35:21",
"share_admins": "xyz@email.com",
"shared": "False",
"shared_users": "xyz@email.com (Owner)",
"title": "Commander Service Mode",
"type": "",
"uid": "folder_uid_string"
},
"status": "success"
}
{
"status": "success",
"command": "audit-report",
"data": [
{
"audit_event_type": "open_record",
"created": "2025-02-18T10:30:45+00:00",
"geo_location": "New York, NY, US",
"ip_address": "192.168.1.100",
"keeper_version": "Commander 16.11.0",
"message": "User john.doe@example.com opened record UID ABCD1234EFGH5678",
"username": "john.doe@example.com"
}
]
}
コマンダーサービスモードでNgrokを使用するには、まず ngrok.com にサインアップし、https://dashboard.ngrok.com/authtokens で認証トークンを生成してください。
カスタムドメインを使用する場合は、https://dashboard.ngrok.com/domains で設定を行い、コマンダーサービスモードの起動時にカスタムサブドメインを指定します。
Ngrokの使用にはセキュリティ上の考慮が必要です。以下のガイダンスをご参照ください。
Keeperサービスアカウントは最小権限で実行します。サービスアカウントの権限は必要最小限に制限することを推奨します。
NgrokのIPポリシーを活用して、サービスへのアクセスを保護します。
サポートするコマンドの範囲を制限します。たとえば、API経由でレコードを追加する必要がある場合は、record-add
コマンドのみに制限するなど、必要なコマンドのみ許可します。「Command List」セクションでコマンド一覧をご参照ください。
指定された時間枠内で許可されるAPIリクエストの最大数を定義します。
入力形式: X/[minute|hour|day]
またはX per [minute|hour|day]
有効な値の例: " 100/minute
"、" 50/hour
"、" 1000 per day
"
備考: 大文字と小文字は区別されません。
IPアドレスまたはIPネットワーク範囲に基づいてアクセスを制御します。
入力形式: IPアドレスまたはCIDRブロックのカンマ区切りリスト
検証ルール: 各IPは有効なIPv4アドレスまたはCIDRブロックである必要があります。
有効な値の例: 192.168.1.1, 10.0.0.0/24
備考: 空のリストも許容されます (この場合、検証はスキップされます)
REST APIレスポンスに対して、AES-256 (GCM) による暗号化を追加するオプションのレイヤーです。
入力形式: y
またはn
秘密鍵の検証ルール
ちょうど32文字であること
使用できる文字: 英数字および特殊文字 (@#$%^&+=)
空欄は不可
備考: API応答の復号化にはキーが必要です。
REST APIトークンの有効期間を設定します。
入力形式: Xm、Xh、Xd。ここで、X は正の数値で、時間単位は分の場合はm、時間の場合はh、日の場合はdとなります。
検証ルール
値は正の数でなければなりません。
単位はm、h、dのいずれかである必要があります。
有効な値の例: 30m
、24h
、7d
備考: 空の入力の場合、トークンは無期限に設定されます。
API経由で公開するコマンドのリストを指定します。
入力形式: 有効なKeeperコマンドーコマンドのコンマ区切りリスト
検証ルール
有効なKeeperコマンダーコマンドのコンマ区切りリストである必要があります (コマンダーCLIでhelpを実行するか、間違ったコマンドを入力すると表示されます)。
空欄にできません
個々のコマンドにはスペースを入れないでください。
有効な値の例: whoami,tree,list
入力形式: 「json」または「yaml」を選択します。
検証ルール: jsonまたはyamlのいずれかである必要があります (大文字と小文字は区別されません)
ボルトに保存された service_config.yaml
ファイルには、サービスのプロパティが含まれています。
このファイル内には「records」と呼ばれるセクションがあり、特定のコマンドやトークンの有効期限を指定したAPIキーを定義できます。
encryption: ''
encryption_private_key: ''
ip_allowed_list: 0.0.0.0/0
ip_denied_list: ''
is_advanced_security_enabled: n
ngrok: y
ngrok_auth_token: XXXXXXXXXX
ngrok_custom_domain: myname
ngrok_public_url: ''
port: 9090
rate_limiting: ''
records:
- api-key: XXXXXXXX
command_list: tree,record-add
expiration_timestamp: '9999-12-31T23:59:59'
- api-key: XXXXXXXX
command_list: get
expiration_timestamp: '9999-12-31T23:59:59'
Dockerイメージのインストール、ビルド、実行
Docker をインストールします。
リポジトリのクローンを作成します。
docker build -t keeper-commander .
コマンドを使用してDockerイメージをビルドします。
作成されたDockerイメージ (docker images
) を確認します。
ターミナルウィンドウで2つの環境変数を設定します。
KEEPER_USERNAME
: Keeperコマンダーにログインするためのユーザー名です。
KEEPER_PASSWORD
: 上記のユーザーのマスターパスワードです。
以下のコマンドを使用してkeeper-commander dockerイメージを実行します。
docker run -d -p <port>:<port> keeper-commander \
service-create -p <port> -c '<comma separated commands like tree,ls>' \
-ng <ngrok-auth-token> -cd <ngrok-custom-domain> \
-aip <allowed-ip-list> -dip <denied-ip-list> \
--user $KEEPER_USERNAME \
--password $KEEPER_PASSWORD
docker ps
コマンドを使用してkeeper-commanderイメージが起動していることを確認します。
コマンドを使用してログを確認します。
docker logs <docker container name or ID>
ログからAPIキーを取得します。APIキーは以下のように表示されます。
Generated API key: <API-KEY>
curl --location 'http://localhost:<port>/api/v1/executecommand' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
"command": "<command>"
}'
Keeperコマンダーは「ログイン状態を維持」などの永続ログインモードに対応しており、一定時間セッションをアクティブに保つことができます。アカウントで永続ログインモードを有効にするには、以下のコマンドを入力します。
this-device persistent-login on
this-device register
永続ログインが有効になっている場合、以降コマンダーを実行する際に認証を求められることはありません。永続ログインは、サービスモードAPIをバックグラウンドで中断なく実行するために必要であり、繰り返しのログインを省略してシームレスに認証を行えます。
永続ログインセッションの詳細については、こちらのページをご覧ください。
サポートや機能のリクエストについては、下記までお問い合わせください。
コマンダーのサービスモードに関して、追加機能やセットアップガイドのご要望がございましたら、お気軽にお問い合わせください。