开源项目 cmdseal：为 AI 智能体打造的 macOS 能力安全网关

一句话概括： 让你的 AI 智能体能调用敏感命令，却拿不到背后的秘密。

今天，我正式将 cmdseal 开源了！这是一个面向 AI 智能体时代的能力网关工具，专门解决一个让我思考了很久的问题——当我们在设备上部署 AI 智能体时，如何让它可以执行需要密码的操作，却又不会把这些秘密暴露给智能体本身。

这个项目为什么存在

过去一年里，越来越多人在自己的 Mac 上部署常驻的个人 AI 智能体。我自己也是其中之一。智能体可以读文件、跑工具、在外出时通过 IM 或邮件自动回复——这些都很好。

但有一道坎始终过不去：秘密怎么处理？

离线密码管理器的主密码、私钥、加密档案的口令……这些东西直接交给 AI 智能体是不可接受的——一次 prompt injection、一次被留底的对话、一条被拦截的信道，秘密就可能全部泄露。

可我们仍然希望智能体能帮上忙。这让我陷入了思考：

怎样让智能体调用一项敏感操作，而不让它知道这项操作所需的秘密？

cmdseal 就是我对这个问题的回答。

核心思路：能力网关

cmdseal 不搞复杂的沙箱或容器方案。它的核心思路非常 macOS 原生：生成一个经过签名、被 Keychain 绑定、单一用途的二进制文件。

这个二进制文件就像一个「能力网关」——AI 智能体可以运行它，但看不到它的内部，也无法提取它所使用的秘密。

工作原理

1
2
3
4
命令模板  ─┐
秘密值   ────┼─►  AEAD 封存的运行器 (C)  ──►  ad-hoc 签名的二进制
           │                                 │
           └──  AES-256 密钥 K  ──►  login.keychain ACL 绑定到此二进制的 cdhash
  1. 秘密不写进二进制 — 秘密值在封存时通过 AES-256 加密后以 AEAD 密文形式嵌入二进制，而不是明文存储
  2. Keychain ACL 绑定 — macOS Keychain 条目通过 ACL（访问控制列表）绑定到这个具体二进制的 cdhash（代码哈希）
  3. 运行时解密 — 封存后的二进制运行时，通过 Keychain 静默获取密钥并解密，在内存中短暂解密后立即 execv 目标命令
  4. 其他进程无法访问 — 任何其他进程（包括 AI 智能体本身、/usr/bin/security、甚至位级完全相同的副本）试图读取 Keychain 条目，都会触发 GUI 弹窗——而无人值守的 AI 智能体无法点击它

安全机制的实证结果

在开发过程中，我搭建了一个非交互 5 秒硬超时的负向测试 harness，针对全新的、未授权任何调用者的 Keychain 条目进行了测试：

攻击者场景 结果（5秒超时）
/usr/bin/security find-generic-password -w ⏸ 超时——弹窗，无法读取
另一个 ad-hoc 签名的二进制调用相同 API ⏸ 超时——弹窗，无法读取
封存二进制的字节级副本 ⏸ 超时——弹窗，无法读取

三种未授权调用者全部触发 GUI 确认弹窗。能力网关这条性质成立。

快速上手：从零开始封存一个命令

GUI 方式（推荐）

1
2
3
4
5
6
git clone https://github.com/szgenle/cmdseal.git
cd cmdseal

make sync            # 安装依赖（PySide6）
make app             # 生成 dist/cmdseal.app
open dist/cmdseal.app

启动封存向导后，首先看到的是主界面：

cmdseal 封存向导主界面

只需要四步完成封存：

① 输入命令 — 支持多管道模板，复杂的 shell 管道也能一键封存：

cmdseal 命令输入界面

② 选择运行时参数 — 可视化配置哪些参数保留给运行时传入：

cmdseal 运行时参数配置

③ 设置保存位置与标签 — 给封存后的二进制打上标签，方便管理：

cmdseal 保存配置

④ 执行封存 — 一键将 shell 命令封装成可独立执行的二进制文件：

cmdseal 封存执行

所有封存记录都会保留在管理器中，方便后续查看、重新生成或删除：

cmdseal 历史记录管理

CLI 方式（高级）

1
2
3
4
5
6
7
8
9
10
11
python3 cmdseal.py seal \
    --command 'zip -j -P {{secret:zippw}} {{arg:1}} {{arg:2}}' \
    --output ./seal_zip

# 运行封存后的二进制
./seal_zip out.zip /path/to/secret.txt
# 首次运行弹一次系统对话框（登录密码 + "始终允许"），之后完全静默

# 验证密码未被明文烘进二进制
strings ./seal_zip | grep -F 'hunter2' && echo FAIL || echo 'PASS'
# → PASS: 密码未泄露

特色功能一览

除了基本的命令封存，cmdseal 还提供了一些非常实用的功能：

🔑 无需重建模板即可轮换密钥

1
2
3
python3 cmdseal.py rotate ./seal_zip
# 生成新 AES-256 密钥，重写 AEAD 密文，重新签名，原子性替换 keychain 条目
# 约 1 秒静默完成，无需用户交互

🔗 多段管道支持（v1.2）

封存后的二进制可以包含 1~8 段由 stdout→stdin 连接的管道，全程由 C 代码调度，从不经过 shell，因此 ;、|、$() 等 shell 元字符完全无效：

1
2
3
4
python3 cmdseal.py seal \
    --command '/usr/local/bin/zhmm_cmd -s {{arg:1}} --once' \
    --command '/usr/bin/zip query_result.zip -' \
    --output ./zhmm_pack

🖥️ Runner 管理器

GUI 内置的「管理 runner…」窗口可以列出本机所有已封存的 runner，支持右键修改模板、联动删除（同时清理 keychain 条目与磁盘文件），零弹窗。

🧩 「从命令生成模板」简化入口

如果你不懂 {{secret:}} 或 {{arg:}} 语法也没关系——先写好一条能跑的命令，然后通过可视化界面点选哪些参数保留给运行时传入，cmdseal 会自动生成模板。

安全模型说明

cmdseal 保护你免受：

  • 通过 argv 或 ps 的秘密窃取 — 秘密以 AEAD 密文形式嵌入，仅在 keychain 获取和 execv 之间短暂存在于内存
  • 其他进程读取 keychain 条目 — macOS ACL 绑定到确切二进制 cdhash
  • 基于 PATH 的程序替换 — 运行器使用 execv + 封存时的绝对路径
  • 通过环境变量的 Dylib 注入 — 运行器剥离 DYLD_* 和 LD_*，并使用 codesign --options runtime 签名

cmdseal 不保护你免受：

  • root 攻击者 — 可以读取任何进程内存、任何 keychain
  • 同用户的任意代码执行 — 可调试/转储运行中的二进制
  • 目标命令的侧信道攻击 — 例如 zip 本身将密码写入日志

⚠️ cmdseal 是一个能力网关，不是保险库。请诚实地评估你的威胁模型。

完美配合 my zhmm 项目

熟悉我博客的朋友知道我还有一个项目叫 zhmm（终端离线密码管理器）。cmdseal 和 zhmm 的组合是一个很好的实践场景：

1
2
3
4
5
6
7
8
# 封存 zhmm 的查询命令，主密码作为 secret
python3 cmdseal.py seal \
    --command 'zhmm_cmd --pwd {{secret:master}} --search {{arg:1}}' \
    --output ./zhmm_fetch

# 交给 AI 智能体调用
./zhmm_fetch "github token"
# AI 智能体拿到了 github token 的值，但永远不知道主密码

技术架构亮点

cmdseal 的实现非常有 macOS 特色：

  1. C 语言 runner — 生成的二进制主体是 C 代码编译而成，仅依赖 Security.framework 和 CoreFoundation，体积极小
  2. AEAD 加密 — 使用 AES-256-GCM 加密秘密，嵌入二进制文件末尾
  3. Ad-hoc 签名 — 编译后立即 codesign -s - 签名，将身份钉死在具体编译产物上
  4. Keychain ACL — 通过 -T 参数将二进制添加到 Keychain 条目的信任列表
  5. 无 shell 执行 — 使用 execv 直接执行预先拆好的 argv 数组

项目状态与路线图

  • ✅ CLI 端到端可用（macOS 13+，已在 14 / 15 / 26 上测试）
  • ✅ GUI 封存向导（PySide6，通过 make app 生成独立 .app 包）
  • ✅ 多段管道支持（v1.2，1~8 段，不经过 shell）
  • ✅ 密钥轮换（rotate 子命令）
  • ⚠️ 目前仅支持 macOS（Linux / Windows 是未来工作）
  • ⚠️ 以源码形式分发（尚未提供 Developer ID 签名的发布版本）

未来计划

  • 消除 sealed binary 自身首次运行的 partition-list 弹窗
  • 实现 cmdseal gc 自动清理已删除二进制的 Keychain 条目
  • Linux（libsecret）/ Windows（DPAPI）适配

结语

cmdseal 这个项目的开发过程让我学到了很多 macOS 安全框架的底层知识，也让我对「能力网关」这个设计模式有了更深的理解。在这个 AI 智能体日益普及的时代，如何安全地授权它们执行操作，是一个绕不开的问题。

我不是第一个思考这个问题的人，也不会是最后一个。但我希望 cmdseal 能给大家提供一个 macOS 原生的、优雅的解决思路。

项目完全开源，MIT 许可证，欢迎来 GitHub 逛逛：

👉 https://github.com/szgenle/cmdseal

有任何问题或建议，欢迎提 Issue 或 PR！

如果你对这个项目感兴趣，欢迎 Star、Fork、分享。你的支持是我持续开源的动力！