Dockerによるデプロイ

Dockerを使用したコマンダーのサービスモードデプロイ

Dockerによるコマンダーサービスモードのデプロイ

Dockerコンテナを使用すると、自動デバイス登録および永続的なログイン設定を備えたKeeperコマンダーのサービスモードを、簡単にデプロイできます。

クイックセットアップコマンド

アカウントでKeeperPAMまたはKeeperシークレットマネージャー (KSM) が有効になっている場合は、Keeperコマンダーの service-docker-setup コマンドを使用して、Dockerデプロイのセットアップ全体を自動化できます。このコマンドでは、デバイス登録、ボルトの構成、KSM連携、docker-composeファイルの生成までを、単一の対話型ワークフローでまとめて行えます。

スムーズにセットアップを行うには、service-docker-setup の使用を推奨します。手動で構成したい場合や、KSMが有効になっていない場合は、以下の認証方法の項をご参照ください。

要件

• Dockerをインストールしていること

• Dockerイメージを取得していること

  docker pull keeper/commander:latest

• アカウントでKeeperシークレットマネージャー (KSM) が有効になっていること

• Keeperコマンダーがローカル環境にインストールされていること

概要

service-docker-setup コマンドでは、以下の処理が自動的に実行されます。

デバイスのセットアップ

• デバイスをKeeperに登録

• 永続的なログインを有効化

• ログアウトのタイムアウトを30日に設定

ボルトの構成

• 共有フォルダを作成 (Commander Service Mode - Docker)

• 構成レコードを作成 (Commander Service Mode - Docker Config)

• 最小化された config.json を添付ファイルとしてアップロード

KSM連携

• KSMアプリケーションを作成 (Commander Service Mode - Docker App)

• 共有フォルダをKSMアプリと共有 (編集権限付き)

• クライアントデバイスを作成し、KSM構成を生成

Docker Composeの生成

• サービス構成 (ポート、コマンド、キューモード、トンネリング、TLS) を対話形式で指定

• そのまま利用できる docker-compose.yml ファイルを生成

使用方法

Keeperコマンダーのシェル内で、以下のコマンドを実行します。

service-docker-setup

slack-app-setup、teams-app-setup、service-docker-setup コマンドでは、認証情報がローカルの config.json に保存されている必要があります。

OSのキーチェーンに認証情報が保存されている状態では、これらのコマンドは動作しません。先に keeper shell --config-file でコマンダーを起動するか、login --config-file でログインしてから、コマンドを再実行してください。

エラーの例

My Vault> slack-app-setup
slack-app-setup: Error: This command requires credentials to be stored in config.json, but they are currently stored in the OS keychain.

Please re-login with the --config-file flag first:

   login --config-file    (or: keeper shell --config-file)

Then re-run this command.

オプションのパラメータ

パラメータ

説明

既定値

--folder-name	共有フォルダの名前	Commander Service Mode - Docker
--app-name	KSMアプリケーションの名前	Commander Service Mode - Docker App
--record-name	構成レコードの名前	Commander Service Mode - Docker Config
--config-path	config.jsonファイルのパス	~/.keeper/config.json
--timeout	デバイスのタイムアウト設定	30d
--skip-device-setup	すでに構成済みの場合にデバイス登録をスキップ	false

対話型構成

このコマンドでは、以下の構成項目について対話形式で設定を行います。

サービス構成

• ポート コマンダーサービスが待ち受けるポート番号を指定します (既定値: 8900)。

• コマンド 実行を許可するコマンドまたはエイリアスを、カンマ区切りで指定します (既定値: tree,ls)。

• キューモード パフォーマンス向上のため、非同期API (v2) を有効にするかどうかを指定します (既定値: 有効)。

-ur フラグを指定すると、APIキーとサービスURLが構成レコードに保存されます。コンテナを再起動するたびに、同じキーがレコードから読み戻され、再生成されません。すでに連携済みのアプリは、docker compose down / up のサイクルをまたいで引き続き動作します。

トンネリングオプション (任意)

• Ngrok ngrokを使用して公開URLを生成します。

  • Ngrok認証トークン

  • Ngrokカスタムドメイン (任意)

• Cloudflare ngrokを無効にしている場合に、Cloudflareを使用して公開URLを生成します。

  • Cloudflareトンネルトークン

  • Cloudflareカスタムドメイン

出力

コマンドが正常に完了すると、以下の情報が表示されます。

作成されたリソース

• 共有フォルダUID

• KSMアプリUID

• 構成レコードUID

• KSM Base64構成 (Dockerの環境変数用)

生成されたファイル

• docker-compose.yml: そのままデプロイに使用できるDocker Compose構成ファイル

docker-compose.yml の出力例

services:
  commander:
    container_name: keeper-service
    image: keeper/commander:latest
    environment:
      KSM_CONFIG: <base64-encoded-ksm-config>
      COMMANDER_RECORD: <config-record-uid>
    ports:
      - "8900:8900"
    command: service-create -p 8900 -c 'tree,ls' -f json -q y -ur $COMMANDER_RECORD \
    --ksm-config $KSM_CONFIG --record $COMMANDER_RECORD
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8900/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    restart: unless-stopped

セキュリティに関する推奨事項

本番環境へDockerデプロイを移行する前に、docker-compose.yml 内の service-create コマンドに以下のフラグを追加して強化することを推奨します。

• -rl <RATE> (--ratelimit): 単一の呼び出し元からのAPIアクセス速度の制限 (例: -rl 60/minute、1000/hour)。APIキーに対する総当たり攻撃や、連携アプリからの過剰リクエストの抑止

• -te <PERIOD> (--token_expiration): 発行するAPIトークンへの有効期限の設定 (例: -te 24h、7d)。基盤となるAPIキーが有効なままでも、漏えいしたトークンの影響範囲の限定

• -aip <CIDR-LIST> (--allowedip): 呼び出し元を既知の送信元範囲への限定 (例: -aip '10.0.0.0/8,192.168.1.0/24')。範囲外からのトラフィックの拒否

強化したコマンドの例

command: service-create -p 8900 -c 'tree,ls' -f json -q y -rl 60/minute -te 24h -aip '10.0.0.0/8,192.168.1.0/24' -ur $COMMANDER_RECORD --ksm-config $KSM_CONFIG --record $COMMANDER_RECORD

連携アプリのトラフィック特性に合った値を選んでください。制限が厳しすぎると、正当な呼び出しも拒否されます。

サービスのデプロイ

コマンドが正常に完了したら、以下の手順を実行することを推奨します。

1. コマンダーのセッションを終了: quit

2. 競合を防ぐため、ローカルの構成ファイルを削除: rm ~/.keeper/config.json

3. Dockerが稼働しているリモートサーバーでサービスを起動: docker compose up -d

4. デプロイを確認: docker ps、docker logs keeper-service、curl http://localhost:8900/health

コマンドの再実行

service-docker-setup コマンドを複数回実行した場合の動作は以下のとおりです。

• 既存のボルトリソース (フォルダ、アプリ、レコード) は再利用されます。

• config.json の添付ファイルが更新されます。

• 新しいKSMクライアントデバイスが作成されます。

• docker-compose.yml ファイルが再生成されます。

コンテナ再起動時のAPIキーの永続化

コンテナは、APIキーを構成レコード上の永続的な状態として扱います。

• 初回起動: 新しいキーの生成と、レコード (api_key カスタムフィールド) への保存

• 2回目以降の再起動: レコードから同じキーの読み戻しと再利用。新しいキーは生成せず、連携済みアプリ (Slack、Teams、カスタムREST呼び出し元) は再構成なしで動作継続

• ローテーションを強制する場合: 次回再起動前に、構成レコードから api_key カスタムフィールドを削除。コンテナは新しいキーを生成して書き戻し

レコード自体が削除されている場合、コンテナは初回起動時と同様に新しいキーを生成します。

---

手動Dockerセットアップ

手動で構成したい場合や、KSMが有効になっていない場合は、Dockerコンテナで以下の4つの認証方法を利用できます。

1. KSM構成ファイルを使用する

Keeperシークレットマネージャー (KSM) の構成ファイルを利用して、Keeperレコードから config.json を取得する方法です。コンテナ側では次の処理が行われます。

• マウントしたKSM構成ファイルを使用して、指定したレコードに添付されている config.json を取得する

• 取得した構成ファイルを使用してコマンダーの認証を行う

アプローチは2種類あります。

• KSM構成をBase64形式で渡す

• ksm-config.json ファイルをコンテナへマウントする

2. KSMトークンを使用する

Keeperシークレットマネージャーのワンタイムアクセストークンを利用して、Keeperレコードから config.json 構成ファイルを取得する方法です。コンテナでは以下の処理が行われます。

• 指定したKSMトークンを使用してレコードから config.json を取得する

• 取得した構成ファイルを使用してコマンダーの認証を行う

3. 認証情報を使用する

コマンドライン引数として資格情報を直接渡す方法です。コンテナは次の処理を自動で実行します。

• Keeperへのデバイス登録

• 永続ログインの有効化

• サービスの起動

4. 構成ファイルを使用する

既存のKeeper構成ファイルをコンテナにマウントして使用します。

一般的な構成ファイルの準備手順

KSM構成ファイル方式、KSMトークン方式、構成ファイル方式を利用する場合は、事前に config.json をボルトにアップロードする必要があります。ホスト環境で以下の手順を実行してください。

1. Keeperへのログイン

   keeper shell
   # 認証情報を使用してログイン
   login [e-mail]

2. デバイス登録

   this-device register

3. 永続ログインの有効化

   this-device persistent-login on

4. タイムアウトの設定

   this-device timeout 43200

5. 構成ファイルのアップロード ホストの .keeper ディレクトリにある config.json を見つけ、共有フォルダ内のレコードに添付ファイルとしてアップロードします。

6. 元の構成ファイルの削除 同じデバイストークンやクローンコードを持つ構成が重複しないよう、ホスト環境の .keeper ディレクトリから config.json を削除します。

重要な注意事項

config.json をアップロードした後は、同じKeeperアカウントを他のコマンダーのセッションや環境で使用しないでください。 同じKeeperアカウントを使用するとクローンコードが再生成され、コンテナ環境や自動化環境における認証フローに支障が生じることがあります。

Dockerコンテナの実行

KSM構成ファイル認証を使用する場合

A. Base64形式のKSM構成を使用する

ファイルのマウントが難しい環境 (例: コンテナオーケストレーション環境) では、KSM構成をBase64エンコードした文字列として渡す方法が利用できます。

要件

KSM構成ファイル認証を使用する前に、以下を完了しておく必要があります。

1. KSMアプリケーションをKeeperボルト内で作成する

2. KSM構成のBase64値を生成する

3. サービス用 config.json 構成ファイルを添付したKeeperレコードを作成する

4. そのレコードをKSMアプリケーションと共有する

セットアップ手順

1. 一般的な構成ファイルの準備手順を完了する

2. KSM構成ファイルの作成

   • ボルト → [シークレットマネージャー] → [アプリケーション] へ移動する

   • 新しいアプリケーションを作成し、共有フォルダへのアクセス権を付与する

   • アプリケーションを選択し、[デバイス] から [デバイスを追加] をクリックする

   • 構成ファイル方式を選択し、構成タイプとして Base64 を指定する

   • 表示されたKSM構成のBase64文字列を安全な場所にコピーして保管する

Docker Composeファイル

services:
    commander:
        ports:
            - <port>:<port>
        image: keeper/commander:latest
        command: service-create -p <port> -c '<commands>' -f <json-or-yaml> 
            --ksm-config <BASE64_ENCODED_CONFIG> 
            --record <RECORD_UID_OR_TITLE>

Dockerの実行

docker run -d -p <port>:<port> \
  keeper/commander:latest \
  service-create -p <port> -c '<commands>' -f <json-or-yaml> \
  --ksm-config <BASE64_ENCODED_CONFIG> \
  --record <RECORD_UID_OR_TITLE>

例

docker run -d -p 9007:9007 \
  keeper/commander:latest \
  service-create -p 9007 -c 'ls,tree' -f json \
  --ksm-config eyJhcHBsaWNhdGlvbiI6ZXN0LWNsaWVudC1pZCJ9 \
  --record ABC123-DEF456-GHI789

--record パラメータには、レコードのUIDとタイトルの両方を指定できます。同じタイトルのレコードが複数存在する場合は、UIDを指定する必要があります。

B. KSM構成ファイルをコンテナ内にマウントする方法

要件

KSM構成ファイルによる認証を利用するには、次の準備が必要です。

1. KeeperボルトでKSMアプリケーションを作成する

2. KSM構成ファイル (ksm-config.json) を生成する

3. サービスの config.json を添付したKeeperレコードを作成する

4. そのレコードを作成したKSMアプリケーションと共有する

手順

1. 一般的な構成ファイル準備手順を完了する

2. KSM構成ファイルを作成する

• ボルト → [シークレットマネージャー] → [アプリケーション] へ移動する

• 新しいアプリケーションを作成し、共有フォルダへのアクセス権を付与する

• 作成したアプリケーションを選択し、[デバイス] へ移動してから [デバイスを追加] をクリックする

• 構成ファイル方式を選択してJSONファイルをダウンロードする

• ダウンロードしたファイルの名前を ksm-config.json に変更する (.keeper/config.json との衝突を避けるため)

Docker Composeファイル

services:
    commander:
        ports:
            - <port>:<port>
        volumes:
            - /path/to/local/ksm-config.json:/home/commander/ksm-config.json
        image: keeper/commander:latest
        command: service-create -p <port> -c '<commands>' -f <json-or-yaml> 
            --ksm-config /home/commander/ksm-config.json 
            --record <RECORD_UID_OR_TITLE>

Dockerの実行

docker run -d -p <port>:<port> \
  -v /path/to/local/ksm-config.json:/home/commander/ksm-config.json \
  keeper/commander:latest \
  service-create -p <port> -c '<commands>' -f <json-or-yaml> \
  --ksm-config /home/commander/ksm-config.json \
  --record <RECORD_UID_OR_TITLE>

例

docker run -d -p 9007:9007 \
  -v /path/to/local/ksm-config.json:/home/commander/ksm-config.json \
  keeper/commander:latest \
  service-create -p 9007 -c 'ls,tree' -f json \
  --ksm-config /home/commander/ksm-config.json \
  --record ABC123-DEF456-GHI789

--record パラメータには、レコードのUIDとタイトルの両方を指定できます。同じタイトルのレコードが複数存在する場合は、UIDを指定する必要があります。

KSMトークン認証を利用する方法

要件

KSMトークン認証を利用する前に、次の準備が必要です。

1. KeeperボルトでKSMアプリケーションを作成する

2. 生成されたアクセストークンを安全に保管する

3. config.json を添付したKeeperレコードを作成する

4. そのレコードを作成したKSMアプリケーションと共有する

手順

1. 一般的な構成ファイルの準備手順を完了する

2. KSMアクセストークンを作成する

1. ボルト → [シークレットマネージャー] → [アプリケーション] へ移動する

2. 新しいアプリケーションを作成し、共有フォルダへのアクセス権を付与する

3. 編集権限を付与し、アクセストークンを生成する

4. 生成されたアクセストークンを安全に保管する

Docker Composeファイル

services:
    commander:
        ports:
            - <port>:<port>
        image: keeper/commander:latest
        command: service-create -p <port> -c '<commands>' -f <json-or-yaml> 
            --ksm-token <KSM_TOKEN> 
            --record <RECORD_UID_OR_TITLE>

Dockerの実行

docker run -d -p <port>:<port> \
  keeper/commander:latest \
  service-create -p <port> -c '<commands>' -f <json-or-yaml> \
  --ksm-token <KSM_TOKEN> \
  --record <RECORD_UID_OR_TITLE>

例

docker run -d -p 9007:9007 \
  keeper/commander:latest \
  service-create -p 9007 -c 'ls,tree' -f json \
  --ksm-token US:odncsdcindsijiojijj32i3ij2iknm23 \
  --record ABC123-DEF456-GHI789

--record パラメータには、レコードのUIDとタイトルの両方を指定できます。同じタイトルのレコードが複数存在する場合は、UIDを指定する必要があります。

ユーザー名/パスワード認証方式

パラメータ

• -p, --port: サービスのポート番号

• -c, --commands: 許可コマンドのカンマ区切りリスト

• -f, --fileformat: 構成ファイル形式 (jsonまたはyaml)

• --user: Keeperユーザー名

• --password: Keeperパスワード

• --server: Keeperサーバー (省略時は keepersecurity.com)

Docker Composeファイル

services:
    commander:
        ports:
            - <port>:<port>
        image: keeper/commander:latest
        command: service-create -p <port> -c '<commands>' -f <json-or-yaml> 
            --user <keeper-username> 
            --password <keeper-password>
            --server <keeper-server>

Dockerの実行

docker run -d -p <port>:<port> keeper/commander:latest \
  service-create \
  -p <port> \
  -c '<comma-separated-commands>' \
  -f <json-or-yaml> \
  --user <keeper-username> \
  --password <keeper-password> \
  --server <keeper-server>

例

docker run -d -p 9009:9009 keeper/commander:latest \
  service-create \
  -p 9009 \
  -c 'tree,ls' \
  -f json \
  --user [e-mail] \
  --password mypassword

構成ファイル認証方式

要件

構成ファイル認証を利用するには、ホスト側で config.json を正しく構成しておく必要があります。

手順

1. 一般的な構成ファイルの準備手順の1〜4を実行する

2. 構成が完了したら、ホストマシンの .keeper フォルダにある config.json を確認し、Dockerでマウントできるように、その内容を任意のパス (例: /path/to/local/config.json) にコピーする

3. コピーが完了したら、デバイストークンやクローンコードの重複を防ぐため、ホストマシンの .keeper フォルダから元の config.json を削除する

構成ファイルをマウントして実行

Docker Composeファイル

services:
    commander:
        ports:
            - <port>:<port>
        volumes:
            - /path/to/local/config.json:/home/commander/.keeper/config.json
        image: keeper/commander:latest
        command: service-create -p <port> -c '<commands>' -f <json-or-yaml>

Dockerの実行

docker run -d -p <port>:<port> \
  -v /path/to/local/config.json:/home/commander/.keeper/config.json \
  keeper/commander:latest \
  service-create -p <port> -c '<commands>' -f <json-or-yaml>

デプロイの確認

コンテナの状態を確認する

docker ps

コンテナログの確認

docker logs <container-name-or-id>

APIキーの取得

APIキーは、Keeperボルト内に安全に保存されます。Dockerのログでは、セキュリティ上の理由からキーの一部がマスク表示されます。

Generated API key: ****nQ= (stored in vault record: <CONFIG_RECORD_UID>)

完全なAPIキーを取得するには、以下の手順を行います。

• Keeperボルトを開きます。

• 「Commander Service Mode - Slack App」 フォルダに移動します。

• 「Commander Service Mode Slack App Config」 レコードを開きます。

• api-keyフィールドを確認します。

リアルタイムでログを確認する

docker logs -f <container-name-or-id>

コンテナのアーキテクチャ

• ベースイメージ: python:3.11-slim

• ワーキングディレクトリ: /commander

• 構成ファイルディレクトリ: /home/commander/.keeper/

• Entrypoint: docker-entrypoint.sh (自動認証セットアップを実行)

コマンダ実行API エンドポイント

# キューを有効化した場合 (v2 - 非同期)
curl --location 'http://localhost:<port>/api/v2/executecommand-async' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
   "command": "<command>"
}'

# キューを無効化した場合 (v1 - 直接)
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
this-device timeout 43200

上記のタイムアウト設定を適用すると、30日間 (43200分) はコマンダーで認証を求められずに利用できます。ログイン状態の維持は、サービスモードAPIをバックグラウンドで継続して実行するために必要で、ログイン要求なしでシームレスに認証できます。

ログイン状態維持セッションについて、詳しくはこちらのページをご覧ください。

ログ記録

サービスには包括的なログ記録機能があり、以下の項目が記録されます。

• サービスの起動と停止

• 構成変更

• API実行

• セキュリティ関連イベント

• エラー状況

ログ構成

サービスモードを開始すると、logging_config.yaml がデフォルトパス (~/.keeper) に生成されます。デフォルトのログレベルは INFO です。ログを無効にする場合は enabled: false に変更します。ログレベルを変更する場合は level に INFO、DEBUG、ERROR のいずれかを指定します。

   logging:
     enabled: true
     level: INFO

バックグラウンドプロセスのログ

バックグラウンドモードで実行されている場合、サービスログは以下に保存されます。

• 場所: keepercommander/service/core/logs/service_subprocess.log

• 内容: サブプロセスの出力、エラー、サービスイベント

• 自動作成: サービスがバックグラウンドで開始されると自動的に作成される

Ngrokログ

ngrokトンネリングが有効になっている場合、追加ログが記録されます。

• 場所: keepercommander/service/core/logs/ngrok_subprocess.log

• 内容: ngrokの起動、接続イベント、パブリックURL生成、トンネルエラー

• 含まれる情報: トンネル確立、再接続試行、ngrok固有のエラーメッセージ

• 自動作成: ngrokトンネリングを構成してサービスを開始すると自動的に作成される

Cloudflareログ

Cloudflareトンネリングが有効になっている場合、追加ログが記録されます。

• 場所: keepercommander/service/core/logs/cloudflare_tunnel_subprocess.log

• 内容: Cloudflareトンネルの起動、接続イベント、パブリックURL生成、トンネルエラー

• 含まれる情報: トンネル確立、再接続試行、Cloudflare固有のエラーメッセージ

• 自動作成: Cloudflareトンネリングを構成してサービスを開始すると自動的に作成される