Security Model

What trustless guarantees

  1. Credential values never enter the LLM context window

    • run: credentials are set on the subprocess environment, output is scanned and redacted before being returned
    • proxy: credentials are substituted inside the proxy process; the agent sees only the API response
    • Direct get outputs the value but requires explicit invocation (not available to the agent in normal workflows)

  2. Command argument scanning (--scan-args)

    • Before spawning a subprocess, all command arguments are scanned for credential patterns and injected values
    • If detected, execution is blocked with exit code 3 (fail closed)
    • Prevents the agent from accidentally exposing credential values in CLI arguments

  3. Policy engine — command-level access control

    • policy.default.denied_commands: block dangerous commands globally (e.g., sh, bash)
    • policy.<key>.denied_commands: block specific commands per credential
    • Fail-closed: policy violation blocks execution with exit code 3

  4. Subprocess output sanitization

    • Default patterns match common credential formats: GitHub tokens, OpenAI keys, xAI keys, AWS keys, Bearer tokens, and generic patterns
    • Injected values are themselves pattern-scanned: if the subprocess echoes the credential, that value is redacted
    • Custom patterns via config file or --sanitize-policy

  5. Minimal attack surface

    • Proxy listens on 127.0.0.1 by default (not exposed to the network)
    • Unix socket mode available for file permission control
    • MITM proxy generates per-hostname ephemeral certificates (24h validity)
    • Single binary with zero runtime dependencies beyond pass + gpg (the bitwarden backend additionally requires the bw CLI)

  6. No credential persistence in the broker process

    • Credentials are resolved on-demand and released after the subprocess exits
    • HTTP proxy holds credentials in memory only during active request processing

What trustless does NOT solve (v1 scope)

  • Dynamic/rotating credentials — the pass store is static; rotation is handled externally
  • Full audit trail — basic logging only; SIEM export is future work
  • Hardware-backed key storage — relies on GPG keyring security
  • HTTPS MITM CA trust management — the MITM proxy generates a CA cert; the user must install it in the OS trust store

← Docs