Files

5.8 KiB
Raw Permalink Blame History

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 的三条硬规矩

  1. 禁止 xop get -v —— 明文会进模型上下文/日志/shell history。 看到 su****【xop禁止将密钥泄漏】 是正常的闸门行为,说明值存在且对路, 继续用 xop run --secret 注入即可。
  2. 必须 < /dev/null —— xop run --secret K=N -- cmd < /dev/null。 不重定向 stdin 会等 Touch ID 弹窗而超时。xop list 同理。
  3. 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