26 KiB
xop · AI Agent 操作速查(上下文压缩后自动加载)
本文件是 xop 给 AI agent 的"可执行附录":Claude Code / WorkBuddy / 其他 agent harness 在每次会话开头、以及上下文压缩(compact)后都会自动重新加载它。 项目根:
/Users/xs/Documents/xop完整交接文档在HANDOFF.md;架构/威胁模型/对比在docs/。
0. 一句话定位
xop = 自带加密 vault + OS-auth gate 的 secret 注入器。xop init | set | list | get | rm 管理本地 vault(~/.xop/key.db,AES-256-GCM + argon2id,LAContext 真指纹预闸门,取消即拒绝,绝不弹系统密码框);xop [flags] -- CMD 把 vault 里的真值注入到子进程的 envp/Askpass/fd,同时强制 Deno 风格的 network/file policy,并在 stdout 里 mask 任何泄漏。无外部后端依赖——不调 op / vault / security CLI。
改 Rust 源码 → 必须 cargo check + cargo test --lib + cargo test --test integration 通过 → 再交付。编译错或测试红禁止 commit。
解锁模型(v0.2.1,2026-10-02 两次实测修正):vault 密钥永远 = argon2(passphrase)。每次操作先过 OS 身份闸门,闸门结论决定 keyring 能不能静默解锁:① 本地真 TTY → 弹 LAContext 真指纹验证(只认手指、绝无密码输入框;取消 = 拒绝操作 exit 77,不静默放行)→ 通过后才允许 keyring 免输;② SSH 会话(stdin 是 pty 但检测到 SSH_TTY/SSH_CONNECTION/SSH_CLIENT env)→ 绝不弹指纹(弹窗会飞到本机物理屏幕上,远程用户根本看不到/等不到),也不走 keyring——没有指纹现证,必须输入 xop passphrase(管理员密码);③ 本地设备无可用指纹(未录入、锁定、无密码、无 GUI、osascript 坏)→ 同样强制输入 xop passphrase;④ Linux 交互会话 → 无指纹闸门可用(pkexec 系统口令框按"永不输系统密码"红线删除)→ xop passphrase;⑤ headless 非 TTY 自动化(agent/pipe/CI/ssh host cmd 无 pty)→ 跳过闸门,keyring 静默解锁(xop run 无人值守的依据)。解锁密钥来源:文件 keyring ~/.xop/keyring(0600,存 hex 派生密钥,xop init 自动写入 / xop key --save 补写;xop key --remove 吊销)或终端手输(闸门要求输 passphrase / 无 keyring / XOP_NO_KEYRING=1 时)。明确设计决定(2026-10-02):绝不使用 macOS Keychain——keychain 方案在后台自动化时会弹系统授权对话框(曾被用户否决),xop 任何代码路径都不调 security(1)。keyring 权限位不合规(group/other 可读)直接拒用报错。release 二进制永不读 XOP_VAULT_PASSWORD env。子进程 stdout/stderr 中的任何 vault 值会被自动 mask 成 12****【xop禁止将密钥泄漏】(前 2 真实字符 + 星号 + 警告),--on-leak=kill|refuse 时直接 SIGKILL 子进程。
1. 编译 + 测试
cd /Users/xs/Documents/xop
# 快速检查(增量编译,最常用)
cargo check --all-targets
# 跑单元测试(64 个:args(含 get -v 解析)/ secret / policy / audit / vault / keyring / auth(touchid classify + decide 决策表)/ stdout-guard / error / injector)
cargo test --lib
# 跑集成测试(17 个:help / dry-run / bad-ref / secrets-file / mask 端到端 / keyring 免密解锁 / SSH-headless / get 默认 mask / get -v 明文)
# 集成测试需要 auth bypass + 已知 passphrase。`XOP_VAULT_PASSWORD` 仅在
# `--features test-bypass` 构建中才被读取;release binary 永远不读这个 env
# ——passphrase 必须用户亲输。所以集成测试必须显式启用 feature。
XOP_AUTH_BYPASS=1 XOP_VAULT_PASSWORD=testpass \
cargo test --features test-bypass --test integration -- --test-threads=1
# 完整构建 + smoke(默认 release build 不带 test-bypass feature)
cargo build --release
./target/release/xop # banner
./target/release/xop help # 完整帮助
./target/release/xop --dry-run --secret FOO=foo --allow-net=db.local:5432 --deny-net=* -- echo hi
./target/release/xop run --secret SSHPASS=ssh_pass -- sshpass -e ssh user@host
# 跑全部测试(不要漏 env vars)
cargo test --lib && \
XOP_AUTH_BYPASS=1 XOP_VAULT_PASSWORD=testpass \
cargo test --features test-bypass --test integration -- --test-threads=1
注意:
- 修改
Cargo.toml加依赖后必须cargo check让 Cargo.lock 重新生成 --test-threads=1在集成测试里必须带,因为某些测试改HOME/ env 状态- 集成测试用
--features test-bypass构建;release 永远不带这个 feature(防止XOP_VAULT_PASSWORD变成绕过 vault 加密的后门) - 编译警告允许带
#[allow(...)],但新代码不写unwrap()除非能证明 panic-safe
2. CLI 用法速记
# ── Vault 管理 ──────────────────────────────────────────────────────
# 一次性初始化(init 本身不要求 Touch ID — 此时还没有可保护的东西)
xop init
# init 问 passphrase ×2,然后自动写 ~/.xop/keyring(0600 文件 keyring,
# 存 argon2 派生密钥的 hex;不是 macOS Keychain):
# 本地真 TTY:弹指纹 → 通过 → 静默读 keyring,零 passphrase
# SSH 交互 / 无可用指纹 / Linux 交互:必须手输 xop passphrase(keyring 不参与)
# headless 自动化(agent/pipe/无 pty):跳过闸门 + keyring 静默
# 管理:xop key(状态)/ xop key --save(补写,老 vault 用它启用免密)
# xop key --remove(吊销,回到手输)
# revoke:`xop reset --yes` 会级联删 keyring 文件
# 存 / 列 / 取 / 删 secret(keyring 已存则免 passphrase)
xop set DB_PASS # TTY 上值输入带部分 mask(前 2 位明文 + *)
echo "hunter2" | xop set DB_PASS # 非 TTY(pipe/agent)从 stdin 读值
xop list # 列 key 名(不显示 value)
xop get DB_PASS # 默认脱敏输出 `su****【xop禁止将密钥泄漏】`(前 2 位)
xop get DB_PASS -v # 明文——人眼核对专用;AI agent 禁止 -v(明文会进模型上下文),用 xop run --secret 注入
xop rm DB_PASS # 删除单个
xop reset --yes # 删整个 vault + audit + keyring(应急)
# ── Exec-mode:envp 注入(传统)──────────────────────────────────────
xop --secret DB_PASS=db_pass \
--allow-net=mysql.local:5432 --deny-net='*' \
-- mysql -h mysql.local -u app mydb
# ── `xop run`:envp 注入 + argv 占位符(推荐用于 SSH)────────────────
# envp 注入:vault 值 → 子进程环境变量
xop run --secret SSHPASS=s11_pass \
--allow-net=192.168.1.19:22 --deny-net='*' \
-- sshpass -e ssh [email protected] 'ls /Users'
# argv 占位符:vault 值直接替换 argv 里的 xop://KEY 字符串
# ⚠️ 替换后的字符串会出现在 /bin/ps 里 —— 密码用 --secret,命令行参数用 xop://
xop run -- ssh user@host 'echo connect with xop://DB_PASS'
# 批量注入(commit-safe 的 .env.xop 文件,每行 KEY=NAME)
xop --secrets-file .env.xop -- ./deploy.sh
# Dry-run:只看 policy,不真执行(AI 自检的 killer feature)
xop --dry-run --secret FOO=foo --allow-net=db:5432 --deny-net=* -- deploy.sh
注意:
KEY=NAME必须在--之前;--后是子命令 + 它的 args- bash 会展开
$VAR,所以 secret 引用不要直接写在命令行里——用--secretflag 或xop://KEY占位符 - v0.2 删了
--backend和所有 scheme 前缀(op://、vault://)——只有 bare key --dry-run在 resolve 之前短路,不开 vault、不过 OS 闸门——纯本地打印有效 policy(集成测试dry_run_prints_effective_policy无 bypass env 也过)- Passphrase 提示策略:stdin 是真 TTY → 走
/dev/tty(隐藏输入),stdin 不是 TTY(agent / pipe / expect)→ fallback 到 stdin。Release binary 永远不读XOP_VAULT_PASSWORDenv——passphrase 必须用户亲输(或走 keyring 免输)
3. 模块地图
| 想了解 | 看哪里 |
|---|---|
| CLI 所有 flag + 解析 + Subcommand enum | src/args.rs |
ref 长啥样 + 怎么解析(bare KEY=NAME + argv_placeholder 标志) |
src/secret.rs |
| 错误类型 + 退出码(BSD sysexits) | src/error.rs |
| 权限策略(allow/deny 默认值) | src/policy.rs::DEFAULT_DENY_READ + Policy::from_args |
| 本地 vault:文件格式 + 加密 | src/vault/mod.rs + src/vault/format.rs |
文件 keyring:~/.xop/keyring 0600 免密解锁(非 Keychain) |
src/vault/keyring.rs(路径显式的 *_at 核心 + env 门控 wrapper) |
OS auth gate:macOS 真指纹(LAContext via JXA)+ Gate 决策(headless/SSH/无指纹/取消) |
src/auth/mod.rs(Gate/Bio/decide/ssh_session)+ touchid.rs(Outcome/classify) |
| 子命令(init / set / list / get / rm / reset / key / run) | src/commands/{init,set,list,get,rm,reset,key}.rs + src/lib.rs::run_join_and_exec |
xop://KEY argv 占位符 + 单 vault open 协调 |
src/lib.rs::expand_xop_placeholders + src/injector.rs::scrub_argv |
| 怎么注入到子进程 | src/injector.rs::plan + build_envp_delta(按 argv_placeholder 过滤) |
| 子进程 stdout 怎么过滤 | src/guard/stdout.rs::pipe_filter_loop |
| 网络/文件策略怎么落 | src/guard/{network,file}.rs(STUB,P1) |
| 审计日志格式 + 不变量 | src/audit.rs(test no_value_field_in_any_event 扫 4 个关键字) |
| 编排 exec-mode pipeline | src/lib.rs::run_exec(9 阶段) |
TTY-aware passphrase prompt(/dev/tty vs stdin fallback) |
src/vault/mod.rs::rpassword_prompt |
Test-only XOP_VAULT_PASSWORD 旁路(gated by Cargo feature) |
src/vault/mod.rs 的 #[cfg(feature = "test-bypass")] 块 + Cargo.toml::[features] |
| spawn 真实现(pre_exec + setrlimit) | src/lib.rs::spawn_child |
4. 关键不变量(违反任一 = 安全漏洞)
| # | 不变量 | 谁保证 | 验证方式 |
|---|---|---|---|
| I1 | LLM API / IPC / shell history 永远不出现 secret value | --secret KEY=NAME flag 设计 + vault 用 SecretBox<String> 包装值 |
code review:grep expose_secret 限定在 injector / guard 内 |
| I2 | 审计日志没有 value/plaintext/ciphertext/passphrase 字段 |
audit::AuditLog 只接收 serde_json::Value,不接收 ResolvedValue |
cargo test audit::tests::no_value_field_in_any_event |
| I3 | SecretBox::Debug 打印 <secret> |
secrecy crate 保证 |
cargo test secret::tests |
| I4 | 真值只在 fork 前短暂活在 parent 内存 | injector::build_envp_delta 拷贝值进 envp 后立刻 drop parent 端 |
手动 review spawn_child |
| I5 | --allow-net/--deny-net 默认 deny-by-default |
Policy::from_args 不接受空 allow 等于全 deny |
cargo test policy::tests |
| I6 | 子进程退出时 temp 文件清掉 | injector::askpass 负责 srm -m + rm(P1) |
手动 review + OS-level verification |
| I7 | vault 文件只有 passphrase 能解密(v0.2 新增) | AES-256-GCM + argon2id KDF;OS auth 只是 pre-gate | cargo test vault::format::tests |
| I8 | keyring 静默解锁只在身份已被证明时允许(本地指纹通过 / headless 自动化);SSH 与无指纹交互场景必须输 xop passphrase,keyring 不参与;且 xop 从不触碰 macOS Keychain(v0.2.1 两次修订) | Vault::open:auth::authenticate() → Gate;AllowKeyring 才 keyring::load(),RequirePassphrase 直接 prompt(SSH env / 无生物特征 / osascript 坏 / Linux 交互);XOP_NO_KEYRING=1 强制手输;keyring mode 非 0600 报错拒用;代码库无 security(1) 调用 |
cargo test auth::tests::decide_*(5 条决策表)+ code review vault/mod.rs::open |
| I11 | 子进程 stdout/stderr 里的 vault 值必被 mask(v0.2.1 新增) | pipe_filter_loop 行缓冲 + StdoutGuard::filter;--on-leak=kill/refuse 时 SIGKILL |
cargo test guard::stdout::tests + integration run_masks_* |
| I9 | release binary 不读 XOP_VAULT_PASSWORD env(v0.2 新增) |
旁路仅在 #[cfg(feature = "test-bypass")] 编译时存在;release 用 cargo build --release(不带 feature) |
strings target/release/xop | grep XOP_VAULT_PASSWORD 应无匹配 |
| I10 | vault 每次 exec 只开一次(v0.2 新增) | --secret 和 xop://KEY 占位符共享同一个 resolve_all 调用 |
code review:run_join_and_exec + run_exec |
5. 当前状态(2026-10-02,v0.2.1)
✅ 已完成(v0.2 pivot 完成):
- 删除
src/backend/{op,vault,kc,env}.rs+mod.rs(4 个外部后端) - 新增
src/vault/:AES-256-GCM + argon2id,atomic write,单元测试覆盖 round-trip / wrong key / 不同 passphrase - 新增
src/auth/:macOS Touch ID(osascript)+ Linux PAM(pkexec)subprocess 方式;TTY 检测 + 1FA fallback - 新增
src/commands/:init/set/list/get/rm/reset6 个子命令 - 新增
xop run子命令:--secret KEY=NAME(envp 注入) +xop://KEY(argv 占位符),通过SecretRef::argv_placeholder区分 - 新增
xop reset --yes子命令:清空 vault + audit - subcommand enum:
init / set / list / get / rm / reset / run / help Args重构:subcmd: Option<Subcmd>+ flat exec 字段 +Args::as_exec()+ExecArgs.argv_placeholdersrun_join_and_exec:单次 vault 开锁统一解析--secret和xop://KEY;scrub_argv替换 argv、build_envp_delta仅生成 envpspawn_child真实现:tokio::process::Command+pre_exec闭包设RLIMIT_CORE=0pipe_filter_loop真实现:stdout/stderr 双 pipe reader,过滤后写回 inheritedbuild_envp_delta真实现:从ResolvedValue[]生成Vec<(String, String)>,按argv_placeholder过滤- TTY-aware
rpassword_prompt:stdin 是 TTY →/dev/tty;stdin 不是 TTY → fallback stdin(agent / pipe / expect 友好) - Cargo feature
test-bypass:仅在cargo test --features test-bypass时启用XOP_VAULT_PASSWORD旁路;release 永不包含 - 39 unit test + 11 integration test 全绿
Makefile:build / install(/usr/local/bin/xop)/ uninstall / test / smoke / clippy / clean- 4 篇 docs 全部更新到 v0.2(design / architecture / threat-model / comparison)
- 端到端 SSH 实测:
xop run --secret SSHPASS=s11_pass -- sshpass -e ssh [email protected] ls /Users跑通
✅ v0.2.1(2026-10-02,用户实测 4 问题修复):
xop set值输入不再明文回显:TTY 走 rpasswordpassword_feedback_partial_mask('*', 2)(前 2 位明文 + 其余*)- 免密解锁改用文件 keyring:
src/vault/keyring.rs(~/.xop/keyring,0600 hex 密钥,xop init自动写);OS 预闸门照旧先跑,之后set/list/get/rm/run免 passphrase → AI agent 可无人值守跑xop run。曾实现过 macOS Keychain 方案,因自动化时弹系统授权对话框被用户否决并整体删除——xop 不调security(1) - OS 闸门改为真指纹:
src/auth/touchid.rs用osascript -l JavaScript调LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)(biometrics-only,弹窗里没有密码框可点)。旧的do shell script "…" with administrator privileges实为系统登录密码框,且取消后被当"不可用"静默降级继续执行(实测xop set取消指纹仍存了 secret)——现取消/拒绝一律AuthCancelledexit 77;无指纹设备/会话 → xop passphrase;Linux pkexec 系统口令框删除(gate 变为 no-op) - 新增
xop key [--save|--remove]子命令:查看/补写/吊销 keyring(用户既有 vault 跑一次xop key --save即启用免密) xop get默认脱敏:输出su****【xop禁止将密钥泄漏】(前 2 位,同 I11 mask 格式),明文只在显式-v/--value时打印且 stderr 带警示。动因:agent 会话里xop get的 stdout 直接进模型上下文/日志/shell history——I1 在"读取"路径上原本不设防。-v是人眼专用逃生门,agent 用密钥必须走xop run --secret注入- SSH 实测二次修正:闸门返回
Gate(auth::decide纯函数决策表)——SSH 交互会话绝不弹指纹(SSH_TTY/SSH_CONNECTION/SSH_CLIENT检测;LAContext 弹窗只会出现在本机控制台),且无指纹现证(SSH/无生物特征/Linux 交互/osascript 坏)时 keyring 不参与解锁,强制输入 xop passphrase;只有「本地指纹通过」或「headless 非 TTY 自动化」允许 keyring 静默。Vault::open按 Gate 分支。Linux 不再有pam.rs - stdout leak guard 修复真 bug:
pipe_filter_loop的guard_for_reader原来是直通 stub(这就是用户看到xop run echo xop://s19_pass打印明文123456的原因);现在按行 buffer(跨 chunk 的密钥不漏检)+ mask 格式12****【xop禁止将密钥泄漏】+kill/refuse时 SIGKILL 子进程 + auditleak_event xop reset --yes级联删 keyring 文件- 64 unit + 17 integration 全绿(端到端 mask ×2、keyring 免密解锁 ×1——
env_remove掉口令通道验证run仍成功、touchid LAError 分类 ×8、auth 决策表 decide ×5、SSH+headless 仍走 keyring ×1、get 默认 mask ×2);release 构建 I9 strings 校验通过
⚠️ P1 / 未来工作:
✅ v0.2spawn_child真实现✅ v0.2pipe_filter_loop真实现✅ v0.2build_envp_delta真实现✅ v0.2xop://KEYargv 占位符NetworkGuard的 pf/iptables 真接入(当前是 stub,新 vault flow OK)FileGuard的 sandbox-exec/landlock 真接入(当前是 stub)- Askpass 注入策略(SSH_ASKPASS + DISPLAY=:0 + SSH_ASKPASS_REQUIRE=force)
- argv scrubber(检测
--password=value等显式模式)
完整 TODO 列表见 HANDOFF.md。
6. 常见踩坑(来自实测 + 设计权衡)
-
bash 会展开
$VAR—xop ssh user:$SSH_PASSWORD@host在 bash 里$SSH_PASSWORD先被 bash 展开成真值,xop 看到的是真值。永远用--secret KEY=NAMEflag。 -
secrecy::SecretBox的expose_secret()— 必须use secrecy::ExposeSecret;才能调。如果 import 漏了,编译错 E0599。./src/{secret,guard/stdout,vault/mod.rs}.rs都已加。 -
async fnin trait 必须#[async_trait]—Auth::authenticate和Guard::setup/teardown都是 async。trait 必须 deriveasync_trait::async_trait,且Cargo.toml依赖async-trait = "0.1"。 -
tokio::process::Command不支持 setrlimit — 想在子进程设RLIMIT_CORE=0必须用pre_exec闭包(runs after fork, before exec)。当前lib.rs::spawn_child已实现,参考nix::sys::resource::setrlimit。 -
Secret<String>在 secrecy 0.10 改名成SecretBox<String>— 别按 0.8 文档写代码。 -
stdout mask 用
Vec<u8>不是String— 子进程的 stdout 可能是 UTF-8 invalid(binary data);用 bytes 避免from_utf8panic。 -
audit log写之前调.flush()— 否则 child crash 时 audit 丢失。AuditLog::write_event已 flush。 -
macOS 指纹 =
osascript -l JavaScript调 LAContext,不是 admin 弹窗 —do shell script … with administrator privileges是系统登录密码框(红线禁止),且 osascript 会命中 admin 授权缓存导致"看起来免密"其实是缓存放行。正确姿势:JXActx.evaluatePolicyLocalizedReasonReply(1, reason, fn)(policy 1 = biometrics-only,无密码选项)+ 主线程NSRunLoop.runUntilDate自旋等 block 回调。实测 JXA 能把私有队列的 block 回调 marshal 回 JS 线程(NSOperationQueue 探针 107ms 通过);LAContext 无缓存,每次调用都真弹指纹。取消分类:-128/-5/-12 → 拒绝操作;-7/-8/-10/-11/-1008/-1/-6 → 无指纹降级 passphrase。 -
Linux 交互 = 直接输 xop passphrase(
pam.rs已删除) — 旧实现pkexec -- true弹的是 polkit 系统密码框,违反"任何时候不要让用户输入系统密码"红线(2026-10-02)。Linux 没有可移植的纯指纹 CLI 闸门,身份无法被生物特征证明 →decide返回RequirePassphrase(keyring 也不参与);headless 自动化仍走 keyring 静默。真 Touch ID 闸门仅 macOS 有。 -
atomic vault write 用 tmp + rename —
~/.xop/key.db.tmp.<pid>写完 fsync 后 rename 到key.db,断电不留下半截文件。 -
argon2id 参数:m=64 MiB, t=3, p=4 — 慢 ≈250ms / attempt,现代 CPU 上比 bcrypt/scrypt 都强。别调低。
-
XOP_VAULT_PASSWORD是 release 后门,必须 gated — v0.2 早期把它当 CI/agent 旁路直接读 env,等于"任何有 env 的进程都能解密 vault"。当前用#[cfg(feature = "test-bypass")]包住;release 永远不编译这段。校验手段:strings target/release/xop | grep XOP_VAULT_PASSWORD必须空。 -
TTY-aware passphrase prompt 怎么选 —
is_terminal(stdin)决定走/dev/tty还是 stdin fallback。如果用/dev/tty检测(/dev/tty文件存在性)会误判(SSH 下文件存在但不可用)。用std::io::IsTerminal(POSIXisatty(fd))才是真信号。 -
vault 不要开两次 — 早期
xop run内部先expand_xop_placeholders开一次 vault,再run_exec开一次,导致用户输两次 passphrase。修复:让expand_xop_placeholders只收集名字(不开 vault),把 placeholder 加进SecretRef::argv_placeholder=true的列表,让run_exec::collect_refs一次性带去resolve_all。原则:vault 整个进程最多 open 一次。 -
SecretRef::argv_placeholder标志位 — 区分 envp 注入(--secret KEY=NAME)和 argv 占位符(xop://KEY),但走同一个 vault 解析。build_envp_delta跳过 placeholder,scrub_argv处理 placeholder。ResolvedValue镜像这个标志位。 -
绝不在后台自动化里对真实钥匙串做写/删 — v0.2.1 曾实现 macOS Keychain 存 passphrase,
security(1)在 agent 会话里会弹出系统授权对话框("xop wants to delete/modify keys"),用户看到就是安全事故,方案整体否决删除。免密改走 0600 文件 keyring:无 GUI、无弹窗、可xop key --remove秒吊销。 -
keyring 静默解锁必须"身份有来源" —
Vault::open先auth::authenticate() → Gate:AllowKeyring(本地指纹刚通过 / headless 非 TTY 自动化)才读 keyring;RequirePassphrase(SSH 交互会话、无可用生物特征、osascript 坏、Linux 交互)直接强制手输 xop passphrase,keyring 根本不参与——否则"免密"就没有任何身份验证垫底。旧两版 bug:keychain 方案"命中即连闸门都不问";指纹闸门版把 SSH/无指纹也当"降级继续"仍走 keyring。另外:lib 单元测试禁止改全局 env(HOME/XOP_NO_KEYRING/SSH_*)——并行跑会互相污染(实测 4 个 keyring 测试因 set_var("HOME") 竞态随机红),文件逻辑/决策逻辑要抽成参数显式的纯函数(auth::decide(tty, ssh, bio)、keyring::*_at(&Path))测。 -
SSH 会话里
isatty(0)是 true,但绝不能弹指纹 — SSH 的 stdin 是 sshd 分配的 pty,TTY 检测≠本地控制台。LAContext的 Touch ID 窗口只会出现在本机物理控制台,远程用户既看不到也点不了,表现为"卡住/错弹"。正确做法:检测SSH_TTY/SSH_CONNECTION/SSH_CLIENTenv(sshd 注入、本地 Terminal 不会有)→ 直接Gate::RequirePassphrase(用户输管理员密码,keyring 免谈);ssh host cmd无 pty 的自动化场景走 headless keyring 静默。顺序必须!tty → AllowKeyring先判,tty+ssh 才 RequirePassphrase。 -
stdout mask 必须按行 buffer — 子进程输出的一个 4096 字节 chunk 可能把密钥劈成两半;
pump()只在遇到\n时才 filter+flush 完整行,残行留在 carry buffer,EOF 再补一次。直接 filter 每个 chunk 会漏检跨 chunk 密钥。expect/Tcl 断言 mask 时注意 glob 的*匹配任何字符——要用regexp {to\*+} $log匹配字面星号。 -
xop get默认输出的su****【xop禁止将密钥泄漏】不是 bug,是闸门 — agent 会话里工具 stdout 直通模型上下文;get若回显明文,注入链路(run 子进程 mask)做得再好也白搭——密钥从"读取"这条路就出去了。看到 mask 说明值存在且对路,继续用xop run注入即可;严禁给 agent 路径加-v(-v是给人眼核对的逃生门,stderr 会打警示)。测试:integrationget_masks_value_by_default/get_dash_v_prints_plaintext。
7. 与 xstudio 的衔接(未来)
xop 是独立项目,但定位上是 xstudio xstudio.ai.runAgentLoop 的"secret 安全层"。集成路径:
- 短期:xstudio plugin 通过
Process.run("/usr/local/bin/xop --secret ... -- <cmd>")调用 xop - 中期:xop 暴露
pub use xop::runlibrary mode,xstudio 直接 link - 不集成:xop 永远不需要知道 xstudio 存在(独立开源)
参考 xstudio 项目里的 xstudio-control skill(同义物)。
8. 文档索引
| 想看 | 路径 |
|---|---|
| 一句话定位 + CLI 速查 | 本文件(AGENTS.md) |
| 完整交接 / 实施路线图 | HANDOFF.md |
| 整体设计 + 命令 + 架构 + 不变量 | docs/design.md |
| 12 个威胁 + v0.2 缓解状态 | docs/threat-model.md |
| vs secret-agent / op run / Vault Agent / Deno | docs/comparison.md |
| 模块依赖图 + 数据流 + trait 表面 | docs/architecture.md |
| 参考实现 | refs/secret-agent/ |
| 实战示例 | examples/{init,list,get,ssh,mysql,dry-run}.sh |
| 集成测试 | tests/integration.rs |
9. License
MIT.