Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,11 @@ jobs:
grep -E -- '--- FAIL|_test\.go:[0-9]+:|^FAIL|panic:' test.log | head -40 | sed 's/^/::error::/'
exit 1
}
# The confined agent check end to end: a real console, the client
# on the host and in docker run (lockkit#133).
- name: go test confine e2e (docker)
if: runner.os == 'Linux'
run: go test -tags e2e -count=1 -v ./confine/...
- name: go test managed (test build)
run: go test -tags lockfamily_managed_test ./managed/ ./console/
- name: pii throughput floor
Expand Down
34 changes: 34 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,40 @@
lockkit has no stability promise before v1: pin an exact version.
GUIDE.md is the contract between lockkit and the products built on it.

## Unreleased

### Breaking

- Unconfined agents are refused by default (#133). 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/`), and the console refuses an unconfined one
with `ipc.CodeUnconfined`, as it does a client holding a gid that owns a
runtime socket (`runtime_group`) or one that sends no report
(`old_client`). The profile key `unconfined = true` lets one in on a
non-production profile (a loosening, approved at the console): red
banner, `"unconfined":true` on every audit record of the connection,
`flags.unconfined` on its hub tickets. A production profile with it
does not start; a managed `require_confined_agent = true` refuses
unconfined agents whatever the profile says. No method is served on a
connection before its hello is accepted, and the decision is taken
again at every request. A lock bumping lockkit must ship its client and
console of the same version: an older console refuses the new hello
member, and an older client is refused by the new console.

### Changes

- ipc: `Cred.Groups` (the peer's supplementary groups: Linux
`SO_PEERGROUPS`, macOS `cr_groups`) and `Cred.HasGroup`;
`HelloParams.Confinement`; `CodeUnconfined` (-32009).
- console: `--runtime-gids` (`HubOptions.RuntimeGIDs`, written by `lox
run`), `ServerConfig.RuntimeGIDs`, `Profile.Unconfined`,
`UnconfinedBanner`, `DecisionRefusedUnconfined`, `ParseGIDs`.
- config: `Base.Unconfined` (`unconfined`, in `DiffBase`); audit:
`Base.Unconfined`, `Base.UnconfinedReasons`; ticket: `Flags.Unconfined`.
- An end-to-end test (`go test -tags e2e ./confine/...`) runs a real
console and the client on the host and in `docker run`, in CI.

## v0.19.2 (2026-11-14)

### Changes
Expand Down
64 changes: 64 additions & 0 deletions GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -216,6 +216,9 @@ loosen it, and no human can approve beyond it.
`File.Fingerprint` is the sha256 of the bytes, `File.Describe()` the
"Managed by <organisation> (sha256:…)" line, `File.Family`
(`RequireConfinedAgent`, `RequireSignature`, `Vault`) the family rules.
The console enforces `RequireConfinedAgent` itself: an unconfined agent
is refused whatever the profile's `unconfined` says (§10, Confined
agents).

Precedence: hard-coded floor > managed bounds and profiles > project file
> user file > managed defaults > built-in defaults. In your config loader:
Expand Down Expand Up @@ -302,6 +305,25 @@ c, err := client.Dial(P, cwd, profile) // *client.NoConsoleError (errors.Is Err
err = c.Call(ctx, "op.run", params, &result) // hello first, no client-side timeout; ctx cancel closes the connection
```

**Confinement (lockkit#133).** The client's `hello` carries
`ipc.HelloParams.Confinement` (`{"confined":bool,"reasons":[…]}`), the
outcome of `confine.Check(confine.RealEnv())`, computed once per process.
Confined means all four checks hold: `in_container` (`/.dockerenv`,
`/run/.containerenv`, a container in `/proc/1/cgroup` or an overlay root in
`/proc/self/mountinfo`; Linux only), `no_host_runtime` (none of
`confine.RuntimeSockets` connects or refuses for want of permission; a
rootless runtime under `/run/user/<uid>/` is not one),
`no_family_state` (`$XDG_STATE_HOME/lockfamily` absent or unreadable),
`lockfamily_read_only` (the nearest `.lockfamily/` above the working
directory, if any, fails `access(W_OK)`). Each failed check is its code in
`reasons`; `confine.Text(code)` is its human text. A refusal is
`ipc.CodeUnconfined` (-32009) with the reasons in the message. Use
`client.Dial`: a client that builds its own hello must send the same
report. `ipc.PeerCred` also returns the peer's supplementary groups
(`Cred.Groups`: Linux `SO_PEERGROUPS`, macOS `cr_groups`), which the
console checks (§10). A console older than this one refuses the new
`confinement` member: ship your client and console of the same version.

Several locks of one type (lea mounts each socket volume on
`<shared socket dir>/<instance>` and lists them, space separated, in
`LEA_<PREFIX>INSTANCES`; one lock stays on the shared dir with no such
Expand Down Expand Up @@ -1080,6 +1102,48 @@ The pieces are exported for a product that assembles its own console:
`console.Harden`, `console.Loop`, `console.WithPeer` / `PeerText` /
`StampPeer`, `console.Level`, `console.ErrResp` / `OKResp` / `Decode`.

### Confined agents (lockkit#133)

The console decides in `hello`, from the client's report (§7) and the
kernel's record of the peer:

| Client | Profile | Outcome |
|---|---|---|
| reports confined, holds no runtime gid | any | served |
| unconfined (any reason) | default | refused: `CodeUnconfined`, audited `refused/refused-unconfined` with `unconfined_reasons` |
| unconfined | `unconfined = true`, not production | served; red banner `console.UnconfinedBanner`; every audit record of the connection has `"unconfined":true` and its reasons; its hub tickets have `flags.unconfined` |
| unconfined | production, or managed `require_confined_agent = true` | refused, whatever `unconfined` says |
| no `confinement` in its hello | any | unconfined, `old_client` |
| holds a gid of `ServerConfig.RuntimeGIDs` | any | unconfined, `runtime_group`, whatever it reports |

- On a socket connection every method but `hello` is refused
(`CodeInvalidRequest`, "hello first") until a hello is accepted, and the
decision is taken again at every request: a policy in force that becomes
production or drops `unconfined`, or a managed file that comes to
require a confined agent, refuses the next request of an open
unconfined connection.
- Reason codes are the agent's word: the console keeps only known ones
(`confine.Known`), never the console's own codes (`runtime_group`,
`old_client`), at most eight.
- `RuntimeGIDs`: `Run` sets them to the gids of `--runtime-gids`
(`HubOptions.RuntimeGIDs`, comma-separated, registered with the hub
flags but not counted by `Enabled`, so a policy-only console takes it
too; `lox run` writes it for a containerized console) and those of this
machine's runtime sockets whose group may write them
(`confine.RuntimeGIDs`: `docker`'s, not rootful Podman's `root:root
0600`). A value that is not a list of gids refuses the start (`ErrConfig`).
- `Profile.Unconfined` comes from `config.Base.Unconfined` (profile key
`unconfined = true`, `json:"unconfined,omitempty"`: existing
fingerprints hold). `DiffBase` marks false→true a loosening, true→false
a tightening. `Run` refuses a production profile with it (`ErrConfig`:
"unconfined is never allowed on a production profile"), before any
prompt and again on the policy approved at start, and prints the banner
at start.
- `audit.Base.Unconfined` / `UnconfinedReasons` are set by `StampPeer`,
so a product's records through `Env`/`AuditBase` carry them.
`ticket.Flags.Unconfined` is `omitempty`: a hub that does not know it
refuses only the tickets that carry it.

## 11. Do not reimplement in your product

- a socket, a peer check or the JSON-RPC framing: `ipc`, `client`;
Expand Down
53 changes: 53 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -198,12 +198,65 @@ builds on it too.
of the human, and on production takes the typed profile name.
- In hub mode, a lock executes only on a decision signed by the hub key it
pinned, bound to the exact plan that was approved.
- The agent must run confined (lea is the reference containment):
unconfined agents are refused by default, see
[Confined agents](#confined-agents).
- Masking is best effort. PII detection quality: precision and recall per
detector and language on a synthetic bench, held to a CI baseline, in
[pii/testdata/bench/RESULTS.md](pii/testdata/bench/RESULTS.md); its
Known gaps section lists what the detectors miss most.

### Confined agents

The Locks' guarantees hold only if the agent cannot reach what protects
them. An agent run directly on your machine (plain `claude` or `codex` in
a terminal) runs as you: it can read the hub facades' private keys and
sign its own approvals, use Docker to open a lock's container and read its
credentials, and edit `lockfamily.yaml` or stop `lox run`. Unconfined, a
lock protects you against a **confused** agent, not against a
**prompt-injected** one.

So every lock client checks where it runs and says so in its `hello`; the
console decides. An agent is confined when all of these hold:

| Check | Reason code when it fails |
|---|---|
| it runs in a container (Linux only; on macOS a client is never confined) | `in_container` |
| no rootful runtime socket is reachable or mounted (`/var/run/docker.sock`, `/run/docker.sock`, `/run/podman/podman.sock`, `/run/containerd/containerd.sock`); a rootless Podman inside the container is fine | `no_host_runtime` |
| the Lock Family's state directory (`$XDG_STATE_HOME/lockfamily`) is absent or unreadable | `no_family_state` |
| the project's `.lockfamily/`, if any, is read-only | `lockfamily_read_only` |

The console adds what the kernel says: a client holding a group that owns
a runtime socket (`docker`) is unconfined (`runtime_group`), whatever it
reports, and a client too old to report is unconfined (`old_client`).

- By default an unconfined agent is refused: `refused: this agent does not
run confined (...); run it inside lea, or ask the human to set
unconfined = true on this non-production profile`.
- `unconfined = true` in a profile lets it in. It is part of the reviewed
policy: switching it on is a loosening you approve at the console. The
console then prints a red banner (`unconfined: this lock protects
against mistakes, not against a compromised agent`) at start and at
every unconfined connection, every audit record of that connection says
`"unconfined":true` with its reasons, and its hub tickets say so too.
- Never on production: a production profile with `unconfined = true` does
not start. A managed file with `require_confined_agent = true` refuses
unconfined agents whatever the profile says.
- No method is served on a connection before its `hello` is accepted, and
the decision is taken again at every request: a policy that becomes
production, or a managed file that comes to require a confined agent,
cuts an unconfined connection already open.

What this proves, and what it does not: the check makes the safe setup the
default and stops honest or confused agents run on the host. It does not
stop a host process that deliberately lies about where it runs: such a
process already runs as you and can drive Docker, so no lock-side check
could stop it. What makes the guarantees hold against prompt injection is
the containment itself: a confined agent (lea) cannot reach the runtime,
the keys or the console's terminal.

Details: [GUIDE.md § 6](GUIDE.md#6-config-and-policy-the-ai-tightens-the-human-loosens),
[§ 7](GUIDE.md#7-ipc-client-tunnel),
[§ 10](GUIDE.md#10-the-console-and-the-backend-seam) and
[§ 13](GUIDE.md#13-hub-tickets-ticket).

Expand Down
6 changes: 6 additions & 0 deletions audit/audit.go
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,12 @@ type Base struct {
// (package managed) when the record was made, so that an action is
// tied to the company policy it ran under.
Managed string `json:"managed,omitempty"`
// Unconfined marks every record of a connection from an agent that
// does not run confined (lockkit#133), served because its profile sets
// unconfined = true, or refused; UnconfinedReasons are the reason codes
// (package confine).
Unconfined bool `json:"unconfined,omitempty"`
UnconfinedReasons []string `json:"unconfined_reasons,omitempty"`
}

// AuditEvent implements Record.
Expand Down
3 changes: 2 additions & 1 deletion audit/audit_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,7 @@ func TestConcurrentWritesStayWholeLines(t *testing.T) {
func TestBaseFieldSet(t *testing.T) {
want := []string{
"approval", "approver", "code", "decision", "error", "event", "facade", "hub_sig", "inputs", "intent", "managed", "pattern", "peer_pid", "peer_uid", "peer_user",
"prev_hash", "profile", "reason", "span", "ticket", "ts", "warnings",
"prev_hash", "profile", "reason", "span", "ticket", "ts", "unconfined", "unconfined_reasons", "warnings",
}
l, err := Open(testProduct, t.TempDir())
if err != nil {
Expand All @@ -178,6 +178,7 @@ func TestBaseFieldSet(t *testing.T) {
Approval: "session", Pattern: "orders.phone", PeerUID: new(int), PeerPID: 4, PeerUser: "agent",
Code: "E_NO_LIMIT", Span: &refusal.Span{Line: 1, Col: 2, Token: "FROM"},
Ticket: "t", Approver: &ticket.Approver{ID: "u", Display: "d"}, Facade: "tty", HubSig: "s", Inputs: []string{"needle"}, Managed: "sha",
Unconfined: true, UnconfinedReasons: []string{"in_container"},
}
if err := l.Append(full); err != nil {
t.Fatal(err)
Expand Down
11 changes: 10 additions & 1 deletion client/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ import (
"time"

"github.com/DavidGodefroid/lockkit/config"
"github.com/DavidGodefroid/lockkit/confine"
"github.com/DavidGodefroid/lockkit/ipc"
"github.com/DavidGodefroid/lockkit/kit"
"github.com/DavidGodefroid/lockkit/sysconf"
Expand Down Expand Up @@ -155,6 +156,13 @@ func sharedDir(p kit.Product, instance string) (string, error) {
return filepath.Join(sys.SocketDir, instance), nil
}

// confinement is the client's self-check (confine.Check), run once per
// process and sent in every hello; tests replace it.
var confinement = sync.OnceValue(func() ipc.Confinement {
r := confine.Check(confine.RealEnv())
return ipc.Confinement{Confined: r.Confined, Reasons: r.Reasons}
})

// dialUnix opens the socket; tests replace it to watch the connection.
var dialUnix = func(path string) (net.Conn, error) { return net.Dial("unix", path) }

Expand Down Expand Up @@ -282,7 +290,8 @@ func (c *Client) handshake(ctx context.Context) error {
name = c.product.Name
}
var hr ipc.HelloResult
if err := c.call(ctx, ipc.MethodHello, ipc.HelloParams{ProtocolMajor: ipc.ProtocolMajor, Client: name}, &hr); err != nil {
conf := confinement()
if err := c.call(ctx, ipc.MethodHello, ipc.HelloParams{ProtocolMajor: ipc.ProtocolMajor, Client: name, Confinement: &conf}, &hr); err != nil {
return err
}
if !ipc.Compatible(hr.ProtocolMajor) {
Expand Down
6 changes: 6 additions & 0 deletions client/client_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ type fakeConsole struct {
mu sync.Mutex
methods []string
clients []string
confs []*ipc.Confinement
}

func (f *fakeConsole) seen() []string {
Expand Down Expand Up @@ -88,6 +89,7 @@ func startFake(t *testing.T, cwd, profile string, handler func(req ipc.Request)
_ = json.Unmarshal(req.Params, &hp)
f.mu.Lock()
f.clients = append(f.clients, hp.Client)
f.confs = append(f.confs, hp.Confinement)
f.mu.Unlock()
resp = result(req.ID, ipc.HelloResult{ProtocolMajor: ipc.ProtocolMajor, ConsoleVersion: "9.9.9", Profile: profile})
} else {
Expand Down Expand Up @@ -224,6 +226,10 @@ func TestCallSendsHelloFirstAndDecodes(t *testing.T) {
if fake.clients[0] != "lockmq" {
t.Fatalf("hello client = %q", fake.clients[0])
}
// The hello carries the client's confinement report.
if c := fake.confs[0]; c == nil || c.Confined != confinement().Confined {
t.Fatalf("hello confinement = %+v, want %+v", c, confinement())
}
}

func TestCallReturnsRPCError(t *testing.T) {
Expand Down
12 changes: 11 additions & 1 deletion config/policy.go
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,13 @@ type Base struct {
TicketsPerWindow int `json:"tickets_per_window,omitempty"`
TicketWindow time.Duration `json:"ticket_window,omitempty"`
MaxPending int `json:"max_pending,omitempty"`
// Unconfined lets an agent that does not run confined use the profile
// (lockkit#133; profile key unconfined = true): the lock then protects
// against mistakes, not against a compromised agent. Never on a
// production profile (the console refuses to start). Part of the
// policy and its fingerprint: switching it on is a loosening. Omitted
// when false, so that the fingerprints of existing policies hold.
Unconfined bool `json:"unconfined,omitempty"`
}

// TicketLimits are the hub client's limits of b (hubclient.Limits,
Expand Down Expand Up @@ -151,7 +158,7 @@ func ConnectionField(field string) bool {
// tls_cert or tls_key, production true→false, any change of the ssh table
// (a credentials mode other than ask for the bastion), a longer session
// limit, a longer or removed credentials_ttl, more tickets per window, a
// shorter ticket window or more pending tickets.
// shorter ticket window or more pending tickets, unconfined false→true.
func DiffBase(a, c Base) []Change {
var out []Change
same := func(field, o, n string) {
Expand Down Expand Up @@ -215,6 +222,9 @@ func DiffBase(a, c Base) []Change {
out = append(out, Change{Field: "limits.max_pending", Old: strconv.Itoa(a.MaxPending), New: strconv.Itoa(c.MaxPending),
Loosens: cl.MaxPending > al.MaxPending})
}
if a.Unconfined != c.Unconfined {
out = append(out, Change{Field: "unconfined", Old: strconv.FormatBool(a.Unconfined), New: strconv.FormatBool(c.Unconfined), Loosens: c.Unconfined})
}
if a.CredentialsTTL != c.CredentialsTTL {
out = append(out, Change{Field: "credentials_ttl", Old: a.CredentialsTTL.String(), New: c.CredentialsTTL.String(),
Loosens: LooserLimit(int64(a.CredentialsTTL), int64(c.CredentialsTTL))})
Expand Down
21 changes: 21 additions & 0 deletions config/policy_test.go
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
package config

import (
"encoding/json"
"errors"
"io/fs"
"os"
"path/filepath"
"reflect"
"runtime"
"strings"
"testing"
"time"

Expand Down Expand Up @@ -196,3 +198,22 @@ func TestConnectionField(t *testing.T) {
}
}
}

// TestUnconfined: the profile key unconfined is in the fingerprint,
// switching it on loosens and off tightens; false keeps the fingerprint
// of a policy written before the key existed.
func TestUnconfined(t *testing.T) {
off, on := Base{User: "u", Credentials: CredentialsAsk}, Base{User: "u", Credentials: CredentialsAsk, Unconfined: true}
if Fingerprint(off) == Fingerprint(on) {
t.Fatal("unconfined does not change the fingerprint")
}
if b, _ := json.Marshal(off); strings.Contains(string(b), "unconfined") {
t.Fatalf("unconfined = false is encoded: %s", b)
}
if ch := DiffBase(off, on); len(ch) != 1 || ch[0].Field != "unconfined" || !ch[0].Loosens {
t.Fatalf("on: %+v", ch)
}
if ch := DiffBase(on, off); len(ch) != 1 || ch[0].Field != "unconfined" || ch[0].Loosens {
t.Fatalf("off: %+v", ch)
}
}
Loading
Loading