kdbx

kdbx — 将每个项目的机密存储在 KeePassXC 保管库中，可安全交给 AI Agent 使用

kdbx 将项目机密存储在按项目、按环境划分的 KeePassXC 保管库中 （KDBX4，仅使用密钥文件解锁，不需要主密码），并将机密提供给需要它们的工具，且 kdbx 绝不会将其输出到对话记录、日志文件或 shell 历史记录中。 自动发现：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 声明最低要求为 1.26。发布的二进制文件是静态构建的，用户无需安装工具链。

Shell 补全：

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

环境对象为空也没问题——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

子进程会继承你的环境以及映射的变量。它的退出码会直接返回。不会写入任何文件，值也不会出现在 shell 历史记录中。

读取操作刻意设计得很简单：

$ 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。 带有 ✦ 标记的操作会向 stderr 输出横幅 ACTIVE ENV: <env> vault=<path> (source: <src>)；纯显示操作则不会。

操作	标志	行为（标准输出 / 标准错误 / 退出状态）
init ✦	--here、--mode standard|strict	创建保管库和密钥文件；如果上方任意位置都没有指针文件，或使用了 --here，则先在当前目录写入一个全新的 .keepassxc.json（项目名称取自该文件名，环境为 dev/prod，并将 dev 设为活动环境），让项目只需一条命令即可启动；如果当前目录位于另一个项目的目录树中，直接运行 init 会指出即将使用的指针文件并先请求确认（仅限 TTY，否则退出码为 4），同时提示可用 --here 启动独立项目；标准错误输出 created <vault>，并警告备份 KEYFILE；拒绝覆盖已有的保管库、密钥文件或指针文件；--mode 会在指针文件中记录环境策略，而 strict 会将其锚定到新保管库中
policy bless ✦		将指针文件当前的策略（其 policy 和 run.allow 部分）锚定到保管库中；仅限交互操作，与 rekey 相同，并由防护机制禁止 Agent 执行；锚定不匹配时，严格的 run 会拒绝执行
set PATH ✦	--var NAME、--from-env VAR、--raw	使用 --from-env 指定的值；否则在 TTY 上交互式提示并要求确认；其他情况下从标准输入读取（空值 → 错误；除非使用 --raw，否则会去掉一个尾随换行符）；拒绝空值或仅含空白字符的值；--var 会将映射添加到指针文件
get PATH	--reveal | --clip	默认输出 (set, hidden)——不会泄露长度或前缀；--reveal 会输出值并在标准错误中发出警告；--clip 会复制值并在约 15 秒后自动清除；缺少条目或字段 → 退出码为 2
list [GROUP]		按排序输出 group/…/title 行，并按 GROUP 前缀筛选；排除回收站；绝不输出值
delete PATH ✦	--purge	默认软删除到回收站；--purge 会提示 y/N（仅限 TTY——非 TTY 环境下会拒绝并以退出码 4 退出），然后永久删除
mv SRC DST ✦		移动条目或重命名条目，并创建目标分组；重新指向当前活动环境中引用了 SRC 的变量映射，同时保留任何 :field 后缀；标准错误输出 re-pointed N var mapping(s) …
run ✦	--allow-missing、--no-mask、--any、-- CMD…	如果指针文件包含 run.allow 列表，则在打开保管库之前拒绝未列出的命令（退出码为 7，NotAllowed），除非使用 --any；解析活动环境的 vars 映射，将其注入子进程环境，通过 PATH 解析 argv[0]（Windows 上使用 PATHEXT），转发信号，并传递子进程的退出码；捕获子进程输出流时（非 TTY），其中长度至少为 8 字节的注入值会被替换为 ***（--no-mask 可禁用此行为；防护机制禁止 Agent 使用该选项）；未指定命令 → 退出码为 2；变量无法解析 → 退出码为 5，除非使用 --allow-missing
export ✦	--out FILE、--allow-missing	将映射渲染为 dotenv 格式（始终使用双引号；对 \、" 和换行符进行转义）；--out 会以 0600 权限原子写入文件，并提醒添加 gitignore，否则输出到标准输出
import FILE ✦		解析 dotenv 文件（不进行 $VAR 插值），将每个 KEY 存储到 imported/KEY 并注册映射；标准错误会提醒你删除或轮换源文件
check		对每个损坏的映射输出 MISSING VAR -> path；检查通过时退出码为 0，存在偏差时为 5
envs		每个环境输出一行，并在活动环境前标记 * ；标准错误输出 active: <env> (source: <src>)；没有指针文件 → 退出码为 2
rekey ✦		提示 y/N（仅限 TTY，否则退出码为 4），生成新的密钥文件，为保管库重新加密，并原子替换旧密钥文件；标准错误会提醒你重新分发密钥文件

集成接口：

命令	用途
kdbx mcp	通过 stdio 提供只读 MCP 服务（五个工具：kdbx_list、kdbx_envs、kdbx_check、kdbx_get、kdbx_run）
kdbx guard --hook pretooluse	从标准输入读取 PreToolUse 钩子载荷，并拒绝由 Agent 发起的仅限人工操作
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}

--json 与 --reveal 一起使用时会被拒绝（退出码为 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，后者的优先级高于指针文件中的 defaultEnv；默认值为 dev。 kdbx envs 和横幅会报告三者中哪一个生效。不在指针文件中的环境会导致错误（退出码为 2）。

退出码

代码	含义
0	成功
1	一般失败（已清理敏感信息）
2	未找到——无指针文件、环境未知、条目或字段缺失，或未向 run 提供命令
3	已锁定、密钥文件缺失或凭据失败
4	未确认破坏性操作
5	漂移——check 发现映射损坏，或 run/export 无法解析映射
6	写入期间保管库发生变化；请重新运行
7	预检拒绝（例如，--var 名称无效，或使用了 --json --reveal）

失败时只会输出一行标准错误，绝不输出堆栈跟踪或密钥。该行包含稳定的错误类型以及 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。

角色 — Agent 读取，人类编写

kdbx 的设计目标是可以安全地交给编码 Agent 使用。规则如下：

• Agent 安全： run、get（已屏蔽）、list、check、envs、init。
• 仅限人类： set、delete、mv、import、rekey、export，以及 get --reveal / get --clip。

Agent 可以使用凭据：kdbx run -- npm test 可以正常运行，而且 kdbx 本身绝不会 打印凭据值。

这是一道防护措施，而非安全边界；为什么如此，需要说清楚。

二进制程序不会强制执行这种区分。真正的边界是是否持有密钥文件： 任何能够读取密钥文件的对象或程序都能打开保险库。支持钩子的运行框架会通过 kdbx guard 执行角色区分；在其他所有情况下，这种区分都只是建议。

如果愿意，可以固定子命令。将 run.allow 列表提交到 .keepassxc.json 后，run 会拒绝任何不在列表中的 argv（人类可以传入 --any；guard 会禁止 Agent 这样做）。但要清楚这能带来什么：原则上 Agent 仍然可以编辑指针，不过 guard 会拦截明显的编辑，而且修改会显示为受跟踪文件中的可见差异，而不是不可见的单行命令。如果没有列表，run 会将凭据注入传入的任意 argv。

对于需要严格管控的环境（生产环境、真实客户凭据），可以启用严格模式：kdbx init --mode strict。严格模式要求设置允许列表，直接拒绝 --any 和 --no-mask，会为每项决策记录审计日志（仅记录命令和变量名称，绝不记录值；日志写入保险库旁权限为 0600 的文件），并要求先通过 kdbx policy bless 将策略哈希写入保险库，才能进行注入。该命令仅限人类交互执行。策略遭到带外修改时，下次 run 会拒绝执行，而不会默默遵从。相同规则也适用于 MCP 服务的 kdbx_run；它还始终会屏蔽输出，完全没有绕过方式。有意破坏规则且使用你的 uid 的 Agent 仍然可以绕过所有这些措施；严格模式改变的是，悄无声息的篡改会变得显而易见。 捕获输出时（例如通过管道、Agent 运行框架或日志），其中注入的值会替换为 ***——因此 kdbx run -- env 显示的是屏蔽后的值，而非原始值，恰好是在这些字节即将写入记录稿的位置。终端会收到原始输出；--no-mask（guard 会禁止 Agent 使用）则会在管道供人类使用时恢复原始值。屏蔽只会匹配完全相同的值：Agent 在输出时对值进行编码就能绕过屏蔽，测试脚本被编辑成外泄数据的脚本也同样如此。kdbx 不打印机密，是 kdbx 的特性，并非它所运行的整个系统的特性。

这种角色区分真正能做到的是，让 Agent 不会在处理其他事情时无意间泄露凭据，也无法创建、轮换或导出凭据。它无法阻止一个决定读取凭据的 Agent。如果你需要这样的保护，就需要设置一道 Agent 无法以你的用户身份跨越的边界：单独的账户、容器，或持有密钥的代理服务。请参阅 issue #11。

kdbx guard 会从 stdin 读取 PreToolUse 载荷，然后打印拒绝信封，或不输出任何内容。它始终以 0 退出——它采用故障开放策略，因此 guard 出现问题也绝不会卡住 Agent。

$ 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

它会阻止两种操作：Agent 发起的仅限人类操作，以及非 kdbx 程序访问 *.kdbx / *.keyx 文件或 KeePassXC 配置目录（因此 cat ~/.config/keepassxc/… 也会被拒绝）。它会将 kdbx、keepassxc-cli 和 keepassxc 调用识别为合法操作。

kdbx mcp 会对 MCP 客户端应用相同的约束：提供五个工具，且全部只读。它刻意不提供写入工具。

Agent 和编辑器集成

MCP 服务 — 添加到 .mcp.json（Claude Code）或客户端的等效文件中：

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

PreToolUse hook — Claude Code 的 settings.json 或插件的 hooks.json：

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

yarrasys/extensions 中的 kdbx plugin 将两者打包在内， 还包括 Agent 用于了解使用约定的技能文档。该仓库自 2026-07-30 起已归档且为只读——该插件仍可运行，但不会收到更新、问题报告或 PR。上面的代码片段就是全部集成内容；无需使用该插件即可将 kdbx guard 或 kdbx mcp 接入 Agent。

安全

• 密钥文件是唯一的机密信息。 没有主密码。任何能读取 <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。请勿公开提交问题报告。

起源

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；这与 shell 的 128+N 不符，因此没有可移植的调用方依赖此行为。正常退出码则会原样传递

错误与反馈

发现错误或有功能建议？请提交问题报告。请附上 kdbx --version、平台信息和已删去敏感信息的复现步骤——切勿粘贴真实机密信息、保险库路径或密钥文件；只需描述问题的大致情况即可。

安全漏洞是唯一的例外：请通过 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，不含任何 Copyleft 组件。