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

6.2 KiB

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 self (age + sqlite) envp (template) ✅ ❌ ❌ ❌ (passphrase only)
1Password op run external (1P only) envp ✅ (default) ❌ ❌ ✅ (1P account)
HashiCorp Vault Agent external (Vault) env file + sidecar ❌ ❌ ❌ ✅ (Vault token)
Bitwarden bw external (BW) envp ❌ (manual) ❌ ❌ ✅ (BW account)
Deno permission 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.