From e878e2f0ef5e18cb205546173afe18e835759804 Mon Sep 17 00:00:00 2001 From: xs Date: Mon, 16 Nov 2026 14:23:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=20README=EF=BC=88=E4=BB=93?= =?UTF-8?q?=E5=BA=93=E5=9C=B0=E5=9D=80/=E7=BC=96=E8=AF=91=E5=AE=89?= =?UTF-8?q?=E8=A3=85/=E9=A6=96=E6=AC=A1=E5=88=9D=E5=A7=8B=E5=8C=96/?= =?UTF-8?q?=E4=B8=89=E7=A7=8D=E6=B3=A8=E5=85=A5=E5=A7=BF=E5=8A=BF/agent=20?= =?UTF-8?q?=E7=A1=AC=E8=A7=84=E7=9F=A9=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4cb4f79 --- /dev/null +++ b/README.md @@ -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