Repository navigation
Description
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 (
dockergroup = root-equivalent),docker execinto a lock container and read its credentials; - read or drive
lox run's terminal, editlockfamily.yamland profiles, and killlox 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:
- Client self-check (in the agent's environment, where the facts are visible) reported in
hello. - Kernel-attested server check (on Linux): the peer's supplementary groups.
The console decides.
- Client self-check (in the agent's environment, where the facts are visible) reported in
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:/.dockerenvor/run/.containerenvexists, or/proc/1/cgroup//proc/self/mountinfoshows 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 viaDOCKER_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.handshakefills it fromconfine.Check(confine.RealEnv()), computed once per process.HelloResultunchanged. A refusal is an error with a new codeCodeUnconfinedand 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.CredgainsGroups []int(LinuxSO_PEERGROUPS; macOSLOCAL_PEERCREDcr_groups; Windows unchanged).- New
Options.RuntimeGIDs []int/--runtime-gidsflag on the shared console flag set. These are the gids that own a runtime socket. A host console computes them itself bystating the sockets above.lox runpasses 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 reportsconfined:trueand noruntime_group. A client sending noConfinement(an older client) counts as unconfined (old_client). - Policy:
- profile key
unconfined = true(inconfig.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.
- profile key
- 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":trueand the reasons (audit.Base.Unconfined,UnconfinedReasons). Hub tickets carry a flagticket.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 runpasses--runtime-gids, shows the unconfined banner and the per-lockunconfinedin 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.Dialandconsole.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 fakeEnv, 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):PeerCredreturns the peer's supplementary groups on Linux (a socketpair test with the process's ownos.Getgroups()). - Unit (
console): decision table. Confined → served. Unconfined + default →CodeUnconfinedwith the reasons in the message, and auditedrefused-unconfined. Unconfined +unconfined = trueon non-prod → served, banner printed, and every audit record of the connection hasunconfined:true.unconfined = trueon a production profile → console refuses to start.RequireConfinedAgent→ refused even withunconfined = true. A peer inRuntimeGIDs→ unconfined even when it reports confined. A hello withoutConfinement→old_client. - Unit (
config):unconfinedchanges 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 runwith only the socket dir mounted and a read-only.lockfamily→ served; - (c) the same container with
/var/run/docker.sockalso mounted → refused (no_host_runtime; andruntime_groupwhen run with--group-add <docker gid>).
- GUIDE, README security model and CHANGELOG updated.
Activity
DavidGodefroid commentedon Nov 14, 2026
Implemented in #205. Follow-ups filed (Ready on the lockfamily board):
lox runpasses--runtime-gids, unconfined banner and flag in the review and facades, lea e2e; closes lockhub#90 then)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 asno_host_runtime;unconfinedis omitempty inconfig.Baseandticket.Flags(old hubs refuse only unconfined tickets).test(console): keep the machine's runtime gids out of Run tests (#133)
feat(confine): refuse unconfined agents by default (#133) (#205)
feat: lockkit v0.20.0, refuse unconfined agents (#243) (#247)