kdbx

kdbx — AI エージェントに安全に渡せる、KeePassXC 保管庫でのプロジェクトごとのシークレット管理

kdbx は、プロジェクトごと、環境ごとの KeePassXC 保管庫 （KDBX4、キーファイルのみでロック解除。マスターパスワードは不要）にシークレットを保管し、 必要なツールに渡します。その際、kdbx がシークレットをトランスクリプト、ログファイル、 シェルの履歴に出力することはありません。 検出は自動です。kdbx は現在のディレクトリから上の階層へたどり、コミット済みの .keepassxc.json ポインターファイルを見つけると、有効な環境を特定して処理を進めます。 中心となるコマンドは kdbx run -- <cmd> です。有効な環境の変数マッピングを解決し、 子プロセスの環境に注入します。.env ファイルを信頼できる情報源として使う代わりに、 保管庫はリポジトリの外に置かれるため、シークレットを誤ってコミットする心配はありません。

以下のインストール方法はすべて利用可能です。curl インストーラー、Homebrew、go install、 ghcr.io コンテナーイメージ、署名済みリリースアーカイブ（SHA256SUMS と cosign、 再現可能なビルドを含む）に対応しています。上のバッジには現在のバージョンが表示されます。

インストール

# curl installer — downloads the release archive, verifies its SHA-256, installs to
# ~/.local/bin (override with KDBX_INSTALL_DIR; pin with KDBX_VERSION=v0.3.2)
curl -LsSf https://raw.githubusercontent.com/yarrasys/kdbx/main/install.sh | sh

brew install yarrasys/tap/kdbx                    # Homebrew
go install github.com/yarrasys/kdbx@latest        # from source, needs Go 1.26+
docker run --rm ghcr.io/yarrasys/kdbx:latest --version   # container (FROM scratch)

Windows の場合は、リリースページから _windows_ アーカイブをダウンロードし、kdbx.exe を PATH に配置します。

ソースからビルドするには、Go 1.26 以降が必要です。Go 1.27 のリリースに伴い Go 1.25 の サポートは終了しており、現在の golang.org/x/term リリースでは Go 1.26 以上が必要です。 リリースバイナリは静的リンクされているため、ユーザー側にツールチェーンは必要ありません。

シェル補完：

kdbx completion zsh  > "${fpath[1]}/_kdbx"
kdbx completion bash > /etc/bash_completion.d/kdbx
kdbx completion fish > ~/.config/fish/completions/kdbx.fish
kdbx completion powershell | Out-String | Invoke-Expression

クイックスタート

1. リポジトリのルートにポインターファイルをコミットします。 プロジェクトとその環境を 指定します。シークレットは含まれないため、安全にチェックインできます。

{
  "project": "demo",
  "defaultEnv": "dev",
  "envs": {
    "dev": {},
    "prod": {}
  }
}

env オブジェクトは空でもかまいません。kdbx はプロジェクト名と環境名からアーティファクトの パスを導き出します。<keepassxc-dir>/demo/dev.kdbx と <keepassxc-dir>/demo/dev.keyx です。 <keepassxc-dir> は、$KEEPASSXC_DIR が設定されていればその値、設定されていない場合は Windows では %LOCALAPPDATA%\keepassxc、それ以外では $XDG_CONFIG_HOME/keepassxc または ~/.config/keepassxc です。別の場所を使う場合は、vault と keyFile を明示的に設定します。 どちらにも ${KEEPASSXC_DIR} トークンと先頭の ~ を使用できます。

2. 保管庫とそのキーファイルを作成します。

$ kdbx init
ACTIVE ENV: dev  vault=/home/you/.config/keepassxc/demo/dev.kdbx  (source: pointer)
created /home/you/.config/keepassxc/demo/dev.kdbx
KEYFILE: /home/you/.config/keepassxc/demo/dev.keyx — back this up; losing it makes the vault unrecoverable.

3. シークレットを保存し、環境変数にマッピングします。 値はコマンドラインに表示されません。 標準入力、--from-env、または対話型プロンプトから渡されます。

$ kdbx set api/openai --var OPENAI_API_KEY < secret.txt
ACTIVE ENV: dev  vault=/home/you/.config/keepassxc/demo/dev.kdbx  (source: pointer)
modified tracked file .keepassxc.json — review and commit

--var はポインターファイルにマッピングを記録します。既存のキーの順序が保たれるため、 差分を確認しやすくなります。

"dev": {
  "vars": {
    "OPENAI_API_KEY": "api/openai"
  }
}

4. シークレットを注入してコマンドを実行します。

kdbx run -- claude              # the author's actual daily use
kdbx run -- npm test
kdbx --env prod run -- ./deploy.sh

子プロセスは、現在の環境にマッピングされた変数を加えた環境を引き継ぎます。終了コードは そのまま返されます。ディスクには何も書き込まれず、値がシェルの履歴に表示されることもありません。

読み取り操作はシンプルです。

$ kdbx list
api/openai
$ kdbx get api/openai
(set, hidden)
$ kdbx check          # every mapping still resolves → exit 0, no output
$ kdbx envs
* dev
  prod

操作

すべての操作で --env NAME を指定できます。読み取り操作では、さらに --json を指定できます。 ✦ の付いた操作は、標準エラー出力にバナー ACTIVE ENV: <env> vault=<path> (source: <src>) を出力します。表示のみを行う操作では出力しません。

操作	フラグ	動作（stdout／stderr／終了コード）
init ✦	--here、--mode standard|strict	Vault とキー ファイルを作成します。上位のどこにもポインタがない場合、または --here を指定した場合は、まず現在のディレクトリに新しい .keepassxc.json を書き込みます（プロジェクト名はそのディレクトリ名、環境は dev／prod、アクティブ環境は dev）。そのため、1 つのコマンドでプロジェクトを開始できます。別のプロジェクトのツリー内で通常の init を実行すると、使用するポインタファイルを名前付きで示し、先に確認を求めます（TTY のみ。そうでない場合は終了コード 4）。別のプロジェクトを開始する方法として --here を案内します。stderr に created <vault> とキー ファイルのバックアップに関する警告を出力します。既存の Vault、キー ファイル、ポインタは上書きしません。--mode はポインタ内に環境のポリシーを記録し、strict の場合は新しい Vault にアンカーします
policy bless ✦		ポインタの現在のポリシー（policy と run.allow セクション）を Vault にアンカーします。rekey と同様に対話型でのみ実行でき、ガードによってエージェントには拒否されます。アンカーが一致するまで、strict の run は拒否されます
set PATH ✦	--var NAME、--from-env VAR、--raw	値は --from-env から取得します。それ以外は、TTY の場合は確認を伴う対話型プロンプト、そうでない場合は stdin から取得します（空の場合はエラー。--raw を指定しない限り、末尾の改行を 1 つ削除します）。空または空白文字のみの値は拒否されます。--var はポインタファイルにマッピングを追加します
get PATH	--reveal | --clip	デフォルトでは (set, hidden) を出力します。長さやプレフィックスも漏えいしません。--reveal は stderr に警告を出して値を表示します。--clip は値をコピーし、約 15 秒後に自動消去します。エントリまたはフィールドがない場合は終了コード 2 です
list [GROUP]		group/…/title の行をソートして表示します。GROUP のプレフィックスで絞り込み、Recycle Bin は除外します。値は決して表示しません
delete PATH ✦	--purge	デフォルトでは Recycle Bin にソフト削除します。--purge は y/N の確認を求め（TTY のみ。非 TTY では終了コード 4 で拒否）、その後、完全に削除します
mv SRC DST ✦		エントリを移動または改名し、移動先のグループを作成します。SRC を参照していたアクティブ環境の var マッピングを付け替え、:field のサフィックスがあれば保持します。stderr に re-pointed N var mapping(s) … を出力します
run ✦	--allow-missing、--no-mask、--any、-- CMD…	ポインタに run.allow リストがある場合、Vault を開く前に、リストにないコマンドを拒否します（終了コード 7、NotAllowed）。ただし --any を指定した場合を除きます。アクティブ環境の vars マップを解決して子プロセスの環境に注入し、PATH（Windows では PATHEXT）を通じて argv[0] を解決し、シグナルを転送し、子プロセスの終了コードをそのまま返します。子プロセスのストリームがキャプチャされる場合（TTY ではない場合）、そこに含まれる 8 バイト以上の注入値は *** に置き換えます（--no-mask で無効化できます。ガードはエージェントに対してこれを拒否します）。コマンドがない場合は終了コード 2、未解決の var がある場合は --allow-missing を指定しない限り終了コード 5 です
export ✦	--out FILE、--allow-missing	マッピングを dotenv 形式で出力します（常に二重引用符で囲み、\、"、改行をエスケープします）。--out を指定した場合は、gitignore に関する注意を添えて 0600 でアトミックに書き込みます。それ以外の場合は stdout に出力します
import FILE ✦		dotenv ファイルを解析し（$VAR の補間は行いません）、各 KEY を imported/KEY に保存してマッピングを登録します。stderr で、元のファイルを削除するかキーをローテーションするよう注意を促します
check		マッピングが壊れている場合に MISSING VAR -> path を 1 件ずつ出力します。問題がなければ終了コード 0、不整合がある場合は 5 です
envs		環境ごとに 1 行ずつ表示し、アクティブな環境には * を付けます。stderr に active: <env> (source: <src>) を出力します。ポインタファイルがない場合は終了コード 2 です
rekey ✦		y/N の確認を求め（TTY のみ。そうでない場合は終了コード 4）、新しいキー ファイルを生成して Vault のキーを変更し、古いキー ファイルをアトミックに置き換えます。stderr で再配布を促します

統合インターフェース：

コマンド	用途
kdbx mcp	stdio 経由の読み取り専用 MCP サーバー（5 つのツール：kdbx_list、kdbx_envs、kdbx_check、kdbx_get、kdbx_run）
kdbx guard --hook pretooluse	stdin 上の PreToolUse フックのペイロードを評価し、人間のみが実行できる操作をエージェントによる実行から拒否します
kdbx completion <shell>	bash、zsh、fish、または powershell 用の補完スクリプトを出力します
kdbx --version	kdbx <version> を出力します

--json

--json を指定すると、読み取り操作の標準出力が機械可読形式になります。シークレットの値は含まれません。

$ kdbx --json list
{"entries":["api/openai"]}
$ kdbx --json envs
{"envs":[{"name":"dev","active":true}],"source":"pointer"}
$ kdbx --json check
{"missing":[],"ok":true}
$ kdbx --json get api/openai
{"path":"api/openai","set":true}

--reveal と併用した --json は拒否されます（終了コード 7）。失敗時は、通常の標準エラーの行と終了コードに加えて、標準出力に {"error":{"op":"check","exit":5,"kind":"Drift"}} が出力されます。

エントリパス

エントリパスは group/sub/Title[:field] です。フィールドの既定値は password です。予約済みのフィールド名（大文字と小文字を区別せずに照合）は、title、username、password、url、notes で、KeePass エントリのネイティブ属性に対応します。それ以外は保護されたカスタムプロパティになります。:`` が複数ある場合、:の後のフィールドが空の場合、または/ で区切られたセグメントが空の場合は拒否されます。--varに渡す変数名は^[A-Z_][A-Z0-9_]*$` に一致する必要があります。

環境の選択

--env は $KDBX_ENV より優先され、$KDBX_ENV はポインタの defaultEnv より優先されます。defaultEnv の既定値は dev です。kdbx envs とバナーには、3 つのうちどれが選択されたかが表示されます。ポインタファイルにない環境を指定するとエラーになります（終了コード 2）。

終了コード

コード	意味
0	成功
1	一般的な失敗（サニタイズ済み）
2	見つかりません — ポインタファイルがない、環境が不明、エントリまたはフィールドがない、run にコマンドが指定されていない
3	ロック中、キーファイルがない、または認証情報のエラー
4	破壊的な操作が確認されていない
5	ドリフト — check でマッピングの破損が見つかった、または run／export でマッピングを解決できなかった
6	書き込み中にボールトが変更されたため、再実行が必要
7	事前チェックで拒否（無効な --var 名、--json --reveal など）

失敗時は、標準エラーに必ず 1 行だけ出力し、スタックトレースやシークレットは出力しません。この行には、安定した種類と kdbx 独自のメッセージが含まれます。このメッセージにはシークレットの値が決して含まれないように記述されています。

$ kdbx get api/nope
kdbx: get failed: NotFound: entry not found: api/nope

このルールに準拠していないため、サードパーティー製ソフトウェアのエラー内容は表示されません。KDBX_DEBUG=1 を設定すると、完全なエラーチェーンとスタックも標準エラーに出力されます。

kdbx が読み取る環境変数：KDBX_ENV、KEEPASSXC_DIR、XDG_CONFIG_HOME、LOCALAPPDATA、KDBX_DEBUG。

ロール — エージェントは読み取り、人間は書き込みます

kdbx は、コーディングエージェントに安心して任せられるように設計されています。ルールは次のとおりです。

• エージェントが安全に使える操作： run、get（マスク済み）、list、check、envs、init。
• 人間のみが使える操作： set、delete、mv、import、rekey、export、および get --reveal / get --clip。

エージェントは認証情報を使用できます。たとえば kdbx run -- npm test は問題なく動作し、kdbx 自体が値を 出力することはありません。

これはガードレールであって境界ではありません。その理由を正確に理解しておくことが大切です。

バイナリは、この区分を強制しません。実際の境界となるのはキーファイルの所持です。キーファイルを読み取れるものは、誰であれ何であれ、保管庫を開けます。このロール区分は、フックに対応するハーネスでは kdbx guard によって強制され、それ以外の場所では助言として機能します。

必要であれば、実行する子コマンドを固定できます。.keepassxc.json にコミット済みの run.allow リストがあると、リストに完全一致する argv 以外は run が拒否します（人間は --any を渡せますが、ガードはエージェントに対して拒否します）。それによって何ができるのか、冷静に理解しておきましょう。エージェントは原理上、ポインターを編集できますが、ガードが明白な編集をブロックし、変更は見えない一行ではなく、追跡対象ファイル上の目に見える差分になります。リストがなければ、run は渡された任意の argv に値を注入します。

本番環境や実際の顧客認証情報など、慎重な運用が求められる環境向けに、strict モードがあります。kdbx init --mode strict で有効にできます。strict モードでは許可リストが必須となり、--any と --no-mask は無条件に拒否されます。すべての判断について、コマンドと変数の名前だけ（値は記録しません）を、保管庫の隣にある 0600 ファイルに監査ログとして記録します。また、注入を許可するには、kdbx policy bless で保管庫に登録されたポリシーハッシュが必要です。このコマンドは人間のみが実行でき、対話形式で動作します。ポリシーが範囲外で編集されていた場合、次の run では黙って従うのではなく、拒否されます。同じルールは MCP サーバーの kdbx_run にも適用されます。このツールは常にマスク処理を行い、例外手段は一切ありません。ユーザーと同じ uid を持つ、決意したエージェントなら、これらすべてを回避できます。strict モードによって変わるのは、密かな改ざんが表面化する点です。 出力がキャプチャされる場合（パイプ、エージェントのハーネス、ログなど）、そこに含まれる注入値は *** に置き換えられます。そのため kdbx run -- env では、値がトランスクリプトに記録されるはずだった箇所に、値ではなくマスクが表示されます。ターミナルには加工前の出力が表示されます。また、--no-mask（ガードによりエージェントには拒否されます）を使うと、人間がパイプ経由で使用する際にマスクを解除できます。マスキングの対象となるのは値と完全一致するものだけです。エージェントが出力時に値をエンコードすれば回避できますし、情報を持ち出すようにテストスクリプトを編集しても同様です。kdbx がシークレットを出力しないというのは、kdbx の特性であって、kdbx が動作するシステムの特性ではありません。

この区分によって実際に得られるのは、エージェントが別の作業中に誤って情報を漏らさず、認証情報を作成、ローテーション、エクスポートできないことです。読み取ろうと決めたエージェントを封じ込めるものではありません。それが必要なら、ユーザーとしてのエージェントが越えられない境界が必要です。別アカウント、コンテナー、またはキーを保持するブローカーなどが該当します。issue #11 を参照してください。

kdbx guard は PreToolUse ペイロードを標準入力から読み取り、拒否エンベロープを出力するか、何も出力しません。終了コードは常に 0 です。フェイルオープン方式なので、ガードの問題によってエージェントが動作不能になることはありません。

$ echo '{"tool_input":{"command":"kdbx set api/openai"}}' | kdbx guard --hook pretooluse
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"kdbx role-guard: 'set' is a human-only operation …"}}

$ echo '{"tool_input":{"command":"kdbx run -- npm test"}}' | kdbx guard --hook pretooluse
$ echo $?
0

ブロックするのは、エージェントが実行する人間専用操作と、kdbx 以外のプログラムが *.kdbx / *.keyx ファイルまたは KeePassXC の設定ディレクトリにアクセスすることの 2 つです（cat ~/.config/keepassxc/… も拒否されます）。kdbx、keepassxc-cli、keepassxc の呼び出しは正当なものとして認識します。

kdbx mcp は、MCP クライアントにも同じ契約を適用します。ツールは 5 つで、すべて読み取り専用です。意図的に、書き込み用のツールはありません。

エージェントとエディターの統合

MCP サーバー — .mcp.json（Claude Code）またはクライアントに相当するファイルに追加します：

{
  "mcpServers": {
    "kdbx": {
      "command": "kdbx",
      "args": ["mcp"]
    }
  }
}

PreToolUse フック — Claude Code の settings.json またはプラグインの hooks.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "kdbx guard --hook pretooluse"
          }
        ]
      }
    ]
  }
}

yarrasys/extensions の kdbx プラグインには、両方に加え、エージェントがコントラクトを学習するために読み込むスキルのドキュメントも含まれています。このリポジトリは2026-07-30現在、アーカイブされ、読み取り専用です。プラグインは引き続き動作しますが、更新や issue、PR は受け付けていません。上記のスニペットが統合に必要なすべてです。エージェントに kdbx guard や kdbx mcp を組み込むのに、このプラグインは必要ありません。

セキュリティ

• 秘密情報はキーファイルだけです。 マスターパスワードはありません。<env>.keyx を読み取れる人は、誰でも <env>.kdbx を開けます。リポジトリとは別の場所に保管してください。デフォルトの場所（~/.config/keepassxc/<project>/）は、意図的にリポジトリの外にあります。
• キーファイルは別の経路でバックアップしてください。 失うと、ボールトは復元できません。設計上、復元方法はありません。
• クラウド同期に注意してください。 OneDrive、Dropbox、iCloud Drive などの下にボールトやキーファイルを置くと、第三者およびそのアカウントに紐づくすべてのデバイスに複製されます。kdbx init はこれを検出すると警告しますが、処理を拒否はしません。
• ボールト、キーファイル、エクスポートされた dotenv ファイルは、アトミックに 0600 で書き込まれます（Windows では所有者のみの ACL）。また、ボールトの保存はクラッシュに対して安全です（一時ファイルからリネームし、リネームが完了するまで以前のボールトを .bak として保持します）。
• 秘密情報の値が argv、ログ、JSON 出力、エラーテキストに出ることはありません。 入力方法は stdin、--from-env、または対話型プロンプトのみです。
• 既知の制限事項： 秘密文字列はメモリ内でゼロ化されません（Python 実装と同様です）。コアダンプや、十分な権限を持つローカルプロセスによって復元される可能性があります。

脆弱性については、SECURITY.md を参照してください。公開 issue は作成しないでください。

起源

kdbx は yarrasys/extensions の Python スキルとして始まりました。このリポジトリは現在アーカイブされています。このバイナリが正式な kdbx であり、Python スキルは廃止されています。互換性を規定する設計仕様は、docs/kdbx-go-standalone-design.md にあります。ボールトは標準の KDBX4（Argon2、キーファイルのみ）なので、kdbx が書き込んだボールトは keepassxc-cli と KeePassXC デスクトップアプリでそのまま開けます。.keepassxc.json のポインターと KeePass XML v2 のキーファイルは、これらのツールがすでに使用している標準形式です。

元の Python スキルから移植する際、いくつかの動作を意図的に選択しました。

項目	動作	理由
install-launcher	削除	バイナリ自体がランチャーであり、インストールするものは残っていません
ボールトを開けない場合	終了コード 3	3 はロックまたは認証情報の失敗に関する文書化されたコントラクトです（Python スキルでは 1 を返す場合もありました）
import 時の不正な .env（閉じていない引用符）	終了コード 7	インポート中に認証情報が黙って失われるより、明確に失敗するほうが望ましいためです
run 中にシグナルで子プロセスが終了した場合	-1 → 255	Go はすべてのシグナル終了を -1 にまとめます。これはシェルの 128+N とは一致しないため、移植可能な呼び出し元はこの動作に依存しないでください。通常の終了コードは同じ値で引き継がれます

バグとフィードバック

バグを見つけた場合や機能のアイデアがある場合は、issue を作成してください。kdbx --version、お使いのプラットフォーム、機密情報を伏せた再現手順を記載してください。実際の秘密情報、ボールトのパス、キーファイルは決して貼り付けないでください。問題の概要だけで十分です。

セキュリティ脆弱性については例外です。公開 issue ではなく、GitHub Security Advisories を通じて非公開で報告してください（SECURITY.md を参照）。

コントリビューション

環境構築とビルド／テストの手順については、まずCONTRIBUTING.mdをご覧ください。 AGENTS.md（CLAUDE.mdとしてシンボリックリンクされています）には、リポジトリのルールとして、エンジンの境界、 シークレットの衛生に関する不変条件、テストの規律が記載されています。PR を作成する前にお読みください。CI では、 Linux、macOS、Windows でテストスイートを実行するほか、go vet、gofmt、golangci-lintも実行します。

参加にあたっては行動規範が適用されます。

ライセンス

MIT — 詳細はLICENSEをご覧ください。依存関係のライセンスはNOTICEに記載されています。依存関係ツリー全体でライセンスは MIT／BSD／Apache-2.0 のみで、コピーレフトのコンポーネントは含まれていません。