Skip to content

feat(confine): refuse unconfined agents by default (#133) - #205

Merged
DavidGodefroid merged 2 commits into
mainfrom
feat/133-confined-agent-default
Nov 14, 2026
Merged

DavidGodefroid merged 2 commits into
mainfrom
feat/133-confined-agent-default

Conversation

@DavidGodefroid

Copy link
Copy Markdown
Owner

Closes #133.

What

Unconfined agents are refused by default, with lea as the reference containment.

  • confine (new): confine.Check(env) Report with the four checks of the issue (in_container, no_host_runtime, no_family_state, lockfamily_read_only), an injectable Env and RealEnv(). Fixed reason codes plus confine.Text. confine.RuntimeGIDs() for a host console.
  • ipc: HelloParams.Confinement, CodeUnconfined (-32009), Cred.Groups (Linux SO_PEERGROUPS, macOS cr_groups) and Cred.HasGroup.
  • client: the hello carries confine.Check(confine.RealEnv()), computed once per process.
  • console: decision in hello (table in GUIDE §10, Confined agents), ServerConfig.RuntimeGIDs (= --runtime-gids ∪ this machine's), Profile.Unconfined, refused at start on production (ErrConfig), refused under managed require_confined_agent, red banner at start and per unconfined connection, audit.Base.Unconfined/UnconfinedReasons stamped on every record of the connection (via StampPeer), ticket.Flags.Unconfined on its hub tickets.
  • config: Base.Unconfined in DiffBase (on = loosening, off = tightening).
  • Docs: GUIDE §6.1, §7, §10; README security model ("Confined agents"); CHANGELOG (Breaking).

Safe-side choices (agreed with the lead)

  1. On a socket connection, no method is served before an accepted hello (hello first). Test: TestMethodBeforeHelloRefused.
  2. The decision is re-taken at every request: a policy that turns production or drops unconfined, or a managed file that comes to require confinement, cuts an open unconfined connection. Test: TestPolicyFlipCutsUnconfined.
  3. Host runtime gids = gids of runtime sockets whose group may write them (rootful Podman's root:root 0600 gives none), plus --runtime-gids. --runtime-gids is registered with the hub flags (HubOptions.RuntimeGIDs, a string so HubOptions stays comparable), not counted by Enabled() so a policy-only console takes it; an invalid value refuses the start.
  4. no_host_runtime also counts a runtime socket that is mounted but refuses for want of permission (EACCES): the socket being there is the misconfiguration, and it makes E2E (c) hold without --group-add.
  5. unconfined is omitempty in config.Base and ticket.Flags: existing policy fingerprints hold; an old hub (strict decoding) refuses only tickets that carry it (fail closed). Test: TestFlagsUnconfinedOldHub.

Client-sent reason codes are filtered to known ones (never the console's own runtime_group/old_client), at most eight.

Tests

  • Unit: confine (each reason alone, all four → confined, nested rootless Podman allowed, /proc detection), ipc (TestPeerCredGroups, socketpair vs os.Getgroups()), console (decision table, start refusal on production, managed, runtime group, old client, hub ticket flag), config (fingerprint, loosening/tightening), ticket, audit field set.
  • E2E: go test -tags e2e ./confine/... (new CI step, Linux): real console on a unix socket, the client run (a) on the host → refused, (b) in docker run with only the socket dir and a read-only .lockfamily → served, writable .lockfamily → refused, (c) with /var/run/docker.sock → refused no_host_runtime, and with --group-add <docker gid> → plus runtime_group. Locally (nested rootless Podman, LOCKKIT_E2E_RUNTIME=podman LOCKKIT_E2E_RUN_ARGS=--userns=keep-id) (b) passes; (a) and (c) skip there and run in CI.

Breaking

A lock bumping lockkit must ship its client and console of the same version: an older console refuses the new hello member, an older client is refused as old_client. Lock tests that dial a console from the host need a confined report or unconfined = true.

Follow-ups

Filed separately (lockhub --runtime-gids/banner/e2e, one lockkit bump per lock), linked from #133.

🤖 Generated with Claude Code

Every lock client reports in hello whether it runs confined (new package
confine: in a container, no host runtime socket, no Lock Family state, a
read-only .lockfamily). The console adds the kernel's record of the
peer's groups (Cred.Groups, SO_PEERGROUPS / cr_groups) against the gids
owning a runtime socket (--runtime-gids plus its own machine's) and
decides: unconfined agents are refused with CodeUnconfined unless the
profile sets unconfined = true (a loosening; never on production, never
under managed require_confined_agent). Served unconfined connections get
a red banner, unconfined:true on every audit record and flags.unconfined
on their hub tickets.

Safe-side choices: no method before an accepted hello on a socket
connection; the decision is re-taken at every request; only runtime
sockets whose group may write them give a runtime gid; unconfined is
omitempty in Base and ticket.Flags.

E2E: go test -tags e2e ./confine/... runs a real console and the client
on the host and in docker run (CI step added).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A CI runner is in the docker group: Run added its gid to RuntimeGIDs and
refused the tests' own clients as runtime_group. hostRuntimeGIDs is now a
package variable the tests replace; TestRunRuntimeGIDs covers the union
with --runtime-gids and the refusal of an invalid value.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@DavidGodefroid
DavidGodefroid merged commit 871b41c into main Nov 14, 2026
4 checks passed
@DavidGodefroid
DavidGodefroid deleted the feat/133-confined-agent-default branch November 14, 2026 14:18
@DavidGodefroid DavidGodefroid mentioned this pull request Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant