サービスモードREST API

KeeperコマンダーサービスモードでREST APIをを作成

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

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暗号化
提供された証明書 (.pem) を使用したTLS対応
レート制限
IP許可/拒否リスト管理
リクエストの検証とポリシーの適用
ローカルサービス構成のJSONまたはYAMLファイルは、秘密鍵を使用して暗号化

セキュリティ

Keeperコマンダーサービスモード機能は、既存のコマンダーセッションをREST APIでラップするセルフホステッドミドルウェアです。この機能は、高速なリクエストとシンプルなHTTPSベースのAPIが求められる環境に適しています。

この機能を最も安全に使用するためには、以下のことをお勧めします。

使用ケースに基づいて必要なコマンドに限定したコマンドアクセス制御を適用する。
REST APIエンドポイントへのアクセスにIPホワイトリストを適用する。
コマンダーサービスを実行しているマシンへのアクセスを保護する。
異なるコマンドや使用ケースごとに異なるAPIトークンを使用する。

使用法

基本設定

Keeperコマンダーを起動します。

keeper shell

プロンプトが表示されたら、Keeperの認証情報でログインします。

対話型構成

対話型プロンプトを使用してサービスを作成および構成します。

service-create

以下を構成します。

構成フォーマット (yaml/json)
ポート番号
Ngrok認証トークン (任意)
TLS証明書パス (任意)
セキュリティ設定 (任意)
コマンドアクセス制御

例

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 TLS Certificate (y/n): n
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

APIの使用

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

Postmanアプリからリクエストを送信できます。以下の画像を参照の上、Content-TypeヘッダーとAPIキーヘッダが指定されていることを確認してください。

API応答

すべての応答では以下の基本形式を使用します。

{ "command": "<command_name>", "data": <command_specific_data> , "status": "success"}

コマンド固有の応答

一部のコマンドは、整形されたJSONを返すように変更されています。それ以外のコマンドは、通常のコマンダーCLIバージョンと同様の形式でデータを返します。

出力が変更されたコマンドの例

リストコマンド (ls)

{
  "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"
      }
    ]
  }
}

ツリーコマンド (tree)

{
  "status": "success",
  "command": "tree",
  "data": [
    {
      "level": 0,
      "name": "Root Folder",
      "path": "Root Folder"
    },
    {
      "level": 1,
      "name": "Subfolder",
      "path": "Root Folder/Subfolder"
    }
  ]
}

ディレクトリ作成 (mkdir)

{
  "status": "success",
  "command": "mkdir",
  "data": {
    "folder_uid": "new_folder_uid_string"
  }
}

レコード追加 (record-add)

{
  "status": "success",
  "command": "record-add",
  "data": {
    "record_uid": "new_record_uid_string"
  }
}

レコード検索 (search record)

{
  "status": "success",
  "command": "search record",
  "data": [
    {
      "number": 1,
      "uid": "record_uid_string",
      "type": "login",
      "title": "Matching Record",
      "description": "Optional description"
    }
  ]
}

フォルダ検索 (search folder)

{
  "status": "success",
  "command": "search folder",
  "data": [
    {
      "number": 1,
      "uid": "folder_uid_string",
      "name": "Matching Folder"
    }
  ]
}

レコード取得 (get)

{
  "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"
}

フォーマット指定ありのコマンド (例: audit-report --format=json)

{
  "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を使用するには、まず 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アドレスまたは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のいずれかである必要があります (大文字と小文字は区別されません)

複数のAPIトークンのサポート

ボルトに保存された 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: ''
tls_certificate: n
certfile: ''
certpassword: ''
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 をインストールします。
リポジトリのクローンを作成します。
docker build -t keeper-commander .コマンドを使用してDockerイメージをビルドします。
作成されたDockerイメージ (docker images) を確認します。
ターミナルウィンドウで2つの環境変数を設定します。
1. KEEPER_USERNAME: Keeperコマンダーにログインするためのユーザー名です。
2. KEEPER_PASSWORD: 上記のユーザーのマスターパスワードです。

以下のコマンドを使用してkeeper-commander dockerイメージを実行します。

docker run -d -p <port>:<port> keeper-commander \ 
  service-create -p <port> -f <file-format-YAML-or-JSON> -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をバックグラウンドで中断なく実行するために必要であり、繰り返しのログインを省略してシームレスに認証を行えます。

永続ログインセッションの詳細については、こちらのページをご覧ください。

ログ

このサービスには、以下の内容を追跡する包括的なログシステムが含まれています。

サービスの起動と終了イベント
構成の変更
APIの実行
セキュリティイベント
エラー状態

構成:

サービスモードが開始されると、デフォルトのパス (~/.keeper) にlogging_config.yamlが生成され、ログレベルはデフォルトでINFOに設定されます。

ユーザーは、以下のように設定することでログ機能を無効にしたり、ログレベル (INFO、DEBUG、ERROR) を変更したりできます。

logging:
  enabled: true
  level: INFO

サポート

サポートや機能のリクエストについては、下記までお問い合わせください。

commander@keepersecurity.com

コマンダーのサービスモードに関して、追加機能やセットアップガイドのご要望がございましたら、お気軽にお問い合わせください。

前へ自動実行次へトラブルシューティング

最終更新 6 日前