5.8 KiB
xop
本地加密密钥库 + OS 身份闸门的 secret 注入器。
xop init | set | list | get | rm 管理本地 vault(~/.x/xop/key.db,AES-256-GCM + argon2id);
xop [flags] -- CMD 把 vault 里的真值注入到子进程的 envp / Askpass / fd,同时强制网络与文件读取策略,
并在 stdout 里 mask 任何泄漏。
无外部后端依赖 —— 不调 op / vault / security CLI。
- 完整操作速查(给 AI agent)见
AGENTS.md - 完整交接与实施路线图见
HANDOFF.md - 设计 / 架构 / 威胁模型 / 竞品对比见
docs/ - 可运行示例见
examples/
仓库地址
http://192.168.1.18:13300/x/xop.git
公司内网 Gitea(192.168.1.18:13300),命名空间 x,仓库公开可读。
凭据取自 ~/.git-credentials。
git clone http://192.168.1.18:13300/x/xop.git
分支 main,当前版本 v0.5.2(tag v0.5.2)。
环境要求
| 项 | 要求 | 备注 |
|---|---|---|
| Rust | 1.95+ | rustup show active-toolchain 自查 |
| 构建 | cargo build --release |
首次约 4 分钟(纯标准库 + 常规 crate) |
| 依赖 | crates.io 可达 | 若走内网缓存,参见 dev-cache-layout 技能 |
| 安装 | 写 /usr/local/bin 需 sudo |
或用 PREFIX 指定其他前缀 |
| 平台 | macOS(Touch ID)/ Linux(passphrase) | 真指纹闸门仅 macOS 有 |
编译与安装
cd xop
cargo build --release # 产物在 target/release/xop
make install # 装到 /usr/local/bin/xop(需 sudo)
make install PREFIX=$HOME/.local # 或装到用户目录,无需 sudo
安装后自检:
xop --version # xop 0.5.2
xop # 打印 banner + quick start
⚠️ release 二进制永远不读
XOP_VAULT_PASSWORD环境变量 —— 该旁路只在--features test-bypass构建中存在,用于集成测试。校验:strings target/release/xop | grep XOP_VAULT_PASSWORD应无匹配。
首次初始化
xop init # 设 passphrase ×2,自动写 ~/.x/xop/keyring(0600)
xop set DB_PASS # 存一个密钥(TTY 下值输入带部分打码)
xop list # 列键名 + 描述(免密免 Touch ID)
xop init 之后,后续操作在本地 Terminal 里只需 Touch ID 指纹(不弹系统密码框);
SSH 交互会话、无可用指纹的设备、Linux 交互会退化为手输 xop passphrase。
三种注入姿势
# 1. envp 注入 —— 值进子进程环境变量
xop run --secret SSHPASS=ssh_pass -- sshpass -e ssh user@host 'ls'
# 2. SSH_ASKPASS 注入 —— 值既不进 argv 也不进 env(直连 ssh 推荐)
xop run --askpass=ssh_pass -- ssh user@host
# 3. argv 占位符 —— %XOP_KEY% 被替换(⚠️ 替换后出现在 /bin/ps,勿用于密码)
xop run -- ssh user@host 'echo %XOP_DB_PASS%'
--secret KEY=NAME 必须写在 -- 之前,-- 之后是子命令及其参数。
先看策略再执行(不碰 vault、不过闸门,纯本地打印):
xop --dry-run --secret FOO=foo --allow-net=db.local:5432 --deny-net='*' -- echo hi
给 AI agent 的三条硬规矩
- 禁止
xop get -v—— 明文会进模型上下文/日志/shell history。 看到su****【xop禁止将密钥泄漏】是正常的闸门行为,说明值存在且对路, 继续用xop run --secret注入即可。 - 必须
< /dev/null——xop run --secret K=N -- cmd < /dev/null。 不重定向 stdin 会等 Touch ID 弹窗而超时。xop list同理。 - key 名 ≠ 字面值 ——
ssh_pass是 vault 里的键名,不是密码本身。 别把键名当口令传给远端。
免密范围
| 操作 | 是否要 Touch ID / passphrase |
|---|---|
xop list / xop desc |
❌ 免(只读元数据,永不吐 value) |
xop get / set / rm / run |
✅ 要(涉及真值) |
list / desc 只暴露键名与描述,不泄漏任何 secret,所以刻意跳过身份闸门,
避免 AI agent 执行到一半被弹窗打断。
常用命令
xop list # 列全部键名 + 描述
xop list git_local # 子串搜索(不用引号、不用通配符)
xop desc KEY 文本 # 给键写描述;不带文字 = 清除
xop get KEY # 取值(默认打码)
xop rm KEY # 删一个键
xop key # 查看 keyring 状态
xop key --save # 补写 keyring(旧 vault 启用免密)
xop key --remove # 吊销 keyring(回到手输 passphrase)
xop reset --yes # 应急:清空整个 vault + 审计日志
仓库结构
src/
main.rs CLI 入口
args.rs flag 解析 + Subcmd 枚举
secret.rs secret 引用类型(envp 注入 vs argv 占位符)
vault/ 加密 vault:格式 / keyring / 元数据
auth/ 身份闸门:Touch ID(macOS)/ passphrase 决策表
guard/ stdout mask、network/file 策略(后两者为 stub)
injector.rs envp 构造 + argv 替换
askpass.rs SSH_ASKPASS 注入(临时文件自动清理)
policy.rs 默认 deny 策略
audit.rs 审计日志(不含 value 字段)
docs/ design / architecture / threat-model / comparison
examples/ init / list / get / ssh / mysql / llm / dry-run
tests/ 集成测试
开发
cargo check --all-targets # 快速检查
cargo test --lib # 单元测试
cargo build --release && make smoke # smoke
集成测试需要 test-bypass feature(仅测试用):
XOP_AUTH_BYPASS=1 XOP_VAULT_PASSWORD=testpass \
cargo test --features test-bypass --test integration -- --test-threads=1
改 Rust 源码后必须 cargo check + cargo test --lib + 集成测试全绿再交付。
License
MIT