interpolateコマンド

テンプレート内Keeper表記法の、ボルト上シークレット実値への置換

interpolate コマンド

説明: テンプレートに書かれたKeeper表記法を、ボルト上のシークレット実値に置き換えます。interpolate コマンドは表記法の参照を含むファイルを読み、ボルトから値を取り出して参照を実値に差し替えます。デプロイやCI/CD、シェル用の環境変数ファイルなど、安全に構成ファイルを用意する用途向けです。

パラメータ:

format: ksm interpolate [INPUT_FILE...] [OPTIONS]

オプション:

オプション	短縮形	説明
INPUT_FILE		入力テンプレート。未指定時は標準入力から読み取り
--output-file PATH	-o	標準出力ではなく指定ファイルへ書き出し
--in-place	-w	インプレース編集 (元ファイルを上書き)
--backup-suffix SUFFIX	-b	-w 使用時のバックアップ拡張子 (既定: .bak)
--dry-run	-n	変更せず置換内容のみ表示
--verbose	-v	置換ごとの詳細出力
--continue	-C	エラーが出ても処理継続
--validate		表記法がすべて解決済みであることの検証
--allow-unsafe-for-eval		[危険] eval / source 用にシェルメタ文字を含むシークレットを許可 (インジェクションリスクあり)

共通フラグ: --profile-name, --ini-file, --color/--no-color, --cache/--no-cache

---

Keeper表記法の形式

interpolate コマンドは、既定値や変換を伴う拡張Keeper表記法に対応します。

基本的な表記:

keeper://RECORD_UID/field/FIELD_NAME
keeper://RECORD_UID/custom_field/CUSTOM_FIELD_NAME
keeper://RECORD_UID/file/FILE_NAME

既定値付き（シェル風の :- 構文）:

keeper://RECORD_UID/field/FIELD_NAME:-default_value

変換付き（パイプ | 演算子）:

keeper://RECORD_UID/field/FIELD_NAME|transform
keeper://RECORD_UID/field/FIELD_NAME:-default|transform

利用できる変換: base64, base64url, urlencode, urlencodeplus, upper, lower, trim, sha256, md5

---

セキュリティ上の挙動

重大: シェルインジェクション対策

既定では、eval や source と併用したときのコマンドインジェクションを防ぐため、改行、バッククォート、$, ;, |, &, >, < などのシェルメタ文字を含むシークレットは受け付けません。

安全な使い方:

1. 推奨: ファイルへ書き出してから source する。

   ksm interpolate secrets.env --output-file /tmp/secrets.env
   source /tmp/secrets.env && rm /tmp/secrets.env

2. 危険: Keeperへの書き込み権限を持つユーザーをすべて信頼できる場合に限り、--allow-unsafe-for-eval を使う。

   eval "$(ksm interpolate secrets.env --allow-unsafe-for-eval)"

その他のセキュリティ機能:

• 出力ファイルは権限 0600 (所有者のみ読み書き)

• 原子書き込みで途中状態のファイルを避ける

• .gitignore に含まれないファイルに対するGitの警告

• パストラバーサル対策

---

例

基本的なファイル処理

テンプレート: config.env.template

# Database configuration
DB_HOST=keeper://MyDatabaseCreds/field/host
DB_PORT=keeper://MyDatabaseCreds/field/port
DB_PASSWORD=keeper://MyDatabaseCreds/field/password

# API configuration
API_KEY=keeper://ApiCredentials/custom_field/api_key

テンプレートを処理:

$ ksm interpolate config.env.template --output-file config.env

結果: config.env (権限 0600、所有者のみ読み書き)

# Database configuration
DB_HOST=db.example.com
DB_PORT=5432
DB_PASSWORD=MySecurePassword123

# API configuration
API_KEY=sk-1234567890abcdef

シェル組み込みコマンド

課題: ksm exec では source などのシェル組み込みコマンドは実行できません。

$ ksm exec -- source .env
Error: No such file or directory: 'source'

解決: 代わりに ksm interpolate を使います。

例1: ファイルへ書き出す (推奨)

$ ksm interpolate secrets.env --output-file /tmp/secrets.env
$ source /tmp/secrets.env
$ rm /tmp/secrets.env

例2: 直接 eval（--allow-unsafe-for-eval が必要）

$ eval "$(ksm interpolate secrets.env --allow-unsafe-for-eval)"

--allow-unsafe-for-eval は、Keeperへの書き込み権限を持つユーザーをすべて信頼できる場合にのみ使ってください。「セキュリティ上の挙動」をご参照ください。

既定値と変換

既定値と変換を含むテンプレート:

# Use production values if available, otherwise defaults
DB_HOST=keeper://ProdDB/field/host:-localhost
DB_PORT=keeper://ProdDB/field/port:-5432

# Base64-encoded JWT secret
JWT_SECRET=keeper://Auth/field/secret|base64

# URL-encoded callback parameter
CALLBACK_URL=keeper://Config/field/callback|urlencode

# Combined: default + transformation
ENCODED_KEY=keeper://API/field/key:-default_value|base64

実行例

$ ksm interpolate app.env.template --output-file app.env

シークレットが存在しないか参照できないときは、既定値が自動的に使われます。変換は取得値と既定値の両方に適用されます。

その他の使い方

標準入力から処理:

cat config.template | ksm interpolate > config.env

複数ファイルを処理:

ksm interpolate *.template

バックアップ付きインプレース編集:

ksm interpolate --in-place --backup-suffix .bak config.env

ドライラン (変更なしで内容確認):

ksm interpolate --dry-run --verbose production.env.template