keeper-secrets

Keeper Secrets Manager CLI (ksm)

KSM CLI は、Keeper のマシン向けシークレット管理ツールです。Keeper Vault からシークレットを取得する際に、完全なユーザーログインは不要です。ワンタイムアクセストークンを使った Application + Client Device 認証を使用します。

公式ドキュメント

• Secrets Manager (KSM) - 概要、インストール、設定
• Keeper notation - フィールド、カスタムフィールド、ファイル向けの keeper:// URI 構文

KSM と Commander の使い分け

必要な操作	ツール
シークレット（パスワード、キー、証明書）を取得する	ksm
実行時にシークレットを環境変数に注入する	ksm exec
シークレットを設定ファイルにテンプレートとして埋め込む	ksm interpolate
アプリと共有されているレコードを一覧表示／検索する	ksm secret list
シークレットレコードを作成または更新する	ksm secret add / ksm secret update
シークレットを AWS/Azure のシークレットストアに同期する	ksm sync
安全なパスワードを生成する	ksm secret password
管理タスク（ユーザー、チーム、ロール、SSO）	keeper（Commander）を使用します。keeper-admin スキルを参照してください
KSM Applications または Client Devices を作成する	keeper（Commander）を使用します。keeper-admin スキルを参照してください
PAM リソースまたはローテーションを管理する	keeper（Commander）を使用します。keeper-admin スキルを参照してください

前提条件

1. KSM CLI がインストールされていること：pip install keeper-secrets-manager-cli（または GitHub リリースのバイナリ）
2. Keeper Vault（または Commander）で KSM Application が作成されていること
3. ワンタイムアクセストークンで Client Device が初期化されていること

インストールを確認します：ksm version

ワークフロー

1. KSM 関連のすべての操作には、必ず専用の TMUX セッションを使用してください。
2. KSM を初めて設定するときは、KSM init コマンドを事前に設定し、ワンタイムトークンをユーザーに入力してもらい、事前設定した tmux セッションに渡してください。
3. 必須フィールドの入力は必ずユーザーに求めてください。必須フィールドの値を推測してはいけません。
4. まずメタデータを検索または確認してから、要求されたフィールドだけを取得してください。機密データを公開しないでください。
5. シークレットをディスクに書き込むより、シークレットの注入や単一コマンドの実行時に限定した環境変数の設定を優先してください。
6. 構文が想定と異なる場合は、すぐに --help と Keeper のドキュメントを確認してください。
7. 削除操作を行う場合は、必ずユーザーに確認してください。

必須の tmux セッション

シェルツールはコマンドごとに新しい TTY を使用します。Keeper の対話型コンテキスト、認証状態、MFA プロンプトを維持するため、対話型の Keeper コマンドや Secrets Manager コマンドは専用の tmux セッション内で実行してください。

実行例：

SOCKET_DIR="${TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/keeper-tmux-sockets}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/keeper-commander.sock"
SESSION="keeper-auth-$(date +%Y%m%d-%H%M%S)"

tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "ksm shell || bash" Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -120

その後、セッションを慎重に操作します：

tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -l -- "whoami"
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -120

ユーザーが Keeper シェルの永続利用を希望しない限り、タスク完了後に tmux セッションを終了してください。

認証とプロファイルの設定

KSM はプロファイルベースの認証を使用します。keyring サポート付きでインストールした場合、認証情報はデフォルトで OS 標準のセキュアストレージ（macOS Keychain、Windows Credential Manager、Linux Secret Service）に保存されます。

# Install with keyring support (recommended)
pip install keeper-secrets-manager-cli[keyring]

# Initialize with One-Time Access Token (set KSM_CLI_TOKEN in your shell first—see Keeper profile docs; do not pass --token with a literal value)
ksm profile init

# For containers/CI (no keyring available)
pip install keeper-secrets-manager-cli
# Prerequisite: export KSM_CLI_TOKEN from a trusted source, then:
ksm profile init
# Creates keeper.ini with 0600 permissions

# Auto-create profile from environment variable (containers; see Keeper docs)
ksm secret list  # When KSM_TOKEN is set, profile may be auto-created on first use

複数のプロファイル

ksm profile list
# After exporting KSM_CLI_TOKEN for each setup step:
ksm profile init --profile production
ksm profile init --profile staging
ksm secret list --profile production

環境変数

変数	用途
KSM_CLI_TOKEN	--token を指定せずに ksm profile init を実行するためのワンタイムアクセストークン（推奨）
KSM_TOKEN	一部のコンテナ環境での自動初期化用ワンタイムアクセストークン（Keeper のドキュメントを参照）
KSM_CONFIG	Base64 設定文字列（K8s/コンテナ用）
KSM_CONFIG_FILE	keeper.ini へのパス
KSM_CLI_PROFILE	アクティブなプロファイル名
KSM_HOSTNAME	Keeper ホスト（US、EU、AU、JP、CA、US_GOV）

主なコマンド

シークレットの一覧表示

ksm secret list
# Output:
# UID                     Record Type          Title
# ----------------------- -------------------- -------------------------
# SNzjw8tM1HsXEzXERCJrNQ login                Stripe API Key
# 8f8I-OqPV58o2r91wVgZ_A databaseCredentials  Production MySQL Database

シークレットの取得

# Get full record as JSON
ksm secret get -u <RECORD_UID> --json

# Get a specific field value
ksm secret get -u <RECORD_UID> -f password
ksm secret get -u <RECORD_UID> -f login

# Get with JSONPath query
ksm secret get -u <RECORD_UID> --json -q '$.fields[[email protected]=="password"].value[0]'

# Get by title
ksm secret get -t "Production MySQL Database" -f password

# Remove surrounding quotes from output (useful for scripting)
ksm secret get -u <RECORD_UID> -f password --raw

Keeper Notation

Keeper Notation は、レコード内の特定のフィールドを参照するための URI 形式です。構文と動作の詳細については、Keeper notation のドキュメントを参照してください。

形式：keeper://<RECORD_UID>/field/<FIELD_TYPE> または keeper://<RECORD_UID>/custom_field/<LABEL>

keeper://SNzjw8tM1HsXEzXERCJrNQ/field/login
keeper://SNzjw8tM1HsXEzXERCJrNQ/field/password
keeper://8f8I-OqPV58o2r91wVgZ_A/field/host
keeper://8f8I-OqPV58o2r91wVgZ_A/custom_field/ConnectionString

Notation の構文全体については、references/keeper-notation.md を参照してください。

環境変数にシークレットを注入する（ksm exec）

シークレットを使ってアプリケーションを実行する際の基本的なパターンです。keeper:// で始まる環境変数は、コマンドの実行前にシークレットの値に置き換えられます。

# Single secret
export DB_PASSWORD="keeper://8f8I-OqPV58o2r91wVgZ_A/field/password"
ksm exec -- myapp

# Inline
DB_PASSWORD="keeper://8f8I-OqPV58o2r91wVgZ_A/field/password" \
API_KEY="keeper://SNzjw8tM1HsXEzXERCJrNQ/field/password" \
ksm exec -- ./start_server.sh

# Docker example
docker run \
  -e DB_PASSWORD="keeper://8f8I-OqPV58o2r91wVgZ_A/field/password" \
  -e KSM_CONFIG="<base64-config>" \
  myimage ksm exec -- /app/start.sh

シークレットを設定ファイルに補間する

# Replace keeper:// placeholders in a template file
ksm interpolate --in-file config.tmpl --out-file config.yaml

# Example template (config.tmpl):
# database:
#   host: keeper://8f8I-OqPV58o2r91wVgZ_A/field/host
#   password: keeper://8f8I-OqPV58o2r91wVgZ_A/field/password

シークレットを作成・更新する

# Create from editor
ksm secret add editor --record-type login --title "New API Key"

# Create from field arguments (supply sensitive field values from secure input, not sample literals)
ksm secret add field --record-type login --title "New API Key" \
  --field "login=admin"

# Update a field (use secure input for password fields)
ksm secret update -u <RECORD_UID> --field "login=newuser"

# Delete a record
ksm secret delete -u <RECORD_UID>

パスワードを生成する

ksm secret password --length 32
ksm secret password --lc 8 --uc 8 -d 8 --sc 8

クラウドストアに同期する

# Sync to AWS Secrets Manager
ksm sync --type aws_sm --credentials <AWS_CREDS_RECORD_UID> \
  --map <KEEPER_UID>=<AWS_SECRET_NAME>

# Sync to Azure Key Vault
ksm sync --type azure_kv --credentials <AZURE_CREDS_RECORD_UID> \
  --map <KEEPER_UID>=<AZURE_SECRET_NAME>

フォルダー管理

ksm folder list
ksm folder get -u <FOLDER_UID>

ガードレール

• シークレットの値をチャット、コードコメント、コミットメッセージに貼り付けたり、表示したり、ログに記録したりしないでください。
• シークレットをディスクに書き込んだり、ソースコードに埋め込んだりする代わりに、必ず ksm exec または ksm interpolate を使用してください。
• 認証エラーでコマンドが失敗した場合は、新しいワンタイムアクセストークンを使ってプロファイルを再初期化してください。
• - で始まるレコード UID の前には -- を付けてください。 ksm secret get -- -AbCdEfGh
• 機密レコードを参照するコマンドでは、破壊的な操作（削除、更新）を実行する前に、ユーザーに操作を確認してください。

よくあるパターン

CI/CD パイプライン（GitHub Actions）

env:
  KSM_CONFIG: ${{ secrets.KSM_CONFIG }}
steps:
  - run: pip install keeper-secrets-manager-cli
  - run: |
      DB_PASSWORD="keeper://<UID>/field/password" \
      ksm exec -- ./deploy.sh

Docker / Kubernetes

# Pass base64 config as env var
kubectl create secret generic ksm-config \
  --from-literal=config=<BASE64_CONFIG>

# In pod spec, mount KSM_CONFIG and use ksm exec as entrypoint

ローカル開発

# One-time setup
pip install keeper-secrets-manager-cli[keyring]
# Prerequisite: export KSM_CLI_TOKEN, then:
ksm profile init

# Daily use - run your app with secrets injected
DB_URL="keeper://<UID>/field/url" \
API_KEY="keeper://<UID>/field/password" \
ksm exec -- npm run dev