vaultguard

🔐 vaultguard
为你的 AI Agent 守护 Obsidian 库。

npx @ashishrao-4/vaultguard init · 零依赖 · 纯 Node · 跨平台

---

问题

你的 AI Agent 功能强大。它们可以交付代码、运行命令，总有一天会问：“把数据库 URL 给我。”

你把它交给了它。现在，这个值会出现在你们对话的每份记录、日志、检查点和备份中。一个月后、一年后，你轮换了它——旧值却仍然留在那些地方。

库本身——Obsidian——只有在你加密时才会加密，而让 Agent 读取你的笔记，就意味着 Agent 也能读取你的秘密。

vaultguard 的功能

秘密以 AES-256-GCM 密文的形式存放在你自己的 Obsidian 库中。你的 Agent 通过 MCP 按名称获取秘密——运行命令时，秘密值会注入环境变量，Agent 永远看不到这些值，同时每次访问都会被审计。

简单来说：你的 Agent 按名称请求，vaultguard 按需解密，秘密值不会进入对话。

• 数据由你掌控。 没有云服务、SaaS 或服务器。加密块是纯 Markdown。
• 在 Obsidian 中可读。 加密块看起来像笔记；点击一下即可查看。
• 让你的 Agent 使用秘密运行任务——秘密值不会出现在对话记录中。
• 零 npm 依赖。 纯 Node ≥ 18。支持 Windows / macOS / Linux。

---

快速开始

1 · 安装

npm install -g @ashishrao-4/vaultguard

2 · 指定你的库

vaultguard init --vault "C:\Users\you\Documents\Obsidian Vault"

程序会要求你输入一个密码短语——用于加密和解密此库中所有块的密钥。 随后程序会：

• 在你的库中创建 Secrets.md，
• 自动将 Inline Secret Block 插件安装到库中，
• 写入 ~/.vaultguard/config.json——不包含密码短语（你需要通过 VAULTGUARD_PASSPHRASE 提供）。

重启 Obsidian 并启用插件：设置 → 社区插件 → Inline Secret Block → 启用。

默认情况下，密码短语绝不会写入磁盘。建议使用环境变量： VAULTGUARD_PASSPHRASE（或 DOORMAN_PASSPHRASE）。如果你仍想方便地存储密码短语—— 代价是安全性较低——请改为运行 vaultguard init --store-passphrase（参见威胁模型）。

3 · 添加第一个秘密——使用 Obsidian

在 Obsidian 中打开 Secrets.md 并添加一个明文块：

```secret DATABASE-URL
Mydatabaseurl@postgres
```

点击显示——插件会立即将其替换为加密的 secret-lock 块。原始值已消失；留下的是：

```secret-lock DATABASE-URL
Nx60U4Ph/+1CO+58Zr00HXhEW9GZ6voHlpS+bEXPpP69avbJaSfafZCC2dpPn6UgdMN+3PJUd+UPm39YAXhFTbHvLUpHDndzbODsL8fOm7IMWC16zjSQCW7CbRWklmUxOGl0lX2qpQ==
```

就这样。以后随时都能获取同一个值：再次点击显示即可。

没有 Obsidian？改用 CLI：

vaultguard add DB_URL     # 隐藏输入
vaultguard set DB_URL     # 原位轮换

4 · 连接你的 Agent

vaultguard mcp

此命令会为你的运行环境输出现成的配置：

opencode — 在 opencode.json 中配置（也可以通过应用进行全局配置）：

{
  "mcp": {
    "vaultguard": {
      "type": "local",
      "command": ["node", "C:/path/to/vaultguard/src/server.mjs"],
      "environment": { "VAULTGUARD_PASSPHRASE": "your-passphrase" }
    }
  }
}

Claude Code：

claude mcp add vaultguard -e VAULTGUARD_PASSPHRASE=your-passphrase -- node C:/path/to/vaultguard/src/server.mjs

Cursor： 将同一个服务添加到项目的 .cursor/mcp.json 中（或添加到 MCP 设置标签页）：

{
  "mcpServers": {
    "vaultguard": {
      "command": "node",
      "args": ["C:/path/to/vaultguard/src/server.mjs"],
      "env": { "VAULTGUARD_PASSPHRASE": "your-passphrase" }
    }
  }
}

5 · 开始使用

you : "run a quick sanity check against DB_URL"
agent: run_with_secret(command: "psql $DB_URL -c 'SELECT 1'", secrets: ["DB_URL"])
you :  ✔ exit 0  ·  audit entry written  ·  no secret leaked

• run_with_secret — 秘密只会注入命令的环境变量中。
• 输出会经过清理——任何意外回显的秘密都会被替换为 [REDACTED:NAME]。
• get_secret — 默认禁用，这样秘密值就不会传给 Agent；如果某个工具需要原始值，可在配置中设置 allowGetSecret: true 以启用。

---

安全模型

层级	防护措施
静态数据	AES-256-GCM、PBKDF2-SHA-256（250,000 次迭代、16 字节盐值，每个值使用全新的 12 字节 IV）。与 Inline Secret Block 插件的字节格式兼容。
审批门槛	默认情况下，禁止使用 run_with_secret，除非设置 requireApproval: false（或 VAULTGUARD_REQUIRE_APPROVAL=0）。
密钥访问门槛	默认情况下，禁用 get_secret——值永远不会传递给 Agent；仅通过 allowGetSecret: true 启用。预期路径是 run_with_secret（注入环境变量，Agent 不会看到值）。
主机允许列表	只有指定的客户端（来自 MCP clientInfo）才能调用工具。列表为空 = 允许所有客户端。
命令允许列表	只有你列出的命令前缀才能运行（例如 ["psql", "node", "git"]）。列表为空 = 允许所有命令。
审计日志	每次调用都会将调用方（主机）、操作、涉及的密钥和结果追加到 ~/.vaultguard/audit.jsonl。使用 vaultguard audit 查看。
输出清理	命令输出中的密钥值及其前 8 个字符会被隐藏。

配置

编辑 ~/.vaultguard/config.json：

{
  "vaultPath": "C:/Users/you/Documents/Obsidian Vault",
  // passphrase is NOT stored here by default — provide VAULTGUARD_PASSPHRASE instead
  "allowlist": { "hosts": [], "commands": ["psql", "node"] },
  "requireApproval": false,          // true (default) = gate run_with_secret
  "audit": true,
  "allowGetSecret": false            // false (default) = values never reach the agent
}

唯一能将密码短语写入此文件的方式是执行 vaultguard init --store-passphrase， 该命令会设置 "storePassphraseOnDisk": true 并包含 "passphrase"。其他情况下，密码短语都从 VAULTGUARD_PASSPHRASE 环境变量或 CLI 提示中读取。

环境变量	覆盖项
VAULTGUARD_VAULT_PATH / VAULT_PATH	保管库路径
VAULTGUARD_PASSPHRASE / DOORMAN_PASSPHRASE	密码短语
VAULTGUARD_HOME	配置目录（默认值：~/.vaultguard）
VAULTGUARD_REQUIRE_APPROVAL=0	自动批准
VAULTGUARD_AUDIT=0	禁用审计
VAULTGUARD_ALLOW_GET_SECRET=1	启用 get_secret（默认：关闭）

密码短语安全注意事项： 除非你选择启用（init --store-passphrase），否则 vaultguard 永远不会将密码短语写入磁盘。 在每个运行环境配置中提供 VAULTGUARD_PASSPHRASE（参见步骤 4），并像保护 SSH 密钥一样保护 ~/.vaultguard。更改了密码短语？vaultguard rekey 会重新加密 每个数据块，然后更新你设置该环境变量的所有位置。

---

CLI 参考

命令	功能
vaultguard init	配置保管库和密码短语，创建 Secrets.md，安装插件
vaultguard add <NAME>	加密并存储新密钥（交互式操作或使用 --value）
vaultguard set <NAME>	原位轮换密钥
vaultguard rekey	使用新密码短语重新加密每个数据块（交互式操作，或使用 --old-passphrase/--new-passphrase）
vaultguard list	列出密钥名称（不显示值）
vaultguard audit [--lines n]	查看审计日志末尾内容
vaultguard mcp	输出特定运行环境的 MCP 配置
vaultguard info	显示配置和安全状况
vaultguard test	加密自测

---

威胁模型——以及何时不应使用

vaultguard 是一个轻量的便捷层，不是密钥管理器。它的作用是防止机密值出现在 AI Agent 的对话记录、日志和检查点中。

它无法防范：

• 机器或执行环境被攻陷。 密码（或选择启用的已存储配置）保存在你的磁盘上。任何以你的身份运行的进程——备份工具、勒索软件、被攻陷的插件、你的 IDE——都能读取你的文件并解密保险库。
• 恶意 Agent。 这个工具的全部设计理念，就是让 Agent 在环境中使用机密运行命令。请把这视为“Agent 就是你”。从命令允许列表开始，并检查 vaultguard audit；不要授予你自己都不会授予的访问权限。
• 弱密码。 AES-256-GCM + PBKDF2 的强度取决于密码。请使用一个较长的随机密码（你的密码管理器可以生成并保存它）。
• 通过合法渠道外传。 有意为之的 Agent 可以将密文或原始值复制到任何可访问的位置。vaultguard 是一道屏障，而非边界。
• 插件供应链风险。 vaultguard init 会从 GitHub 发布页面下载 Inline Secret Block 插件。知道你的密码的恶意插件可以解密所有内容——如果你在意这一点，请固定版本并验证插件。

**适合使用的情况：**你希望实现“Agent 使用机密运行任务，而我不必把值粘贴到聊天中”，并且可以接受上述剩余风险。

**不适合使用的情况：**你需要真正的密钥管理保障——轮换策略、硬件支持的密钥、不会让原文可被原生插件访问的流程；你的威胁模型包括共享机器或 CI 机器上的恶意 Agent；或者你需要对保险库本身进行静态加密（此时应使用 Obsidian 自带的保险库加密功能或加密卷）。

---

常见问题

我的保险库适合放入 Git 吗？ 加密块是纯 Markdown，可以安全地提交、同步，或存放在任何 Obsidian 可用的位置。由于默认情况下密码不再保存在 ~/.vaultguard/config.json 中，提交该文件会泄露你的保险库路径和设置，但不会泄露密钥。

如果我忘记密码怎么办？ 这些块使用 AES-256-GCM 加密，无法恢复——这正是设计目的。

需要安装哪个 Obsidian 插件？ Inline Secret Block——vaultguard init 会为你安装。

我需要服务端吗？ 不需要。这是一个本地 stdio MCP 服务（node src/server.mjs）。没有任何程序监听端口。

---

许可证

MIT © vaultguard 贡献者。

此软件包会安装 Inline Secret Block 插件（同样采用 MIT 许可证）；该插件会在运行 init 时从其官方发布页面下载，不会随此软件包一同分发。本项目仅使用 Node.js 内置模块（crypto），因此无需跟踪任何依赖项的许可证。

---

守护你的保险库，让 Agent 放手工作。