Skip to content

Require a confined agent by default (lea as reference); unconfined only by explicit opt-in, never in production #133

Closed

Description

@DavidGodefroid

Postponement lifted (triage 2026-11-14).

Goal

The Lock Family's guarantees hold only if the agent cannot reach what protects them. An agent run directly on the host (plain claude, codex in a terminal) runs as the user and can:

  • read the hub facades' private keys ($XDG_STATE_HOME/lockfamily/facades/tty.key) and sign its own approvals;
  • use the container runtime (docker group = root-equivalent), docker exec into a lock container and read its credentials;
  • read or drive lox run's terminal, edit lockfamily.yaml and profiles, and kill lox run.

Unconfined, the Locks protect against a confused agent, not a prompt-injected one. Direction: require a confined agent by default, with lea as the reference containment. Unconfined runs only by explicit, human-reviewed opt-in, and never on a production profile.

What the check can and cannot prove (read first)

  • Decision: the uid is not the criterion. lea's agents run as the host user's uid (lockhub docs/lox-run.md, allowed_uids), so "does not run as the human's uid" would refuse lea itself. The criterion is the environment the client runs in.
  • Decision: the check makes the safe setup the default and stops honest or confused host agents. It does not claim to stop a host process that deliberately lies. Such a process already runs as the human and can drive Docker, so no lock-side check could stop it. Docs say so plainly. Confined agents (lea) cannot reach the runtime, the keys or the terminal, and that is what makes the guarantees hold against prompt injection.
  • Two layers:
    1. Client self-check (in the agent's environment, where the facts are visible) reported in hello.
    2. Kernel-attested server check (on Linux): the peer's supplementary groups.
      The console decides.

Scope (lockkit only; ordered)

Step 1: confine package (new): confine.Check(env Env) Report

Report{Confined bool; Reasons []string}. Env holds injectable functions for tests, and confine.RealEnv() is the real one. Reasons are fixed short codes plus a human text, never a path's contents. The client is confined when all hold:

  • in_container: /.dockerenv or /run/.containerenv exists, or /proc/1/cgroup / /proc/self/mountinfo shows a container root (Linux). On macOS the client is never in a container, so the client is unconfined.
  • no_host_runtime: none of the rootful runtime sockets connect: /var/run/docker.sock, /run/docker.sock, /run/podman/podman.sock, /run/containerd/containerd.sock. A rootless runtime socket inside the container (lea's nested Podman via DOCKER_HOST=unix:///run/user/<uid>/podman/podman.sock) is allowed: it runs inside the container's namespaces.
  • no_family_state: $XDG_STATE_HOME/lockfamily (default ~/.local/state/lockfamily) is absent or unreadable.
  • lockfamily_read_only: the nearest .lockfamily/ above the working directory, if any, is not writable (unix.Access(W_OK)). lea mounts it read-only.

Step 2: wire format and client (ipc/methods.go, client/client.go)

  • HelloParams.Confinement *ipc.Confinement ({"confined":bool,"reasons":[…]}). client.handshake fills it from confine.Check(confine.RealEnv()), computed once per process.
  • HelloResult unchanged. A refusal is an error with a new code CodeUnconfined and the message: refused: this agent does not run confined (<reasons>); run it inside lea, or ask the human to set unconfined = true on this non-production profile.

Step 3: console decision (console/server.go hello handler, console/serve.go accept path, ipc/peer_linux.go)

  • ipc.Cred gains Groups []int (Linux SO_PEERGROUPS; macOS LOCAL_PEERCRED cr_groups; Windows unchanged).
  • New Options.RuntimeGIDs []int / --runtime-gids flag on the shared console flag set. These are the gids that own a runtime socket. A host console computes them itself by stating the sockets above. lox run passes them to containerized consoles (lockhub follow-up). A peer holding one of them is unconfined (runtime_group), whatever it reports.
  • Decision in hello: confined when the client reports confined:true and no runtime_group. A client sending no Confinement (an older client) counts as unconfined (old_client).
  • Policy:
    • profile key unconfined = true (in config.Base, part of the reviewed/approved policy and its fingerprint, so changing it is a loosening the human approves at the console);
    • refused at console start on a production profile (ErrConfig: "unconfined is never allowed on a production profile");
    • refused when managed.File.RequireConfinedAgent() is true.
      Default: refuse unconfined clients.
  • With unconfined = true, the console prints a red banner at start and at every unconfined connection: unconfined: this lock protects against mistakes, not against a compromised agent. Every audit record of that connection carries "unconfined":true and the reasons (audit.Base.Unconfined, UnconfinedReasons). Hub tickets carry a flag ticket.Flags.Unconfined, so lockhub can show it.

Step 4: docs

  • GUIDE §7 (IPC, client) and §10 (console): the check, the decision table, the wire field, the profile key.
  • README security model: what holds with and without confinement (the "can and cannot prove" section above, in user words).
  • CHANGELOG: Breaking. Unconfined clients are refused by default. A lock bumping lockkit must ship its client and console of the same version.

Out of scope (follow-ups to file when this starts):

  • lockhub: lox run passes --runtime-gids, shows the unconfined banner and the per-lock unconfined in its review, and gets a lea e2e. Close lockhub#90 then.
  • Each lock (locksql, lockmq, lockfile, lockhttp, locklog, lockssh) bumps lockkit. They need no code change if they use client.Dial and console.Run. lockhttp's gate path needs its own check.
  • lockkit#4 and the desktop level 1/2 model: re-evaluate once this lands.
  • Recognising other sandboxes (Claude Code sandbox mode, srt, devcontainers): they pass if they meet Step 1's checks. No allowlist.

Dependencies

  • The maintainer lifts the postponement.
  • lockkit#166 (managed, merged 2026-11-09, unreleased). It is on main, so nothing blocks the code; it ships in the same release.

Acceptance criteria

  • Unit (confine): with a fake Env, each reason is reported alone, all four hold → Confined:true, and a nested rootless Podman socket under /run/user/<uid>/ does not make it unconfined.
  • Unit (ipc): PeerCred returns the peer's supplementary groups on Linux (a socketpair test with the process's own os.Getgroups()).
  • Unit (console): decision table. Confined → served. Unconfined + default → CodeUnconfined with the reasons in the message, and audited refused-unconfined. Unconfined + unconfined = true on non-prod → served, banner printed, and every audit record of the connection has unconfined:true. unconfined = true on a production profile → console refuses to start. RequireConfinedAgent → refused even with unconfined = true. A peer in RuntimeGIDs → unconfined even when it reports confined. A hello without Confinement → old_client.
  • Unit (config): unconfined changes the policy fingerprint, and switching it on is a loosening (needs approval), off is a tightening.
  • E2E (Linux CI, Docker available; go test -tags e2e ./confine/...): a real console server on a unix socket in a temp dir, and the test's client binary run three ways:
    • (a) on the host → refused;
    • (b) in docker run with only the socket dir mounted and a read-only .lockfamily → served;
    • (c) the same container with /var/run/docker.sock also mounted → refused (no_host_runtime; and runtime_group when run with --group-add <docker gid>).
  • GUIDE, README security model and CHANGELOG updated.

Activity

  1. DavidGodefroid commented on Nov 14, 2026

    @DavidGodefroid
    OwnerAuthor

    Implemented in #205. Follow-ups filed (Ready on the lockfamily board):

    Safe-side choices made here (agreed with the lead, each tested): no method before an accepted hello on a socket connection; the decision is re-taken at every request (a policy flip cuts an open unconfined connection); host runtime gids are those of runtime sockets whose group may write them, plus --runtime-gids; a runtime socket mounted but refused for want of permission still counts as no_host_runtime; unconfined is omitempty in config.Base and ticket.Flags (old hubs refuse only unconfined tickets).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions