Files

168 lines
5.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`](AGENTS.md)
- 完整交接与实施路线图见 [`HANDOFF.md`](HANDOFF.md)
- 设计 / 架构 / 威胁模型 / 竞品对比见 [`docs/`](docs/)
- 可运行示例见 [`examples/`](examples/)
## 仓库地址
```text
http://192.168.1.18:13300/x/xop.git
```
公司内网 Gitea(`192.168.1.18:13300`),命名空间 `x`,仓库公开可读。
凭据取自 `~/.git-credentials`。
```bash
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 有 |
## 编译与安装
```bash
cd xop
cargo build --release # 产物在 target/release/xop
make install # 装到 /usr/local/bin/xop(需 sudo)
make install PREFIX=$HOME/.local # 或装到用户目录,无需 sudo
```
安装后自检:
```bash
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` 应无匹配。
## 首次初始化
```bash
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**。
## 三种注入姿势
```bash
# 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、不过闸门,纯本地打印):
```bash
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 执行到一半被弹窗打断。
## 常用命令
```bash
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/ 集成测试
```
## 开发
```bash
cargo check --all-targets # 快速检查
cargo test --lib # 单元测试
cargo build --release && make smoke # smoke
```
集成测试需要 test-bypass feature(仅测试用):
```bash
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