Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
e878e2f0ef |
@@ -0,0 +1,167 @@
|
||||
# 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
|
||||
Reference in new issue
Block a user